taro-ui-guide

name taro-ui-guide description Guides installation, Taro config, styling, and usage of taro-ui (At* components) for WeChat/Alipay/H5/RN. Use when building Taro apps with taro-ui, picking components, theming, i18n, or modifying packages/taro-ui source. 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 ）。 仅在使用该组件时 打开对应文件。 受控与回调 开关类： 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 自定义主题 SCSS 变量 （推荐）：在引入默认样式 之前 覆盖变量，再 @import 全量样式。 $color-brand : #6190e8 ; @import 'taro-ui/dist/style/index.scss' ; 变量表： packages/taro-ui/src/style/variables/default.scss 。 globalClass ：在 Page 级 SCSS 用 .my-btn.at-button { } 覆盖（自定义组件内无效）。 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 工作流 确认场景 ：消费方 Taro 项目 vs 本 monorepo 源码修改。 查 API ： references/<slug>.md → types/*.d.ts → docs/docs/components/*.md 。 写用法 ： import { AtX } from 'taro-ui' + 对应 dist/style/components/x.scss 。 排查样式缺失 ：是否引入 SCSS；H5 是否配置 esnextModules ；是否配置 prebundle.exclude 。 排查小程序样式 ：基础库版本、 globalClass 、BEM 类名是否与文档一致。 延伸阅读 references/README.md — 组件索引（按维度渐进披露） docs/docs/guide/quickstart.md — 快速上手与 babel 按需 docs/docs/guide/customize-theme.md — 主题详解