ConfigProvider 配置

为整个应用或局部区域统一设置主题、语言和组件默认参数。

放在应用入口时作用于整个应用；嵌套使用时只调整当前区域。

想调整什么	使用的配置
内置文本与自定义语言	`locale`、`translations`
主题色、外观、尺寸与间距	`theme`、`density`
统一组件参数	`components`

多语言

locale 切换日期面板、空状态、清除按钮等内置文本。业务标题、字段标签和选项内容由应用自行翻译。

内置语言

以下语言已内置，无需额外导入语言包。未配置 locale 时，默认使用简体中文。

语言	`locale`
简体中文	`zh-CN`
繁體中文	`zh-TW`
English	`en-US`
日本語	`ja-JP`
한국어	`ko-KR`

其他语言需要提供翻译资源。仅传入其他语言代码不会自动翻译内置文本；未找到的词条最终回退到英文。

切换语言

更新 locale 即可切换语言。在下拉框中选择语言，再打开日期或空选项控件，可比较五种语言的内置提示。

locale.tsx

import { ConfigProvider, DatePicker, Form, FormField, Select, Space } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ConfigProviderLocale() {
  const [locale, setLocale] = useState('zh-CN');
  return (
    <Space direction="vertical" align="stretch">
      <Select
        aria-label="组件语言"
        value={locale}
        onChange={setLocale}
        options={[
          { value: 'zh-CN', label: '简体中文' },
          { value: 'zh-TW', label: '繁體中文' },
          { value: 'en-US', label: 'English' },
          { value: 'ja-JP', label: '日本語' },
          { value: 'ko-KR', label: '한국어' },
        ]}
      />
      <ConfigProvider locale={locale}>
        <Form>
          <FormField label="日期">
            <DatePicker />
          </FormField>
          <FormField label="空选项">
            <Select options={[]} />
          </FormField>
        </Form>
      </ConfigProvider>
    </Space>
  );
}

嵌套区域未指定语言时继承上层；direction 调整文字方向，weekStartsOn 设置一周的起始日，浮层也会继承这些配置。

补充自己的语言

复制完整英文 JSON作为模板，翻译后导入并传给 translations。键是语言代码，JSON 只包含按组件分组的文本，不需要重复写语言代码。可以只提供部分词条。

👽 下面用火星文演示自定义资源，作为一个小彩蛋。它是一种混用谐音字、形近字和符号的网络写法。

未翻译的词条回退英文。字段名称、确认框正文等业务内容仍由应用提供。

火星文使用私用语言标记 zh-CN-x-mars，日期和数字仍按简体中文的区域格式显示。它仅用于演示，不属于内置语言。

translations.tsx

import { Button, ConfigProvider, DatePicker, Form, FormField, Pagination, Select, Space, useConfirm } from '@ifhover/leaf-ui';

import mars from './zh-CN-x-mars.json';

const translations = { 'zh-CN-x-mars': mars };

function Controls() {
  const { confirm } = useConfirm();
  return (
    <Space direction="vertical" align="stretch">
      <Form>
        <FormField label="日期">
          <DatePicker />
        </FormField>
        <FormField label="空选项">
          <Select options={[]} />
        </FormField>
      </Form>
      <Pagination total={24} showTotal />
      <Button
        variant="outline"
        onClick={() =>
          void confirm({
            title: '继续操作？',
            children: '确认与取消按钮使用火星文，未翻译的文本回退英文。',
          })
        }
      >
        打开确认框
      </Button>
    </Space>
  );
}

export function ConfigProviderTranslations() {
  return (
    <ConfigProvider locale={['zh-CN-x-mars', 'en-US']} translations={translations}>
      <Controls />
    </ConfigProvider>
  );
}

示例中的 zh-CN-x-mars.json：

