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/components/tao-provider.md.
v0.0.57
  • 简体中文
  • TaoProvider

    配置@rockshin/tao-ui

    为组件树提供主题 seed、组件 token、尺寸、密度与禁用状态。

    何时使用

    应用或局部区域需要统一配置 tao-ui 组件时使用 TaoProvider。

    推荐

    • 在应用根部只设置稳定的全局 seed。
    • 局部覆盖使用嵌套 Provider。
    • Portal 内容应继承同一主题作用域。

    避免

    • 不要在每个组件外重复创建 Provider。

    代码演示

    基础用法

    TSX

    全局尺寸

    TSX

    品牌 Token 与组件 Token

    TSX

    深色模式、紧凑密度与隔离

    TSX

    全局外观

    统一设置表单控件的外观,再按需要局部覆盖。

    TSX

    品牌色

    在同一套组件中切换品牌色,保持状态色与对比关系。

    Default (Anthropic-neutral)
    oklch(0.205 0.01 70)
    Tag
    Vercel Black
    oklch(0.145 0 0)
    Tag
    Linear Indigo
    oklch(0.52 0.19 275)
    Tag
    Stripe Purple
    oklch(0.55 0.22 300)
    Tag
    Supabase Green
    oklch(0.62 0.17 155)
    Tag
    Notion Orange
    oklch(0.68 0.17 45)
    Tag
    TSX

    语义颜色

    分别配置成功、警告、错误等语义颜色,避免复用同一种颜色表达所有状态。

    successDeployedPassedReady
    warningDegradedPreviewDraft
    errorFailedBlockedBroken

    ring color follows colorError token

    TSX

    圆角尺度

    根圆角会派生不同尺寸的圆角,比较整组控件的变化。

    sharp · 2px
    r-2
    Tag
    default (10) · 10px
    r-10
    Tag
    rounded · 16px
    r-16
    Tag
    pill-ish · 24px
    r-24
    Tag
    TSX

    嵌套与隔离

    嵌套 Provider 可继承或重置主题,局部配置不会影响外层。

    outer · purple / large
    outer
    Tag
    inner · orange, size inherited (large)
    inner
    Tag
    inner · color inherited (purple), size=small
    inner
    Tag
    TSX

    弹层主题继承

    打开下拉弹层,确认通过 Portal 渲染的内容仍使用所属 Provider 的主题。

    Select popup portals to body but still reads the closest TaoProvider — both dropdowns below should match their parent primary.
    TSX

    动态切换主题

    通过状态切换主题参数,真实控件与弹层即时响应。

    active · Default (Anthropic-neutral)
    live
    Tag
    TSX

    布局透明

    Provider 不额外改变布局结构,组件仍按父容器的布局规则排列。

    Children of a single TaoProvider must land in separate grid columns. If the wrapper collapsed layout, both cards would stack in column 1.
    Sidebar
    col 1 · 200px
    Main
    col 2 · 1fr — buttons below should feel indigo
    TSX

    组件级 Token

    只覆盖目标组件的 Token,其他组件继续使用全局主题。

    theme.components.Button — pill radius + custom padding/font weight
    TSX

    紧凑密度

    紧凑模式调整间距与控件密度,字体保持主题定义的字号。

    theme.compact: control height 32→28, paddings one notch tighter
    Default
    Compact
    TSX

    从右到左布局

    通过 TaoProvider 的 direction="rtl" 或外围 HTML 元素的 dir="rtl" 设置方向。组件继承局部方向,弹层挂载到 Portal 后仍沿用触发区域的方向。组件显式 direction 或嵌套 Provider 可以覆盖继承值;Carousel 使用已有的 rtl 属性。语言与方向独立设置,bottomLeft 等显式弹层位置仍表示物理左侧。

    TSX

    17 种语言与地区格式

    切换语言可更新组件默认文案、日期与数字格式。日期默认仍使用原有 ISO 格式;此例用 format="L" 显式选择地区格式。数字输入回调始终返回规范 ASCII 十进制字符串。调用方提供的业务标签由应用自行翻译。

    1 234 567,89
    Aucune donnée
    TSX

    API

    useTaoInternalConfig

    Internal component access for token propagation through third-party portals.

    属性说明类型默认值

    useTaoDirection

    Resolve DOM inheritance at a component's source, before it creates portals.

    属性说明类型默认值

    useTaoToken

    **antd theme.useToken counterpart, zero-runtime edition: returns every design token as a var(--tao-*) reference string, so custom components can stay visually consistent with tao-ui and still resolve in the browser against the live theme (dark mode, seed overrides, compact density):

    const { token } = useTaoToken();
    <div style={{ borderRadius: token['--tao-radius-lg'], padding: token['--tao-padding-lg'] }} />
    ```**
    
      |属性|说明|类型|默认值|
    |:---:|:---:|:---:|:---:|
      
        
    
      ### TaoPortalScope
    
      **Re-establishes the theme token scope inside a portal. Floating components
    portal their popup to document.body, escaping the `[data-tao-provider]`
    element that carries custom token overrides; wrapping the portal content in
    this component re-applies those overrides so colors/sizes stay consistent.
    
    With `asChild`, merges the tokens onto the immediate child (via Radix Slot)
    instead of adding a wrapper div. Prefer `asChild` inside portals whose Radix
    primitive does NOT Presence-gate its Portal (notably `@radix-ui/react-select`
    — see `SelectPortal` in `node_modules/@radix-ui/react-select`): the wrapper
    div would otherwise render even while the popup is closed, leaving a ghost
    `<div data-tao-provider>` in the body for every mounted-but-closed Select.**
    
      |属性|说明|类型|默认值|
    |:---:|:---:|:---:|:---:|
      |style|节点样式|`CSSProperties \| undefined`|`-`|
        
    
      ### TaoProvider
    
      
      |属性|说明|类型|默认值|
    |:---:|:---:|:---:|:---:|
      |direction|Text and interaction direction. Defaults to the surrounding DOM direction.|`TaoDirection \| undefined`|`-`|
    |locale|Component text and regional settings; omitted keys inherit from the parent.|`Partial<TaoLocale> \| undefined`|`-`|
    |disabled|是否禁用|`boolean \| undefined`|`-`|
        
    
      ### BuiltinTaoLocale
    
      **Complete dictionaries shipped by tao-ui; custom TaoLocale values stay compatible.**
    
      |属性|说明|类型|默认值|
    |:---:|:---:|:---:|:---:|
      
        
    
      ### TaoLocale
    
      **Built-in Select and date-picker text. Arrays use calendar order (Monday first).**
    
      |属性|说明|类型|默认值|
    |:---:|:---:|:---:|:---:|