> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/config-provider.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# ConfigProvider 配置

为应用或局部区域设置语言、主题和组件默认参数。嵌套使用时，未指定的配置继承上层。


## 基础用法

[](#)
[](#)
通过 `theme` 配置当前区域及其浮层。示例只修改主题色。


项目名称

项目类型

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/basic.tsx"
import { ConfigProvider, Form, FormField, Input, Select } from '@ifhover/leaf-ui';

export function ConfigProviderBasic() {
  return (
    <ConfigProvider theme={{ primaryColor: '#1d9bf0' }}>
      <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>
      </Form>
    </ConfigProvider>
  );
}
```

展开代码


## 示例

### 切换语言

#### 多语言

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

#### 内置语言

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

默认语言为简体中文，与文档站的语言无关。这五种资源已内置；其他语言需要[提供翻译资源](#补充自己的语言)。

更新 `locale` 后，打开日期面板或空选项下拉框，查看内置文本。应用提供的字段标签保持不变。


组件语言

日期

空选项

locale.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/locale.tsx"
import { ConfigProvider, DatePicker, Flex, Form, FormField, Select } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function ConfigProviderLocale() {
  const [locale, setLocale] = useState('zh-CN');
  return (
    <Flex direction="column" gap="lg">
      <FormField label="组件语言">
        <Select
          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: '한국어' },
          ]}
        />
      </FormField>
      <ConfigProvider locale={locale}>
        <Form onSubmit={(event) => event.preventDefault()}>
          <FormField label="日期">
            <DatePicker />
          </FormField>
          <FormField label="空选项">
            <Select options={[]} />
          </FormField>
        </Form>
      </ConfigProvider>
    </Flex>
  );
}
```

展开代码

嵌套区域未指定语言时继承上层。`direction` 设置文字和交互方向，`weekStartsOn` 设置一周的起始日；浮层也会继承。

### 补充自己的语言

通过 `translations` 按语言代码提供资源。示例只补充三个法语词条，其他词条回退英文；字段名称仍由应用提供。


日期

空选项

translations.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/translations.tsx"
import { ConfigProvider, DatePicker, Form, FormField, type LeafTranslations, Select } from '@ifhover/leaf-ui';

const translations = {
  'fr-FR': {
    datePicker: { placeholder: 'Choisir une date' },
    select: { placeholder: 'Choisir une option', empty: 'Aucun résultat' },
  },
} satisfies LeafTranslations;

export function ConfigProviderTranslations() {
  return (
    <ConfigProvider locale={['fr-FR', 'en-US']} translations={translations}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="日期">
          <DatePicker />
        </FormField>
        <FormField label="空选项">
          <Select options={[]} />
        </FormField>
      </Form>
    </ConfigProvider>
  );
}
```

展开代码

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

嵌套资源按语言和词条合并。未传 `locale`
 时继承语言链，显式传入则替换整条链；组件文案参数与 `components`
 默认值优先。需要完整资源时可下载[英文 JSON 模板
](/leaf-ui/locales/en-US.json)。类型、JSON Schema 与校验方式见[翻译资源](https://ifhover.github.io/leaf-ui/api/translations.md)
。
### 区域密度

`density="compact"` 收紧控件和内容间距，默认使用 `comfortable`。显式的主题尺寸和组件尺寸优先于密度预设。


舒适

项目名称

负责人

紧凑

项目名称

负责人

density.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/density.tsx"
import { ConfigProvider, Flex, Form, FormField, Input, Select, Text } from '@ifhover/leaf-ui';

export function ConfigProviderDensity() {
  return (
    <Flex direction="column" gap="lg">
      {(['comfortable', 'compact'] as const).map((density) => (
        <ConfigProvider key={density} density={density}>
          <Flex direction="column" gap="sm">
            <Text tone="muted">{density === 'compact' ? '紧凑' : '舒适'}</Text>
            <Form onSubmit={(event) => event.preventDefault()}>
              <FormField label="项目名称">
                <Input defaultValue="Leaf UI" />
              </FormField>
              <FormField label="负责人">
                <Select
                  defaultValue="lin"
                  options={[
                    { value: 'lin', label: 'Lin' },
                    { value: 'alex', label: 'Alex' },
                  ]}
                />
              </FormField>
            </Form>
          </Flex>
        </ConfigProvider>
      ))}
    </Flex>
  );
}
```

展开代码

### 基础高度

设置 `theme.controlHeight` 改变尺寸基准，小、大尺寸会随之派生。


基础高度

当前高度: 34px

小尺寸

按钮

中尺寸

按钮

大尺寸

按钮

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/sizes.tsx"
import { Button, ConfigProvider, Flex, FormField, Grid, Slider, Text } from '@ifhover/leaf-ui';
import { Fragment, useState } from 'react';

export function ConfigProviderSizes() {
  const [height, setHeight] = useState(34);
  return (
    <Flex direction="column" gap="lg">
      <FormField label="基础高度">
        <Slider min={28} max={44} value={height} onChange={setHeight} showValue={false} />
      </FormField>
      <Text tone="muted">当前高度: {height}px</Text>
      <ConfigProvider theme={{ controlHeight: height }}>
        <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
          {(
            [
              ['sm', '小尺寸'],
              ['md', '中尺寸'],
              ['lg', '大尺寸'],
            ] as const
          ).map(([size, label]) => (
            <Fragment key={size}>
              <Text tone="muted">{label}</Text>
              <Flex align="start">
                <Button size={size}>按钮</Button>
              </Flex>
            </Fragment>
          ))}
        </Grid>
      </ConfigProvider>
    </Flex>
  );
}
```

展开代码

外观和 token 配置见[定制主题](https://ifhover.github.io/leaf-ui/guide/theming.md)，服务端接入见[服务端渲染](https://ifhover.github.io/leaf-ui/guide/ssr.md)。`theme.components` 设置组件样式 token，下方的 `components` 设置组件默认参数。

### 统一输入参数

[](#)
通过 `components` 设置共享的输入提示和清除行为。实例传入的参数覆盖配置默认值。


继承默认参数

实例覆盖

defaults.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/defaults.tsx"
import { ConfigProvider, Form, FormField, Input } from '@ifhover/leaf-ui';

export function ConfigProviderDefaults() {
  return (
    <ConfigProvider components={{ Input: { placeholder: '请输入名称', allowClear: true } }}>
      <Form onSubmit={(event) => event.preventDefault()}>
        <FormField label="继承默认参数">
          <Input />
        </FormField>
        <FormField label="实例覆盖">
          <Input placeholder="请输入团队名称" />
        </FormField>
      </Form>
    </ConfigProvider>
  );
}
```

展开代码

### 弹窗关闭方式

`Modal: { maskClosable: false }` 禁止点击遮罩关闭区域内的弹窗。关闭按钮、底部操作和 Escape 仍然可用。


打开弹窗

modal-defaults.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/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>点击遮罩不会关闭。使用关闭按钮、底部操作或 Escape 关闭。</Paragraph>
      </Modal>
    </ConfigProvider>
  );
}
```

展开代码

### 继承与覆盖

优先级为 **实例参数 > 内层配置 > 外层配置 > 组件内置值**。


外层配置

继续

内层覆盖

继续

实例覆盖

继续

inheritance.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/inheritance.tsx"
import { Button, ConfigProvider, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function ConfigProviderInheritance() {
  return (
    <ConfigProvider components={{ Button: { size: 'sm' } }}>
      <Grid columns={1} gap={24}>
        <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
          <Text tone="muted">外层配置</Text>
          <Flex align="start">
            <Button>继续</Button>
          </Flex>
        </Grid>
        <ConfigProvider components={{ Button: { size: 'lg' } }}>
          <Grid columns={1} gap={24}>
            <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
              <Text tone="muted">内层覆盖</Text>
              <Flex align="start">
                <Button>继续</Button>
              </Flex>
            </Grid>
            <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
              <Text tone="muted">实例覆盖</Text>
              <Flex align="start">
                <Button size="md">继续</Button>
              </Flex>
            </Grid>
          </Grid>
        </ConfigProvider>
      </Grid>
    </ConfigProvider>
  );
}
```

