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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/config-provider.md.

ConfigProvider 配置

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

基础用法

通过 theme 配置当前区域及其浮层。示例只修改主题色。

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
Englishen-US
日本語ja-JP
한국어ko-KR

默认语言为简体中文,与文档站的语言无关。这五种资源已内置;其他语言需要提供翻译资源。

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

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
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 模板。类型、JSON Schema 与校验方式见翻译资源。

区域密度

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

舒适
紧凑
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
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 配置见定制主题,服务端接入见服务端渲染。theme.components 设置组件样式 token,下方的 components 设置组件默认参数。

统一输入参数

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

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
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
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
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。完整参数见组件默认值参考。

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

API

ConfigProvider API

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

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

LeafTheme

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

属性类型默认值说明
primaryColorstring'#007aff'主题基色,浅深外观共用;交互色自动派生。
appearance'light' | 'dark''light'浅色或深色;嵌套时继承显式配置
borderRadiusnumber | string10基础圆角;数字为 px,小标签按 0.5、sm/lg 控件按 0.8/1.2、内容面与浮层按 1.4/1.6 倍生成。
controlHeightnumber | string34基础控件高度;小 / 大尺寸分别减 / 加 6px
fontSizenumber | string14基础字号;小字号减 1px,大字号加 2px
fontFamilystring系统无衬线字体字体族
motionbooleantrue启用当前区域的交互动效;系统减少动态效果优先,浮层继承此设置。
spacingnumber—基础间距,其他间距按比例派生。
lineHeightnumber | string20正文行高。数字默认为 px;大于 0 且不超过 4 的数字保留旧倍率语义,字符串按 CSS 长度处理。
headingWeight400 | 500 | 700700Card 与 Typography 标题字重,默认 700;其他组件标签使用 tokens.fontWeight,默认 500。
elevation'none' | 'soft' | 'medium'—整体阴影强度。
breakpointsPartial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>>—useBreakpoint 使用的响应式断点。
tokensLeafThemeTokens—可选的高级覆盖,不必配置全部字段
componentsRecord<string, LeafComponentTokens>—按组件名称覆盖局部样式。