For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/zh/guide/getting-started.md.
v0.0.57
  • 简体中文
  • 快速开始

    React 和 React DOM 最低需要 18.2,同时兼容 React 19,两者的 peer dependency 范围均为 ^18.2.0 || ^19.0.0。日期组件使用的 dayjs 是普通依赖,会自动安装。使用你偏好的包管理器安装 tao-ui。

    npm
    yarn
    pnpm
    bun
    deno
    npm install @rockshin/tao-ui

    添加 Provider

    在应用根部包裹一次 TaoProvider。组件会继承尺寸、禁用状态与主题模式等设置。

    import { Button, TaoProvider } from '@rockshin/tao-ui';
    
    export default function App() {
      return (
        <TaoProvider size="medium">
          <Button>继续</Button>
        </TaoProvider>
      );
    }

    按组件引入

    按组件入口引入时,只加载对应组件及其依赖的样式,并自动包含公共主题样式,无需额外导入 CSS。现有根入口继续可用,会包含全部组件样式。

    import { Button, type ButtonProps } from '@rockshin/tao-ui/button';
    import { TaoProvider } from '@rockshin/tao-ui/provider';

    入口使用短横线命名,例如 /input-number、/range-picker、/form-layout。同组导出共用入口:CheckboxGroup 使用 /checkbox,HeadlessInputNumber 使用 /number-input。

    控制字段值

    Input、Textarea、InputNumber、Select、DatePicker 和 RangePicker 中,显式传入 value={undefined} 表示受控空值。非受控字段应省略 value,使用 defaultValue 设置初始值。表单中可通过 form.setFieldsValue({ field: undefined }) 清空字段,无需重新挂载控件。

    使用深色模式

    在 Provider 上设置主题模式。通过 Portal 渲染的组件也会继承同一主题。

    <TaoProvider theme={{ mode: 'dark' }}>
      <App />
    </TaoProvider>

    继续阅读 Button 组件。

    无障碍与 ARIA

    使用 FormField 或 Form.Item 为控件关联标签、说明与错误信息。Input、Textarea、InputNumber、Select、Checkbox、Radio、Switch、DatePicker 和 RangePicker 会将字段 ARIA 属性传递到实际交互元素;CheckboxGroup 与 RadioGroup 支持分组标签及错误关联。占位符不能代替字段标签。

    <FormField label="出行日期" required error="请选择有效日期">
      <RangePicker placeholder={['开始日期', '结束日期']} />
    </FormField>

    Radio 将 aria-required 转为原生 required,显式 required prop 优先。分组选项使用各自的原生禁用状态,保留子项 disabled={false} 的覆盖行为。

    桌面日期输入框使用 combobox 语义,按方向下键打开日历并移入焦点,Escape 关闭并返回输入框。RangePicker 的两个输入框组合显式 ARIA 标签和各自占位符作为名称,请提供可区分的起止文案;原生 label 可分别关联 id 和 ${id}-end。日历、月份、年份、时间选项均暴露选中态。

    • Tabs 使用 aria-label 或 aria-labelledby 命名标签组;文本面板可通过 Tab 聚焦。
    • Modal、Drawer、Popover 使用可见 title 或显式 ARIA 名称;Popconfirm 自动关联问题和说明。
    • Spinner 可用 aria-label 自定义加载名称;无提示文案时默认为 Loading,包裹内容在加载期间(包括延迟显示阶段)标记 aria-busy。
    • 仅含图标的按钮仍需要应用提供有意义的名称。

    自动测试验证 React 18/19 的 DOM 语义和键盘行为,应用仍需对组合后的页面进行浏览器及读屏检查。交互依据参考 WAI-ARIA 日期组合框示例 和 Tabs 模式。