展开代码

默认值按组件和参数合并。只有 `undefined` 会回退；`false`、`0` 和空字符串等值会保留。对象、数组、类名和回调整体替换，不继续合并。

### 清除继承

将组件配置设为 `null`，在当前区域恢复它的内置默认值。空对象和 `undefined` 继续继承；其他组件与主题不受影响。


继承默认参数

清除继承

reset.tsx

复制代码

```tsx lineNumbers file="../../src/examples/config-provider/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 onSubmit={(event) => event.preventDefault()}>
        <FormField label="继承默认参数">
          <Input defaultValue="只读内容" />
        </FormField>
        <ConfigProvider components={{ Input: null }}>
          <FormField label="清除继承">
            <Input defaultValue="可以编辑" />
          </FormField>
        </ConfigProvider>
      </Form>
    </ConfigProvider>
  );
}
```

展开代码

使用 `LeafComponentDefaults` 检查可复用配置。键名与公开组件名一致；DataTable 仅使用 `DataTable` 键，别名使用规范名称，例如 `FAB` 对应 `FloatButton`。完整参数见[组件默认值参考](https://ifhover.github.io/leaf-ui/api/component-defaults.md#leafcomponentdefaults)。

每个实例的数据、受控状态和事件仍传给组件。更新配置时传入新对象；内部控件通过所属组件配置，例如 `Modal.confirmButtonProps`，不会跟随全局 `Button` 默认值。


## API

### ConfigProvider API

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

其余原生 div 属性、`className` 和 `style` 作用于区域容器。

### LeafTheme

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

| 属性              | 类型                                                                                                                     | 默认值         | 说明                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ |
| `primaryColor`  | `string`                                                                                                               | `'#007aff'` | 主题基色，浅深外观共用；交互色自动派生。                                               |
| `appearance`    | `'light' \| 'dark'`                                                                                                    | `'light'`   | 浅色或深色；嵌套时继承显式配置                                                    |
| `borderRadius`  | `number \| string`                                                                                                     | `10`        | 基础圆角；数字为 px，小标签按 0.5、sm/lg 控件按 0.8/1.2、内容面与浮层按 1.4/1.6 倍生成。        |
| `controlHeight` | `number \| string`                                                                                                     | `34`        | 基础控件高度；小 / 大尺寸分别减 / 加 6px                                          |
| `fontSize`      | `number \| string`                                                                                                     | `14`        | 基础字号；小字号减 1px，大字号加 2px                                             |
| `fontFamily`    | `string`                                                                                                               | 系统无衬线字体     | 字体族                                                                |
| `motion`        | `boolean`                                                                                                              | `true`      | 启用当前区域的交互动效；系统减少动态效果优先，浮层继承此设置。                                    |
| `spacing`       | `number`                                                                                                               | —           | 基础间距，其他间距按比例派生。                                                    |
| `lineHeight`    | `number \| string`                                                                                                     | `20`        | 正文行高。数字默认为 px；大于 0 且不超过 4 的数字保留旧倍率语义，字符串按 CSS 长度处理。                |
| `headingWeight` | `400 \| 500 \| 700`                                                                                                    | `700`       | Card 与 Typography 标题字重，默认 700；其他组件标签使用 `tokens.fontWeight`，默认 500。 |
| `elevation`     | `'none' \| 'soft' \| 'medium'`                                                                                         | —           | 整体阴影强度。                                                            |
| `breakpoints`   | `Partial<Record<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl', number>>`                                                        | —           | useBreakpoint 使用的响应式断点。                                            |
| `tokens`        | [`LeafThemeTokens`](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafthemetokens)                             | —           | 可选的高级覆盖，不必配置全部字段                                                   |
| `components`    | `Record<string, `[`LeafComponentTokens`](https://ifhover.github.io/leaf-ui/api/theme-tokens.md#leafcomponenttokens)`>` | —           | 按组件名称覆盖局部样式。                                                       |
