taro-ui-guide

Taro UI 使用指南

基于 Taro 3+ 的多端 React 组件库。组件均以 At 前缀导出（如 AtButton），样式与逻辑分离，需单独引入 SCSS。

官方文档：https://jd-opensource.github.io/taro-ui/#/
源码：packages/taro-ui/（本 monorepo）

何时使用本 Skill

• 在 Taro 项目中集成、配置或排查 taro-ui
• 选择/组合组件、查 Props、写示例页面
• 自定义主题、国际化、按需加载
• 在本仓库内开发/修复 packages/taro-ui 组件

版本与安装

Taro 版本	taro-ui 版本
< 3	taro-ui@2.3.4
≥ 3	taro-ui@latest（当前 monorepo 为 3.x）

pnpm add taro-ui
# 或 npm install taro-ui@latest

Peer 依赖：@tarojs/taro、@tarojs/components、@tarojs/react、react、react-dom（≥16.13）。RN 端另需 react-native、react-native-modal（可选）。

微信小程序需基础库 ≥ 2.2.3（globalClass 与样式穿透）。

Taro 项目必配项

在消费方项目的 config/index.ts（或 config/index.js）中：

1. H5 编译 node_modules 中的 taro-ui

h5: {
  esnextModules: ['taro-ui']
}

2. Taro 3.5+ 关闭对 taro-ui 的 prebundle（否则 @tarojs/components 可能未打进 bundle，页面异常）

compiler: {
  type: 'webpack5',
  prebundle: {
    exclude: ['taro-ui']
  }
}

样式引入

样式在 taro-ui/dist/style/，不会随 JS 自动注入，必须显式引入。

全量（开发/原型）

入口或 app.scss：

import 'taro-ui/dist/style/index.scss'

@import 'taro-ui/dist/style/index.scss';

按需（推荐生产）

页面/全局 SCSS 按组件名引入（AtButton → button.scss）：

@import 'taro-ui/dist/style/components/button.scss';

或用 babel-plugin-import（见 docs/docs/guide/quickstart.md）：

// babel.config.js plugins
['import', {
  libraryName: 'taro-ui',
  customName: name => `taro-ui/lib/components/${name.slice(3)}`,
  customStyleName: name => `taro-ui/dist/style/components/${name.slice(3)}.scss`
}, 'taro-ui']

At 前缀去掉后即为目录名：AtActionSheet → action-sheet。

组件使用模式

基础引入

import { View } from '@tarojs/components'
import { AtButton } from 'taro-ui'

export default function Page() {
  return (
    <View>
      <AtButton type="primary" onClick={() => {}}>
        按钮
      </AtButton>
    </View>
  )
}

公共 Props（AtComponent）

多数组件支持：

Prop	说明
className	外层类名（小程序可用 globalClass 覆盖内部 BEM 类）
customStyle	内联样式，string 或 CSSProperties
children	子节点

类型定义：packages/taro-ui/types/base.d.ts。

复合组件

按文档组合子组件，例如：

• AtModal + AtModalHeader / AtModalContent / AtModalAction
• AtList + AtListItem
• AtTabs + AtTabsPane
• AtActionSheet + AtActionSheetItem

按组件查阅：references/README.md（如 references/button.md）。仅在使用该组件时打开对应文件。

受控与回调