• 简体中文
  • ConfigProvider 配置

    统一设置区域的主题、外观与语言。

    区域主题与语言

    交互预览区域主题与语言
    basic.tsx
    import { Button, ConfigProvider, DatePicker, Select, Switch, useMessage } from '@sudden3/leaf-ui';
    import { useState } from 'react';
    
    function Region() {
      const { message, contextHolder } = useMessage();
      return (
        <div className="leaf-demo-row">
          <Select aria-label="选项" options={[]} />
          <DatePicker aria-label="日期" />
          <Button onClick={() => message.success('Success / 操作成功')}>Message</Button>
          {contextHolder}
        </div>
      );
    }
    export function ConfigProviderBasic() {
      const [english, setEnglish] = useState(true);
      return (
        <div className="leaf-demo-stack leaf-demo-stack--wide">
          <Switch checked={english} onChange={(event) => setEnglish(event.target.checked)}>
            English
          </Switch>
          <ConfigProvider
            locale={english ? 'en-US' : 'zh-CN'}
            theme={{ primaryColor: '#7654c6', borderRadius: 4 }}
          >
            <Region />
          </ConfigProvider>
          <ConfigProvider theme={{ primaryColor: '#087f8c', borderRadius: 16 }}>
            <Region />
          </ConfigProvider>
        </div>
      );
    }
    

    基础尺寸与高级覆盖

    修改基础高度时,小、大控件会同步调整。需要特殊尺寸时,再通过 tokens 单独覆盖。

    交互预览基础尺寸与高级覆盖
    sm
    md
    lg
    sizes.tsx
    import { Button, ConfigProvider, Input } from '@sudden3/leaf-ui';
    import { useState } from 'react';
    
    export function ConfigProviderSizes() {
      const [height, setHeight] = useState(34);
      return (
        <div className="leaf-demo-stack leaf-demo-stack--wide">
          <label>
            基础高度:{height}px
            <input
              aria-label="基础控件高度"
              type="range"
              min="28"
              max="44"
              value={height}
              onChange={(event) => setHeight(Number(event.target.value))}
            />
          </label>
          <ConfigProvider
            className="leaf-demo-stack"
            theme={{ controlHeight: height, borderRadius: 8 }}
          >
            {(['sm', 'md', 'lg'] as const).map((size) => (
              <div key={size} className="leaf-demo-control-row">
                <span className="leaf-demo-size">{size}</span>
                <Input size={size} aria-label={`${size} 主题输入框`} placeholder="项目名称" />
                <Button size={size}>保存</Button>
              </div>
            ))}
          </ConfigProvider>
          <ConfigProvider
            theme={{ controlHeight: height, tokens: { controlHeightSm: 26, borderRadiusLg: 20 } }}
          >
            <Button size="sm" variant="outline">
              高级覆盖:小尺寸固定为 26px
            </Button>
          </ConfigProvider>
        </div>
      );
    }
    

    ConfigProvider API

    属性类型默认值说明
    themeLeafTheme—区域主题;未设置的字段继承上层
    locale'zh-CN' | 'en-US''zh-CN'内置文本语言,嵌套时继承
    childrenReactNode—区域中的内容

    其余原生 div 属性、className 和 style 作用于区域容器。主题设置通过 theme 传入。

    LeafTheme

    属性类型默认值说明
    primaryColorstring'#20834a'主题色,悬停和按下等状态自动生成;深色默认采用较浅的绿色
    borderRadiusnumber | string10基础圆角;数字为 px,小 / 大圆角按 0.6 / 1.6 倍生成
    controlHeightnumber | string34基础控件高度;小 / 大尺寸分别减 / 加 6px
    fontSizenumber | string14基础字号;小 / 大字号分别减 / 加 2px
    fontFamilystring系统无衬线字体字体族
    appearance'light' | 'dark''light'浅色或深色;嵌套时继承显式配置
    motionbooleantrue是否启用过渡与加载图标旋转;尊重系统减少动态效果设置
    tokensLeafThemeTokens—可选的高级覆盖,不必配置全部字段

    以上默认值适用于未配置的应用。嵌套区域继承上层显式设置;长度也支持 CSS 单位。小控件高度和字号的自动结果不会小于 1px。

    LeafThemeTokens

    所有字段均可选;显式值优先于默认或自动生成值。

    属性类型默认值说明
    onPrimaryColorstring按主题生成主题背景上的文字色
    dangerColor / onDangerColorstring按外观生成危险色 / 危险背景上的文字色
    successColor / warningColor / infoColorstring按外观生成成功 / 警告 / 信息颜色
    textColor / mutedTextColorstring按外观生成主要 / 次要文字
    surfaceColor / mutedSurfaceColorstring按外观生成表面 / 次级表面
    borderColorstring按外观生成中性边框
    borderRadiusSm / borderRadiusLgnumber | string基础圆角 × 0.6 / 1.6单独覆盖小 / 大圆角
    controlHeightSm / controlHeightLgnumber | string基础高度 − / + 6px单独覆盖小 / 大高度
    fontSizeSm / fontSizeLgnumber | string基础字号 − / + 2px单独覆盖小 / 大字号
    fontWeightnumber500按钮等组件的字重
    motionDurationnumber | string160过渡时间;数字为 ms,也支持 '0.2s';motion=false 时为 0
    motionEasingstring'ease'过渡曲线
    popupZIndex / modalZIndex / messageZIndexnumber1000 / 1100 / 1200浮层 / 弹窗 / 消息层级
    buttonBorderRadius / buttonHeightnumber | string当前控件尺寸仅按钮的圆角 / 共用高度覆盖
    choiceBorderRadiusnumber | string基础圆角 × 0.5复选框圆角
    focusColorstring当前语义色自动生成焦点轮廓颜色
    primaryHoverColor / primaryActiveColorstring主题色自动生成主色悬停 / 按下
    primarySoftColor / primarySoftHoverColor / primarySoftActiveColorstring主题色自动生成主色柔和背景与交互状态
    primaryBorderColorstring主题色自动生成主题色边框
    dangerHoverColor / dangerActiveColorstring危险色自动生成危险状态悬停 / 按下

    类型

    组装可复用的主题或属性时,可导入这些类型:

    import type { ConfigProviderProps, LeafTheme, LeafThemeTokens, LeafLocale } from '@sudden3/leaf-ui';
    
    const theme: LeafTheme = { primaryColor: '#7654c6', borderRadius: 8 };
    const advanced: LeafThemeTokens = { controlHeightLg: 44 };

    LeafLocale 直接表示 'zh-CN' | 'en-US'。ConfigProviderProps 对应上方 ConfigProvider API。

    使用说明

    嵌套区域按字段合并 tokens;手动指定的派生尺寸会继续继承。浮层、Modal 和此区域内的 message / confirm contextHolder 沿用相同配置。

    语言覆盖内置提示、日期、时间、清除按钮和反馈组件;业务内容、label 和 options 由应用翻译。

    使用 ConfigProvider 调整主题,CSS 变量供业务组件读取和复用。入门示例见定制主题,服务端接入见 SSR 使用。