{
  "common": {
    "confirm": "確萣",
    "cancel": "筭ㄋ"
  },
  "select": {
    "placeholder": "挑①個唄",
    "empty": "暫蒔木洧選項"
  },
  "datePicker": {
    "placeholder": "選個ㄖ剘"
  },
  "pagination": {
    "total": "共 {total} 條數據"
  }
}

locale={['zh-CN-x-mars', 'en-US']} 按顺序查找每个缺失词条，最后由内置英文兜底。第一项始终控制当前语言、日期与数字的区域格式；字符串等价于单项数组，空数组无效。不会自动添加 zh-CN-x-mars → zh-CN 或 fr-CA → fr 等回退。

嵌套时 translations 按语言和词条合并；未传 locale 则继承，显式传入则替换整条语言链。组件实例与 components 设置的文案优先。完整规则、类型、JSON Schema 和词条检查见翻译资源。

主题与外观

区域主题

主题会应用到区域内的组件和浮层。通常只需要修改主题色或基础圆角，其余样式会随之调整。

basic.tsx

import { Button, ConfigProvider, Form, FormField, Input, Select } from '@ifhover/leaf-ui';

export function ConfigProviderBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 8 }}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="项目名称">
          <Input defaultValue="Leaf UI" />
        </FormField>
        <FormField label="项目类型">
          <Select
            defaultValue="website"
            options={[
              { value: 'website', label: '网站' },
              { value: 'app', label: '应用' },
            ]}
          />
        </FormField>
        <Button type="submit">保存设置</Button>
      </Form>
    </ConfigProvider>
  );
}

区域密度

density="compact" 适合信息较多的界面，会一起收紧控件和内容间距；默认使用 comfortable。嵌套区域可单独设置。

舒适

紧凑

density.tsx

import { Button, ConfigProvider, Form, FormField, Input, Select, Space, Text } from '@ifhover/leaf-ui';

export function ConfigProviderDensity() {
  return (
    <Space direction="vertical" align="stretch" size="lg">
      {(['comfortable', 'compact'] as const).map((density) => (
        <ConfigProvider key={density} density={density}>
          <Space direction="vertical" align="stretch">
            <Text tone="muted">{density === 'compact' ? '紧凑' : '舒适'}</Text>
            <Form>
              <FormField label="项目名称">
                <Input defaultValue="Leaf UI" />
              </FormField>
              <FormField label="负责人">
                <Select
                  options={[
                    { value: 'lin', label: 'Lin' },
                    { value: 'alex', label: 'Alex' },
                  ]}
                  defaultValue="lin"
                />
              </FormField>
              <Button type="reset" variant="outline">
                重置
              </Button>
            </Form>
          </Space>
        </ConfigProvider>
      ))}
    </Space>
  );
}

基础高度

需要改变整体尺寸基准时，设置 theme.controlHeight，小、大尺寸会自动派生。无需逐项调整按钮和输入框的高度。

小尺寸

默认尺寸

大尺寸

sizes.tsx

