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	[email protected]
≥ 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）。仅在使用该组件时打开对应文件。

受控与回调

• 开关类：open / isOpened + onClick / onClose（以各组件 types/*.d.ts 为准）
• 表单类：AtForm 包裹 AtInput、AtSwitch 等，注意 formType、校验文案
• 环境判断：组件内部常用 Taro.getEnv() 区分 WEB / WEAPP / ALIPAY

查 Props 时优先读 references/<slug>.md，其次 packages/taro-ui/types/<component>.d.ts 与 docs/docs/components/<name>.md。

命令式 API：AtMessage

页面需挂载 <AtMessage />，再通过 Taro.atMessage 调用：

import Taro from '@tarojs/taro'
import { AtMessage } from 'taro-ui'

// render 中: <AtMessage />
Taro.atMessage({ message: '提示', type: 'success', duration: 3000 })
// type: info | success | error | warning

AtToast 为声明式：isOpened、text、status、onClose。

国际化 ConfigProvider

import { ConfigProvider, AtLoadMore, enUS } from 'taro-ui'

export default function App({ children }) {
  return (
    <ConfigProvider locale={enUS}>
      {children}
    </ConfigProvider>
  )
}

• 内置：zhCN（默认）、enUS
• locale 与默认包深合并，可只覆盖部分 key（如 LoadMore.moreText）
• 优先级：组件 props > ConfigProvider.locale > 默认 zhCN

自定义主题

1. SCSS 变量（推荐）：在引入默认样式之前覆盖变量，再 @import 全量样式。

$color-brand: #6190e8;
@import 'taro-ui/dist/style/index.scss';

变量表：packages/taro-ui/src/style/variables/default.scss。

2. globalClass：在 Page 级 SCSS 用 .my-btn.at-button { } 覆盖（自定义组件内无效）。

3. customStyle：仅部分组件支持，优先用前两种方式。

AtSlider、AtSwitch 暂不支持 SCSS 变量覆盖主题。

在本仓库开发 taro-ui

pnpm install          # 根目录，仅允许 pnpm
pnpm build:ui         # 构建 packages/taro-ui → dist/
pnpm --filter demo dev:h5
pnpm --filter demo dev:weapp
pnpm --filter docs dev

组件实现路径：

内容	路径
组件实现	packages/taro-ui/src/components/<name>/
类型	packages/taro-ui/types/<name>.d.ts
样式	packages/taro-ui/src/style/components/<name>.scss
导出	packages/taro-ui/src/index.ts
RN 实现	packages/taro-ui/rn/components/
单测	packages/taro-ui/test/components/

新增/修改组件：同步更新 src/index.ts、类型文件、样式、test 快照；提交信息格式 feat(ComponentName): ...（见 .github/CONTRIBUTING.md）。

Agent 工作流

1. 确认场景：消费方 Taro 项目 vs 本 monorepo 源码修改。
2. 查 API：references/<slug>.md → types/*.d.ts → docs/docs/components/*.md。
3. 写用法：import { AtX } from 'taro-ui' + 对应 dist/style/components/x.scss。
4. 排查样式缺失：是否引入 SCSS；H5 是否配置 esnextModules；是否配置 prebundle.exclude。
5. 排查小程序样式：基础库版本、globalClass、BEM 类名是否与文档一致。

延伸阅读

• references/README.md — 组件索引（按维度渐进披露）
• docs/docs/guide/quickstart.md — 快速上手与 babel 按需
• docs/docs/guide/customize-theme.md — 主题详解