
vantui
工具基于 Vant Weapp 视觉规范打造的 Taro 3 + React 组件库,一套代码同时运行于微信/支付宝/百度/抖音小程序及 H5 端。AntmJS 团队出品,158 个 npm 版本高频迭代,65+ 高质量组件,TypeScript 原生编写
taroreactui-libraryvanttypescriptminiprogramantmjs
详细文档
资源概述#
@antmjs/vantui 是 AntmJS 团队开发的 Taro 3 React 组件库,基于 Vant Weapp 的视觉规范打造。一套代码同时运行于微信/支付宝/百度/抖音小程序及 H5 端,为 Taro React 开发者提供高质量的 UI 组件解决方案。
核心特性#
- 65+ 高质量组件:覆盖基础组件、表单、展示、导航、反馈等全场景
- Vant 视觉规范:与 Vant Weapp 保持一致的设计语言,降低设计协同成本
- TypeScript 原生编写:完整类型定义,IDE 智能提示
- 多端兼容:微信/支付宝/百度/抖音/QQ 小程序 + H5
- 主题定制:CSS Variables 方案,支持暗黑模式与自定义主题
- 按需引入:支持 babel-plugin-import,自动引入组件样式
- 高频迭代:158 个 npm 版本,持续优化适配各平台
项目数据#
| 指标 | 数值 |
|---|---|
| GitHub Stars | 832⭐ |
| Forks | 108 |
| npm 版本数 | 158(latest: 3.7.0) |
| npm 最后修改 | 2025-09-04 |
| 最后推送 | 2026-06-03 |
| 许可证 | MIT |
| 创建年份 | 2021 |
设计规范#
组件分类#
| 分类 | 组件 |
|---|---|
| 基础组件 | Button、Cell、Icon、Image、Col/Row、Popup |
| 表单组件 | Field、Checkbox、Radio、Switch、Stepper、Rate、Slider、Search、DatetimePicker、Calendar |
| 展示组件 | Tag、Badge、Card、Skeleton、Empty、ImagePreview、Collapse、TreeSelect |
| 导航组件 | Tabbar、NavBar、Tabs、Sidebar、DropdownMenu、IndexBar、Pagination |
| 反馈组件 | Toast、Dialog、Loading、ActionSheet、Notify、SwipeCell、PullRefresh |
| 业务组件 | AddressList、AddressEdit、Area、Card、CouponList、GoodsAction、SubmitBar |
视觉规范#
vantui 完全继承 Vant Weapp 的设计系统:
- 主色调:
#1989fa(蓝色)为默认主题色 - CSS Variables:所有样式通过 CSS 变量驱动,支持运行时主题切换
- 暗黑模式:内置
ConfigProvider组件一键切换暗黑主题 - 尺寸单位:
px为主,通过 Taro 的样式适配方案自动转换
TypeScript 支持#
import { Button, Cell, Toast } from '@antmjs/vantui'
// 组件 Props 类型完整导出
import type { ButtonProps } from '@antmjs/vantui'
const props: ButtonProps = {
type: 'primary',
size: 'small',
loading: false,
onClick: (e) => console.log('clicked', e)
}
审核规范#
不适用(开源 UI 库,非平台类资源)
开发指南#
安装#
# npm
npm install @antmjs/vantui
# pnpm
pnpm add @antmjs/vantui
配置按需引入(推荐)#
在 babel.config.js 中配置:
module.exports = {
presets: [
['taro', {
framework: 'react',
ts: true,
compiler: 'webpack5'
}]
],
plugins: [
[
'import',
{
libraryName: '@antmjs/vantui',
libraryDirectory: 'es',
style: () => false // 样式已内联
},
'@antmjs/vantui'
]
]
}
基础用法#
import { Component } from 'react'
import { View } from '@tarojs/components'
import { Button, Cell, CellGroup, Toast } from '@antmjs/vantui'
export default class Index extends Component {
state = {
show: false
}
showToast = () => {
this.setState({ show: true })
}
render() {
const { show } = this.state
return (
<View className="page">
<CellGroup title="基础示例">
<Cell title="单元格" value="内容" />
<Cell title="单元格" value="内容" label="描述信息" border />
</CellGroup>
<View style={{ padding: '16px' }}>
<Button
type="primary"
block
onClick={this.showToast}
>
显示 Toast
</Button>
</View>
<Toast
visible={show}
message="操作成功"
duration={2000}
onClose={() => this.setState({ show: false })}
/>
</View>
)
}
}
Hooks 用法(函数组件)#
import { useState } from 'react'
import { Button, Dialog } from '@antmjs/vantui'
export default function MyPage() {
const [visible, setVisible] = useState(false)
return (
<>
<Button type="danger" onClick={() => setVisible(true)}>
删除
</Button>
<Dialog
visible={visible}
title="确认删除"
message="删除后不可恢复,确定继续吗?"
showCancelButton
onConfirm={() => {
// 执行删除逻辑
setVisible(false)
}}
onCancel={() => setVisible(false)}
/>
</>
)
}
主题定制#
import { ConfigProvider } from '@antmjs/vantui'
// CSS 变量定制
const themeVars = {
buttonPrimaryBackgroundColor: '#07c160',
buttonPrimaryBorderColor: '#07c160',
cellBackgroundColor: '#f7f8fa'
}
export default function App({ children }) {
return (
<ConfigProvider themeVars={themeVars}>
{children}
</ConfigProvider>
)
}
常见陷阱#
- React 限定:vantui 仅支持 React,Vue3 请使用 wot-design-uni 或 sard-uniapp
- 样式隔离:小程序端样式隔离需要配置
addGlobalClass: true(页面配置) - babel-plugin-import 版本:必须使用
babel-plugin-import@1.x,2.x 版本配置方式不同 - H5 端适配:部分弹层组件在 H5 端需要额外处理
position: fixed的滚动穿透问题 - Taro 版本兼容:vantui v3.x 需要 Taro 3.6+,低版本 Taro 请使用 vantui v2.x
生态资源#
AntmJS 生态#
vantui 是 AntmJS 团队的核心开源项目,该团队还维护:
| 项目 | 说明 |
|---|---|
| antm-business | 业务组件库扩展 |
| antm-utils | JavaScript 工具函数库 |
对比参考#
| UI 库 | 框架 | Stars | 多端 | React | Vue3 | 维护状态 |
|---|---|---|---|---|---|---|
| vantui (AntmJS) | Taro 3 | 832⭐ | ✅ 5+端 | ✅ | ❌ | 🟢 活跃 |
| Taroify | Taro 3 | 1087⭐ | ✅ | ✅ | ❌ | 🟢 活跃 |
| NutUI UniApp | uni-app | 556⭐ | ✅ | ❌ | ✅ | 🟢 活跃 |
| Vant Weapp | 微信原生 | 18423⭐ | ❌ | ❌ | ❌ | 🟢 活跃 |
| wot-design-uni | uni-app | 2278⭐ | ✅ | ❌ | ✅ | 🟢 活跃 |
选择建议#
| 场景 | 推荐 |
|---|---|
| Taro + React 项目 | vantui 或 Taroify |
| Taro + Vue3 项目 | NutUI(Taro 适配) |
| uni-app Vue3 项目 | wot-design-uni 或 NutUI UniApp |
| 微信原生小程序 | Vant Weapp |
| 需要与 Vant 设计一致 | vantui / Taroify(二选一) |
版本更新#
- v3.7.0(2025-09):TypeScript 类型优化,修复小程序端样式兼容问题
- v3.6.0(2025-06):新增 Skeleton 骨架屏组件,优化 DatetimePicker 性能
- v3.5.0(2025-03):新增暗黑模式 ConfigProvider,适配 Taro 4.0
- v3.4.0(2024-12):新增 PullRefresh、SwipeCell 交互组件
- v3.0.0(2024-06):重大升级,TypeScript 重写,API 对齐 Vant 4 设计