import { Button, ConfigProvider, Form, FormField, Slider, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ConfigProviderSizes() {
  const [height, setHeight] = useState(36);
  return (
    <Space direction="vertical" align="stretch" size="lg">
      <Form>
        <FormField label={`基础高度：${height}px`}>
          <Slider min={28} max={44} value={height} onChange={setHeight} showValue={false} />
        </FormField>
      </Form>
      <ConfigProvider theme={{ controlHeight: height }}>
        <Space wrap align="end" size="lg">
          {(
            [
              ['sm', '小尺寸'],
              ['md', '默认尺寸'],
              ['lg', '大尺寸'],
            ] as const
          ).map(([size, label]) => (
            <Space key={size} direction="vertical" size="sm">
              <Text tone="muted">{label}</Text>
              <Button size={size} variant="outline">
                按钮
              </Button>
            </Space>
          ))}
        </Space>
      </ConfigProvider>
    </Space>
  );
}

进一步定制见定制主题。theme.components 调整组件局部样式，下方的 components 设置组件默认参数；两者用途不同，可以同时使用。服务端接入见服务端渲染。

组件默认值

常用参数设一次，省去每个组件重复传参。 用 components 统一按钮样式、输入提示、弹窗关闭方式，后续调整也只改一处。

放在应用入口作用于全站，放在局部只影响当前区域；个别组件仍可用自身参数覆盖。

统一表单习惯

下面统一输入提示、清除按钮和按钮样式，结束日期与保存按钮单独覆盖。

defaults.tsx

import { Button, ConfigProvider, DatePicker, Form, FormField, Input, Space } from '@ifhover/leaf-ui';

export function ConfigProviderDefaults() {
  return (
    <ConfigProvider
      components={{
        Button: { variant: 'outline' },
        Input: { placeholder: '请输入项目名称', allowClear: true },
        DatePicker: { placeholder: '选择项目开始日期', allowClear: true },
      }}
    >
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="项目名称">
          <Input />
        </FormField>
        <FormField label="开始日期">
          <DatePicker />
        </FormField>
        <FormField label="结束日期">
          <DatePicker placeholder="实例覆盖：选择结束日期" />
        </FormField>
        <Space wrap>
          <Button type="reset">重置</Button>
          <Button type="submit" variant="solid">
            保存（实例覆盖）
          </Button>
        </Space>
      </Form>
    </ConfigProvider>
  );
}

防止误点遮罩关闭弹窗

编辑时不希望误点遮罩就关掉弹窗，可以统一设置 Modal: { maskClosable: false }。区域内的 Modal 都会沿用，无需逐个设置；关闭按钮和 Esc 仍然可用。

modal-defaults.tsx

import { Button, ConfigProvider, Modal, Paragraph } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ConfigProviderModalDefaults() {
  const [open, setOpen] = useState(false);

  return (
    <ConfigProvider components={{ Modal: { maskClosable: false } }}>
      <Button onClick={() => setOpen(true)}>打开弹窗</Button>
      <Modal open={open} title="点击遮罩不会关闭" onClose={() => setOpen(false)}>
        <Paragraph>
          试着点击弹窗外的遮罩，弹窗会保持打开。仍可通过关闭按钮、底部操作或 Esc 关闭。
        </Paragraph>
      </Modal>
    </ConfigProvider>
  );
}

继承与覆盖

统一默认值后，局部仍可灵活调整：实例参数 > 内层配置 > 外层配置 > 组件内置值。

外层配置

内层覆盖尺寸

实例覆盖参数

inheritance.tsx

import { Button, ConfigProvider, Flex, Space, Text } from '@ifhover/leaf-ui';

export function ConfigProviderInheritance() {
  return (
    <ConfigProvider components={{ Button: { variant: 'outline', size: 'sm' } }}>
      <Space direction="vertical" align="stretch">
        <Flex justify="space-between" align="center" gap="md">
          <Text tone="muted">外层配置</Text>
          <Button>小尺寸 · 边框</Button>
        </Flex>
        <ConfigProvider components={{ Button: { size: 'lg' } }}>
          <Space direction="vertical" align="stretch">
            <Flex justify="space-between" align="center" gap="md">
              <Text tone="muted">内层覆盖尺寸</Text>
              <Button>大尺寸 · 继承边框</Button>
            </Flex>
            <Flex justify="space-between" align="center" gap="md">
              <Text tone="muted">实例覆盖参数</Text>
              <Button size="md" variant="solid">
                默认尺寸 · 主要
              </Button>
            </Flex>
          </Space>
        </ConfigProvider>
      </Space>
    </ConfigProvider>
  );
}

清除继承

将组件配置设为 null，可在局部恢复它的内置默认值，例如 components={{ Input: null }}。

reset.tsx

import { ConfigProvider, Form, FormField, Input, type LeafComponentDefaults } from '@ifhover/leaf-ui';

const defaults = { Input: { readOnly: true } } satisfies LeafComponentDefaults;

export function ConfigProviderReset() {
  return (
    <ConfigProvider components={defaults}>
      <Form>
        <FormField label="继承默认参数">
          <Input defaultValue="此输入框为只读" />
        </FormField>
        <ConfigProvider components={{ Input: null }}>
          <FormField label="清除当前区域的默认参数">
            <Input defaultValue="试试修改这里的内容" />
          </FormField>
        </ConfigProvider>
      </Form>
    </ConfigProvider>
  );
}

API

ConfigProvider API

属性	类型	默认值	说明
`locale`	`LeafLocale \| readonly LeafLocale[]`	`'zh-CN'`	当前语言与逐词条回退顺序；未指定则继承
`translations`	`Readonly<Record<string, LeafTranslation>>`	—	按语言代码提供 JSON 翻译，嵌套时按词条合并
`theme`	`LeafTheme`	—	区域主题；未设置的字段继承上层
`direction`	`'ltr' \| 'rtl'`	—	文字和交互方向。
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	—	一周起始日，0 表示周日、1 表示周一。
`getPopupContainer`	`() => Element \| DocumentFragment`	—	返回浮层的挂载容器，也可返回 ShadowRoot。
`maskBlur`	`boolean`	`true`	启用 Modal、Drawer 及基于 Modal 的确认框、命令面板等遮罩模糊；关闭可减少渲染开销，嵌套时继承。
`density`	`'comfortable' \| 'compact'`	`'comfortable'`	继承控件、表单、菜单、列表与浮层的密度；显式尺寸优先于预设。
`components`	`LeafComponentDefaults`	—	当前区域的组件默认参数，嵌套时按组件和参数继承。

其余原生 div 属性、className 和 style 作用于区域容器。maskBlur={false} 关闭背景模糊，仍保留半透明遮罩；此设置独立于 theme.motion。

LeafTheme

常用主题配置。未设置的字段继承外层区域。

属性	类型	默认值	说明
`primaryColor`	`string`	`'#20834a'`	主题色，悬停和按下等状态自动生成；深色默认采用较浅的绿色
`borderRadius`	`number \| string`	`10`	基础圆角；数字为 px，小 / 中 / 大圆角按 0.6 / 1.2 / 1.6 倍生成
`controlHeight`	`number \| string`	`36`	基础控件高度；小 / 大尺寸分别减 / 加 6px
`fontSize`	`number \| string`	`14`	基础字号；小字号减 1px，大字号加 2px
`fontFamily`	`string`	系统无衬线字体	字体族
`appearance`	`'light' \| 'dark'`	`'light'`	浅色或深色；嵌套时继承显式配置
`motion`	`boolean`	`true`	启用当前区域的交互动效；系统减少动态效果优先，浮层继承此设置。
`tokens`	`LeafThemeTokens`	—	可选的高级覆盖，不必配置全部字段
`spacing`	`number`	—	基础间距，其他间距按比例派生。
`lineHeight`	`number`	—	正文行高。
`headingWeight`	`number`	—	Typography 文档标题的字重；组件标题使用 `tokens.fontWeight`。
`elevation`	`'none' \| 'soft' \| 'medium'`	—	整体阴影强度。
`breakpoints`	`Partial<Record<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl', number>>`	—	useBreakpoint 使用的响应式断点。
`components`	`Record<string, LeafComponentTokens>`	—	按组件名称覆盖局部样式。

类型与完整参考

组装可复用配置时，可按需导入类型：

import type { ConfigProviderProps, LeafComponentDefaults, LeafTheme } from '@ifhover/leaf-ui';

LeafComponentDefaults：组件名称与可配置的默认参数。
LeafThemeTokens：高级主题覆盖。

#ConfigProvider 配置

#多语言

#内置语言

#切换语言

#补充自己的语言

#主题与外观

#区域主题

#区域密度

#基础高度

#组件默认值

#统一表单习惯

#防止误点遮罩关闭弹窗

#继承与覆盖

#清除继承

#API

#ConfigProvider API

#LeafTheme

#类型与完整参考