ConfigProvider 配置
为应用或局部区域设置语言、主题和组件默认参数。嵌套使用时,未指定的配置继承上层。
基础用法
通过 theme 配置当前区域及其浮层。示例只修改主题色。
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 后,打开日期面板或空选项下拉框,查看内置文本。应用提供的字段标签保持不变。
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 按语言代码提供资源。示例只补充三个法语词条,其他词条回退英文;字段名称仍由应用提供。
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。显式的主题尺寸和组件尺寸优先于密度预设。
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 改变尺寸基准,小、大尺寸会随之派生。
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 设置共享的输入提示和清除行为。实例传入的参数覆盖配置默认值。
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 仍然可用。
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>
);
}
继承与覆盖
优先级为 实例参数 > 内层配置 > 外层配置 > 组件内置值。
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 继续继承;其他组件与主题不受影响。
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
其余原生 div 属性、className 和 style 作用于区域容器。
LeafTheme
常用主题配置。未设置的字段继承外层区域。