Taroify

Taroify#

资源概述#

Taroify 是移动端组件库 Vant 的 Taro React 版本，由 mallfoundry 团队开发维护。项目创建于 2021 年 4 月，截至 2026 年 7 月已发布 165 个 npm 版本（最新 v1.0.0），GitHub 星标 1085+。Taroify 基于 Vant 设计语言，为使用 Taro 框架的开发者提供与 Vant 近似一致的 API 接口，支持微信小程序、支付宝小程序、抖音小程序及 H5 多端。采用 Monorepo 架构组织，核心包 @taroify/core 提供 70+ 高质量组件，另有 @taroify/icons（图标）、@taroify/icons-react（React 图标）等独立包。所有组件使用 TypeScript 编写，单元测试覆盖率超过 90%，组件平均体积小于 1KB（min+gzip）。

设计规范#

Taroify 遵循 Vant 设计语言规范，视觉风格与 Vant 保持一致：

主题系统：内置 700+ 个 CSS/Sass 主题变量，通过覆盖变量即可定制全局风格
色彩体系：主色 #1989fa（Vant Blue），支持 primary / info / danger / warning / success 五种语义色
字体规范：使用 px 单位，Taro 自动转换为 rpx（小程序端）或 rem（H5 端）
组件分类：
- 基础组件：Button、Cell、Icon、Image、Layout、Popup、Style
- 表单组件：Form、Field、Input、Checkbox、Radio、Switch、Slider、Stepper、Rate、Uploader、Search、Calendar
- 反馈组件：ActionSheet、Dialog、Toast、Notify、Loading、PullRefresh、SwipeCell
- 展示组件：Collapse、Empty、List、Card、Tag、Badge、Skeleton、Divider、Steps、TreeSelect
- 导航组件：Tabs、Tabbar、Segmented、Backtop、FloatingBubble、Grid、Sticky、Sidebar、Navbar
暗黑模式：通过 ThemeProvider 组件一键切换暗黑主题
国际化：内置多语言支持（@taroify/core 内置）

审核规范#

Taroify 是第三方 UI 组件库，不涉及平台审核。使用 Taroify 构建的小程序仍需遵循目标平台（微信/支付宝/抖音等）的审核规范。注意事项：

包体影响：全量引入会增加包体，推荐使用按需引入（babel-plugin-import）减小体积
样式兼容：部分 CSS 属性在低版本基础库中不支持（如 position: sticky），需测试目标平台兼容性
H5 端注意：Taro.chooseImage 等 API 在 H5 端行为与小程序不同，组件已做兼容处理

开发指南#

快速上手#

code

# 安装核心包
npm install @taroify/core

# 或使用 yarn / pnpm
yarn add @taroify/core
pnpm add @taroify/core

# 安装图标包（可选）
npm install @taroify/icons

使用组件：

code

import { Button } from "@taroify/core"
import "@taroify/core/button/style"

export default function Index() {
  return (
    <Button color="primary" onClick={() => console.log("clicked")}>
      开始使用 Taroify
    </Button>
  )
}

配置按需引入（推荐，减小构建体积）：

code

// babel.config.js
module.exports = {
  presets: [
    ['taro', {
      framework: 'react',
      ts: true,
    }]
  ],
  plugins: [
    ['import', {
      libraryName: '@taroify/core',
      libraryDirectory: '',
      style: name => `${name}/style`
    }, '@taroify/core']
  ]
}

主题定制：

code

import { ConfigProvider } from "@taroify/core"

// 通过 CSS 变量覆盖主题
<ConfigProvider
  themeVars={{
    buttonPrimaryBackgroundColor: "#07c160",
    buttonPrimaryBorderColor: "#07c160",
  }}
>
  <Button color="primary">自定义主色按钮</Button>
</ConfigProvider>

常见陷阱#

样式未引入：每个组件需要单独引入样式文件（@taroify/core/[component]/style），按需引入插件会自动处理
Taro 版本兼容：Taroify 依赖 Taro 3.x+，低版本 Taro 可能出现样式或 API 不兼容
小程序端 rpx 转换：Taroify 使用 px 单位，Taro 编译时会自动转为 rpx，但配置 designWidth 需为 750
H5 端适配：部分交互组件（如 ActionSheet）在 H5 端的遮罩层行为与小程序不同
React 版本要求：需要 React 16.8+（Hooks 支持）

从 Vant 迁移#

Taroify 的 API 设计参考 Vant，但并非完全一致：

Vant（Vue）→ Taroify（React）：事件用 onClick 替代 @click，用 props 替代 v-model
组件名保持一致：<van-button> → <Button>
大部分属性名和值保持一致，少数差异参考官方迁移文档

生态资源#

社区资源#

官方文档：https://taroify.github.io/taroify.com/
在线演示：https://taroify.github.io/taroify.com/h5/index.html
GitHub Discussions：https://github.com/mallfoundry/taroify/discussions
npm 包：@taroify/core、@taroify/icons

版本更新#

v1.0.0（最新稳定版）：正式发布 1.0 里程碑，API 稳定
v0.9.x：RC 阶段，修复大量兼容性问题，新增 Segmented、Sidebar 等组件
v0.8.x：完善表单组件，新增 Calendar、Uploader 改进
npm 已发布 165 个版本（2021-04 至今），持续迭代中
Monorepo 架构：核心包 @taroify/core、图标包 @taroify/icons，按需安装
GitHub 1085+ stars、122+ forks，社区活跃（Discussions 开放）

详细文档

Taroify#

资源概述#

设计规范#

审核规范#

开发指南#

快速上手#

常见陷阱#

从 Vant 迁移#

生态资源#

推荐框架#

相关 UI 库#

社区资源#

版本更新#