▶_MiniApp Toolkit

vantui

工具

基于 Vant Weapp 视觉规范打造的 Taro 3 + React 组件库,一套代码同时运行于微信/支付宝/百度/抖音小程序及 H5 端。AntmJS 团队出品,158 个 npm 版本高频迭代,65+ 高质量组件,TypeScript 原生编写

taroreactui-libraryvanttypescriptminiprogramantmjs

详细文档

资源概述#

@antmjs/vantuiAntmJS 团队开发的 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 Stars832⭐
Forks108
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 支持#

code
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 库,非平台类资源)

开发指南#

安装#

code
# npm
npm install @antmjs/vantui

# pnpm
pnpm add @antmjs/vantui

配置按需引入(推荐)#

babel.config.js 中配置:

code
module.exports = {
  presets: [
    ['taro', {
      framework: 'react',
      ts: true,
      compiler: 'webpack5'
    }]
  ],
  plugins: [
    [
      'import',
      {
        libraryName: '@antmjs/vantui',
        libraryDirectory: 'es',
        style: () => false  // 样式已内联
      },
      '@antmjs/vantui'
    ]
  ]
}

基础用法#

code
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 用法(函数组件)#

code
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)}
      />
    </>
  )
}

主题定制#

code
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>
  )
}

常见陷阱#

  1. React 限定:vantui 仅支持 React,Vue3 请使用 wot-design-uni 或 sard-uniapp
  2. 样式隔离:小程序端样式隔离需要配置 addGlobalClass: true(页面配置)
  3. babel-plugin-import 版本:必须使用 babel-plugin-import@1.x,2.x 版本配置方式不同
  4. H5 端适配:部分弹层组件在 H5 端需要额外处理 position: fixed 的滚动穿透问题
  5. Taro 版本兼容:vantui v3.x 需要 Taro 3.6+,低版本 Taro 请使用 vantui v2.x

生态资源#

AntmJS 生态#

vantui 是 AntmJS 团队的核心开源项目,该团队还维护:

项目说明
antm-business业务组件库扩展
antm-utilsJavaScript 工具函数库

对比参考#

UI 库框架Stars多端ReactVue3维护状态
vantui (AntmJS)Taro 3832⭐✅ 5+端🟢 活跃
TaroifyTaro 31087⭐🟢 活跃
NutUI UniAppuni-app556⭐🟢 活跃
Vant Weapp微信原生18423⭐🟢 活跃
wot-design-uniuni-app2278⭐🟢 活跃

选择建议#

场景推荐
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 设计