Arco Design ConfigProvider 全局配置完全指南:国际化、主题、组件默认参数与 RTL 布局
Arco Design ConfigProvider 全局配置完全指南:国际化、主题、组件默认参数与 RTL 布局
导读
ConfigProvider 是 Arco Design React 组件库(@arco-design/web-react)中用于全局配置的核心组件,将其置于应用最外层,即可一次性设置国际化语言、主题色、组件默认尺寸与参数、RTL 布局、弹出层挂载节点等全局能力,让所有子组件自动生效。本文将以仓库内 ConfigProvider 模板文档 与 README 文档 为主体,结合源码实现与测试用例,系统讲解每个配置项的用法、默认值与底层原理。读完本文,你将掌握在项目中通过 ConfigProvider 统一管理多语言、动态主题、组件级默认配置、表格分页、空状态以及 RTL 视图的完整实战方案。
ConfigProvider 是什么:一次设置、全局生效
官方文档对它的定位只有一句话:在应用的最外层进行配置,一次设置,全局生效("Configure in the outermost layer of the application to set global params")。它本质上是一个基于 React Context 的配置注入组件——从 context.tsx 可以看到,组件内部创建了 ConfigContext,并通过 ConfigContext.Provider 把合并后的配置下发到组件树中:
// components/ConfigProvider/context.tsx(节选)
export const DefaultConfigProviderProps: ConfigProviderProps = {
locale: defaultLocale,
prefixCls: 'arco',
getPopupContainer: () => document.body,
size: 'default',
renderEmpty,
focusLock: {
modal: { autoFocus: true },
drawer: { autoFocus: true },
},
};
export const ConfigContext = createContext<ConfigProviderProps>({
getPrefixCls: (componentName: string, customPrefix?: string) =>
`${customPrefix || 'arco'}-${componentName}`,
...DefaultConfigProviderProps,
});
每个具体组件(如 Button、DatePicker)在渲染时通过 useContext(ConfigContext) 读取配置。以 Button/index.tsx 为例,它会从 Context 中取出 getPrefixCls 等字段:
import { ConfigContext } from '../ConfigProvider';
// ...
const { getPrefixCls, ... } = useContext(ConfigContext);
// ...
const prefixCls = getPrefixCls('btn');
也就是说,ConfigProvider 设置的 prefixCls、size、locale、componentConfig 等参数,会被所有消费该 Context 的组件自动继承,这就是"一次设置、全局生效"的底层机制。从源码结构看,ConfigProvider/index.tsx 中 useMergeProps 负责合并"用户传入 props + 默认 props + 全局 componentConfig",最终通过 ConfigContext.Provider 注入子树:
function ConfigProvider(baseProps: ConfigProviderProps) {
const props = useMergeProps<ConfigProviderProps>(baseProps, defaultProps, componentConfig);
// ...
const config: ConfigProviderProps = {
...omit(props, ['children']),
getPrefixCls,
};
// ...
return <ConfigContext.Provider value={config}>{child}</ConfigContext.Provider>;
}
除 Context 外,ConfigProvider 还会通过命令式 API 把部分配置同步给全局单例组件(Modal、Message、Notification),详见后文"局部修改 Message / Notification / Modal 配置"一节。
基础用法:国际化语言包设置
最常见的用法是设置国际化语言。基础示例(来自 basic.md)展示了如何通过 locale 属性动态切换多种语言,让 Pagination、DatePicker、TimePicker、Popconfirm、Modal 等组件内部的文案同步变化:
import { useState } from 'react';
import {
ConfigProvider,
Radio,
Pagination,
DatePicker,
TimePicker,
Popconfirm,
Button,
Modal,
} from '@arco-design/web-react';
import zhCN from '@arco-design/web-react/es/locale/zh-CN';
import enUS from '@arco-design/web-react/es/locale/en-US';
import jaJP from '@arco-design/web-react/es/locale/ja-JP';
import koKR from '@arco-design/web-react/es/locale/ko-KR';
import idID from '@arco-design/web-react/es/locale/id-ID';
import thTH from '@arco-design/web-react/es/locale/th-TH';
import zhHK from '@arco-design/web-react/es/locale/zh-HK';
import frFR from '@arco-design/web-react/es/locale/fr-FR';
import esES from '@arco-design/web-react/es/locale/es-ES';
import deDE from '@arco-design/web-react/es/locale/de-DE';
import itIT from '@arco-design/web-react/es/locale/it-IT';
import viVN from '@arco-design/web-react/es/locale/vi-VN';
function App() {
const [locale, setLocale] = useState('zh-CN');
function getLocale() {
switch (locale) {
case 'zh-CN':
return zhCN;
case 'en-US':
return enUS;
case 'ja-JP':
return jaJP;
case 'ko-KR':
return koKR;
case 'id-ID':
return idID;
case 'th-TH':
return thTH;
case 'zh-HK':
return zhHK;
case 'fr-FR':
return frFR;
case 'es-ES':
return esES;
case 'de-DE':
return deDE;
case 'it-IT':
return itIT;
case 'vi-VN':
return viVN;
default:
return zhCN;
}
}
return (
<ConfigProvider locale={getLocale()}>
<Radio.Group
value={locale}
options={[
'zh-CN',
'en-US',
'zh-HK',
'ja-JP',
'ko-KR',
'id-ID',
'th-TH',
'fr-FR',
'es-ES',
'de-DE',
'it-IT',
'vi-VN',
]}
name="locale"
type="button"
mode="fill"
onChange={setLocale}
style={{ marginBottom: 40 }}
/>
<br />
<Pagination
total={200}
showTotal
sizeCanChange
style={{ marginBottom: 20, marginRight: 40, minWidth: 550 }}
/>
<DatePicker.RangePicker style={{ marginBottom: 20, marginRight: 40, width: 300 }} />
<TimePicker.RangePicker style={{ marginBottom: 20, marginRight: 40, width: 300 }} />
<Popconfirm title="Click to confirm!">
<Button style={{ marginBottom: 20, marginRight: 20 }} type="primary">
Popconfirm
</Button>
</Popconfirm>
<Button
onClick={() =>
Modal.confirm({
title: 'Title',
content: 'Content',
})
}
>
Modal confirm
</Button>
</ConfigProvider>
);
}
export default App;
仓库内置的语言包位于 components/locale 目录,共提供 21 种语言:zh-CN、zh-HK、zh-TW、en-US、ja-JP、ko-KR、id-ID、th-TH、fr-FR、es-ES、de-DE、it-IT、vi-VN、ar-EG、ms-MY、pt-BR、pt-PT、ru-RU、tr-TR 等。使用 locale 属性时直接传入这些语言包对象(或自定义的 Locale 类型对象)即可。
测试用例 locale.test.tsx 验证了该机制的真实效果:当传入 enUS 时,DatePicker 的 placeholder 读取自 enUS.DatePicker.placeholder.date;传入 zhCN 时则读取 zhCN.DatePicker.placeholder.date:
it('enUs placeholder correctly', () => {
const component = render(
<ConfigProvider locale={enUS}>
<DatePicker />
</ConfigProvider>
);
expect(component.find('.arco-picker-start-time')[0].getAttribute('placeholder')).toBe(
enUS.DatePicker.placeholder.date
);
});
主题配置:一行属性切换全局主题色
theme 属性用于全局主题配置,可设置 primaryColor、successColor、infoColor、warningColor、dangerColor 等颜色。示例(来自 theme.md)中预置了 4 套主题色,切换时通过 ConfigProvider theme 动态传入:
import { useState } from 'react';
import { ConfigProvider, Button, Input, Radio } from '@arco-design/web-react';
const themes = {
blue: {
primaryColor: '#3370ff',
},
red: {
primaryColor: '#ee4d38',
},
green: {
primaryColor: '#0fbf60',
},
orange: {
primaryColor: '#f58505',
},
};
function App() {
const [theme, setTheme] = useState(null);
return (
<ConfigProvider theme={theme && themes[theme]}>
<Radio.Group
name="theme"
options={['blue', 'red', 'green', 'orange']}
onChange={(theme) => {
setTheme(theme);
}}
style={{ display: 'block', marginBottom: 40 }}
/>
<Button
style={{ marginRight: 40 }}
type="primary"
>
Button
</Button>
<Input
style={{ width: 200 }}
placeholder="Please Enter ..."
/>
</ConfigProvider>
);
}
export default App;
从源码 ConfigProvider/index.tsx 看,主题生效机制是把颜色值写入 document.body 上的 CSS 变量。setTheme 函数维护了一张颜色与 CSS 变量的映射表:
const colorList = {
primaryColor: { default: '--arcoblue-6', hover: '--arcoblue-5', active: '--arcoblue-7' },
successColor: { default: '--green-6', hover: '--green-5', active: '--green-7' },
infoColor: { default: '--arcoblue-6', hover: '--arcoblue-5', active: '--arcoblue-7' },
warningColor: { default: '--orangered-6', hover: '--orangered-5', active: '--orangered-7' },
dangerColor: { default: '--red-6', hover: '--red-5', active: '--red-7' },
};
function setTheme(theme: ConfigProviderProps['theme']) {
if (theme && isObject(theme)) {
const root = document.body;
Object.keys(colorList).forEach((color) => {
if (theme[color]) {
root.style.setProperty(colorList[color].default, lighten(theme[color], 0));
if (!theme[`${color}Hover`]) {
root.style.setProperty(colorList[color].hover, lighten(theme[color], 10));
}
if (!theme[`${color}Active`]) {
root.style.setProperty(colorList[color].active, lighten(theme[color], -10));
}
}
});
}
}
细节说明:
- 只需给出主色(如
primaryColor: '#3370ff'),hover/active 色会由工具函数lighten自动推导(hover 在主色基础上加亮 10%,active 加深 10%);如果你同时提供了xxxColorHover/xxxColorActive,则以你提供的值为准。 lighten的实现位于 util.ts,它先完成 HEX → RGB → HSL 的转换,再对亮度百分比做加减,最后转回 RGB 输出(例如lighten('#666666', 20)输出'153,153,153')。对应测试见 theme.test.tsx,其中验证了"全局 CSS 变量正确写入"与"颜色加亮计算正确"两个行为。
组件级默认配置 componentConfig
componentConfig(自 2.23.0 起支持)用于为所有组件全局设置默认参数,是 ConfigProvider 最强大的能力之一。它的类型是 ComponentConfig,以组件名(含 'Avatar.Group'、'Radio.Group' 等复合组件名)为 key,值为该组件的 props 类型。
示例(来自 component-config.md):一次性把 Button 默认为 primary + round、DatePicker 默认周一为一周开始、InputNumber 默认为按钮模式、Radio.Group 默认为按钮形态、Space 默认大间距、Table 默认无边框并定制空数据文案、Tag 默认 arcoblue 大号:
import { useState } from 'react';
import {
ConfigProvider,
Button,
DatePicker,
Space,
InputNumber,
Radio,
Table,
Tag,
} from '@arco-design/web-react';
const columns = [
{ title: 'Name', dataIndex: 'name' },
{ title: 'Salary', dataIndex: 'salary' },
{ title: 'Address', dataIndex: 'address' },
{ title: 'Email', dataIndex: 'email' },
];
function App() {
const componentConfig = {
Button: {
type: 'primary',
shape: 'round',
},
DatePicker: {
dayStartOfWeek: 2,
utcOffset: 0,
},
InputNumber: {
mode: 'button',
},
'Radio.Group': {
type: 'button',
},
Space: {
size: 'large',
},
Table: {
border: false,
noDataElement: 'Oops, no data ~',
},
Tag: {
color: 'arcoblue',
size: 'large',
},
};
return (
<ConfigProvider componentConfig={componentConfig}>
<Space direction="vertical">
<Space>
<Button>Button 1</Button>
<Button status="success">Button 2</Button>
<Button type="secondary">Button 2</Button>
</Space>
<Space>
<Radio.Group options={['JavaScript', 'CSS', 'React', 'Vue']} defaultValue="JavaScript" />
<Radio.Group options={['Light', 'Dark']} defaultValue="Light" />
</Space>
<Space>
<DatePicker showTime />
<DatePicker.RangePicker />
</Space>
<Space>
<InputNumber defaultValue={2} />
<InputNumber defaultValue={3} />
</Space>
<Space>
<Tag>ArcoDesign</Tag>
<Tag>Design System</Tag>
<Tag>Component</Tag>
<Tag>Design Lab</Tag>
</Space>
<Table columns={columns} data={[]} />
</Space>
</ConfigProvider>
);
}
export default App;
注意两点:
- 局部 props 优先级更高:
componentConfig只是"默认参数",当组件自身显式传入同名属性时,组件属性会覆盖全局配置(这一合并逻辑由useMergeProps实现)。 - 部分组件对全局默认配置做了字段裁剪:例如 interface.ts 中
DatePicker的全局默认配置通过Omit排除了placeholder、onChange、onSelect、onOk、defaultPickerValue、pickerValue、onPickerValueChange、inputProps这些与具体实例强相关的字段,避免全局配置干扰单个组件的交互行为。
Table 全局分页配置 tablePagination
tablePagination(自 2.6.0 起支持)用于全局设置 Table 组件的分页属性,类型为 PaginationProps。典型场景是全局设置 hideOnSinglePage,当表格数据少于等于一页时自动隐藏分页器。
示例(来自 tablePagination.md):
import { useState } from 'react';
import { ConfigProvider, Table, Switch, Space, Typography } from '@arco-design/web-react';
const columns = [
{ title: 'Name', dataIndex: 'name' },
{ title: 'Salary', dataIndex: 'salary' },
{ title: 'Address', dataIndex: 'address' },
{ title: 'Email', dataIndex: 'email' },
];
const data = [
{ key: '1', name: 'Jane Doe', salary: 23000, address: '32 Park Road, London', email: 'jane.doe@example.com' },
{ key: '2', name: 'Alisa Ross', salary: 25000, address: '35 Park Road, London', email: 'alisa.ross@example.com' },
{ key: '3', name: 'Kevin Sandra', salary: 22000, address: '31 Park Road, London', email: 'kevin.sandra@example.com' },
];
function App() {
const [hideOnSinglePage, setHideOnSinglePage] = useState(true);
return (
<ConfigProvider
tablePagination={{
hideOnSinglePage,
}}
>
<Space style={{ marginBottom: 10 }}>
<Typography.Text>tablePagination.hideOnSinglePage</Typography.Text>
<Switch checked={hideOnSinglePage} onChange={(checked) => setHideOnSinglePage(checked)} />
</Space>
<Table columns={columns} data={data} />
</ConfigProvider>
);
}
export default App;
通过开关切换 hideOnSinglePage 的值,可以直观看到只有 3 条数据的表格分页器在 true 时被隐藏。该属性接收完整的 PaginationProps,因此 pageSize、sizeCanChange、showTotal、showJumper 等分页参数同样可以全局配置。
全局空元素 renderEmpty
renderEmpty(自 2.10.0 起支持)用于全局定义组件内部显示的空状态元素,回调参数 componentName 可以区分具体组件。示例(来自 renderEmpty.md):
import { useState } from 'react';
import {
ConfigProvider,
Cascader,
Select,
TreeSelect,
List,
Table,
Space,
Empty,
Typography,
} from '@arco-design/web-react';
function renderEmpty(componentName) {
switch (componentName) {
case 'Cascader':
return <Typography.Text>Cascader no data!</Typography.Text>;
case 'Select':
return <Typography.Text>Select no data!</Typography.Text>;
case 'TreeSelect':
return <Typography.Text>TreeSelect no data!</Typography.Text>;
case 'List':
return <Empty description="List no data!" />;
case 'Table':
return <Empty description="Table no data!" />;
default:
return <Empty />;
}
}
const App = () => {
return (
<ConfigProvider renderEmpty={renderEmpty}>
<Space>
<Cascader style={{ width: 200 }} placeholder="Cascader" />
<Select style={{ width: 200 }} placeholder="Select" />
<TreeSelect style={{ width: 200 }} placeholder="TreeSelect" />
</Space>
<List header="Empty List" style={{ marginTop: 20 }}/>
<Table
data={[]}
columns={[
{ title: 'Name', key: 'name' },
{ title: 'Age', key: 'age' },
]}
style={{ marginTop: 20 }} />
</ConfigProvider>
);
};
export default App;
从 context.tsx 可以看到,默认的 renderEmpty 实现是对所有组件统一返回 <Empty />;覆盖后即可按组件类型定制不同的空状态(如 Table 显示"Table no data!"、Select 显示"Select no data!")。
RTL 视图:从右向左的布局
rtl(自 2.36.0 起支持)将组件视图切换为从右向左(Right-to-Left)阅读的形式,适用于阿拉伯语、希伯来语等从右向左书写的语言环境。示例(来自 rtl.md)通过 Switch 动态切换 RTL / LTR:
import React, { useState } from 'react';
import {
ConfigProvider,
Divider,
Switch,
Space,
Badge,
Avatar,
Tabs,
Tag,
DatePicker,
Pagination,
} from '@arco-design/web-react';
const TabPane = Tabs.TabPane;
function App() {
const [rtl, setRtl] = useState(true);
return (
<div>
<Switch checkedText='RTL' uncheckedText='LTR' checked={rtl} onChange={(checked) => setRtl(checked)} />
<Divider />
<ConfigProvider rtl={rtl} effectGlobalNotice={false}>
<Tabs defaultActiveTab='1' style={{ marginBottom: 20 }}>
<TabPane key='1' title='Tab 1' />
<TabPane key='2' title='Tab 2' />
<TabPane key='3' title='Tab 3' />
</Tabs>
<Space direction="vertical" style={{ width: '100%' }}>
<Space size="large">
<Badge count={9}>
<Avatar shape='square' />
</Badge>
<Badge
count={9}
dot
dotStyle={{ width: 10, height: 10 }}
>
<Avatar shape='square' />
</Badge>
<Tag color="red" closable>red</Tag>
<Tag color="arcoblue" closable>arcoblue</Tag>
<Tag color="green" closable>green</Tag>
</Space>
<Space>
<DatePicker />
<DatePicker.RangePicker style={{ width: 300 }} />
</Space>
<Pagination defaultCurrent={5} total={200} sizeCanChange />
</Space>
</ConfigProvider>
</div>
);
}
export default App;
开启 RTL 后,Tabs、Badge、Tag、DatePicker、Pagination 等组件的排列方向与图标方向都会随之反转。实际项目中建议配合 locale 一起使用(如 ar-EG 语言包 + rtl),实现完整的阿拉伯语界面。
局部修改 Message / Notification / Modal 配置
原理:配置如何影响全局单例组件
Message、Notification 的方法调用(如 Message.info)以及 Modal.confirm 这类命令式 API 并不在组件树内渲染,因此它们无法通过 Context 读取配置。ConfigProvider 采用了另一套机制:在 index.tsx 中通过 useEffect 把配置同步给这些全局单例:
useEffect(() => {
if (effectGlobalNotice) {
Message.config({ prefixCls, rtl });
Notification.config({ prefixCls, rtl });
}
}, [prefixCls, rtl, effectGlobalNotice]);
useEffect(() => {
if (effectGlobalModal) {
setConfigProviderProps({ locale, prefixCls, rtl });
}
}, [locale, prefixCls, rtl, effectGlobalModal]);
其中 Modal 的配置写入逻辑见 components/Modal/config.ts:setConfigProviderProps 把 locale / prefixCls / rtl 存入模块级变量,Modal.confirm 等方法在执行时通过 getConfigProviderProps() 读取这些全局配置。
默认行为:配置全局生效
默认情况下,通过 ConfigProvider 设置的 prefixCls 和 rtl 会作用到所有 Message、Notification 以及所有 Modal 函数方法上。也就是说,应用最外层 ConfigProvider 设置 RTL 后,即使你在任意位置直接调用 Message.info(),其弹层也是 RTL 表现。
关闭全局生效:只影响局部
如果你希望 prefixCls / rtl 只在 ConfigProvider 内部生效,需要:
- 配合
Message.useMessage()或Notification.useNotification()的 hook 形式使用,同时把effectGlobalNotice设为false(此功能自 2.40.0 起支持); - 对于 Modal 函数方法,把
effectGlobalModal设为false(此功能自 2.61.0 起支持)。
示例(来自 local-setting.md),上半部分用 useMessage / useNotification 获取局部实例并关闭 effectGlobalNotice,使 RTL 只作用于局部;下半部分的全局调用则保持正常 LTR 视图:
import React, { useState } from 'react';
import { Button, Message, Space, ConfigProvider, Notification, Typography } from '@arco-design/web-react';
function App() {
const [message, messageHolder] = Message.useMessage();
const [notification, notificationHolder] = Notification.useNotification();
return (
<Space direction="vertical" size={20}>
<ConfigProvider rtl effectGlobalNotice={false} effectGlobalModal={false}>
<Typography.Title heading={6}> 局部 RTL 视图</Typography.Title>
<div className="demo-holder-wrapper">
{messageHolder}
{notificationHolder}
</div>
<Space>
<Button
onClick={() => {
message.info && message.info('This is an info message!');
}}
type="primary"
>
Open Message
</Button>
<Button
onClick={() => {
notification.info && notification.info({
closable: true,
title: 'Notification',
content: 'This is a notification!',
});
}}
type="primary"
>
Open Notification
</Button>
</Space>
</ConfigProvider>
<div>
<Typography.Title heading={6}> 正常视图 </Typography.Title>
<Space>
<Button
onClick={() => {
Message.info('This is an info message!');
}}
>
Open Message
</Button>
<Button
onClick={() => {
Notification.info({
closable: true,
title: 'Notification',
content: 'This is a notification!',
});
}}
>
Open Notification
</Button>
</Space>
</div>
</Space>
);
}
export default App;
.demo-holder-wrapper .arco-message-wrapper {
left: 0;
}
Modal 的局部配置同理(来自 modal-setting.md):关闭 effectGlobalModal 后,ConfigProvider 内的 RTL 只影响其子树,Modal.confirm 在全局调用时不再被该局部配置污染:
import React, { useState } from 'react';
import { Button, Space, ConfigProvider, Modal, Typography,Tabs } from '@arco-design/web-react';
function App() {
const confirm = () => {
Modal.confirm({
title: 'Confirm deletion',
content: 'Are you sure you want to delete the 3 selected items? Once you press the delete button, the items will be deleted immediately. You can’t undo this action.',
okButtonProps: {
status: 'danger',
},
onOk: () => {
return new Promise((resolve, reject) => {
setTimeout(Math.random() > 0.5 ? resolve : reject, 1000);
}).catch((e) => {
Message.error({
content: 'Error occurs!',
});
throw e;
});
},
});
};
return (
<Space direction="vertical" size={20}>
<ConfigProvider rtl effectGlobalNotice={false} effectGlobalModal={false}>
<Typography.Title heading={6}>局部 RTL 视图</Typography.Title>
<Tabs defaultActiveTab='1' style={{ marginBottom: 20 }}>
<Tabs.TabPane key='1' title='Tab 1' />
<Tabs.TabPane key='2' title='Tab 2' />
<Tabs.TabPane key='3' title='Tab 3' />
</Tabs>
<Space>
<Button type='primary' onClick={confirm}>
Confirm
</Button>
</Space>
</ConfigProvider>
</Space>
);
}
export default App;
提示:
Message.useMessage()返回的 hook 实例会携带所在ConfigProvider的上下文配置,因此即使全局effectGlobalNotice为true,hook 实例本身也支持局部 RTL 效果;两个开关主要用于决定"非 hook 的全局静态调用"是否同步 ConfigProvider 的配置。
其余全局参数速览
除上述能力外,ConfigProvider 还提供以下参数:
- prefixCls:全局组件类名前缀,默认
arco。所有组件的类名由getPrefixCls(componentName)生成,即${prefixCls}-${componentName},例如默认情况下 Button 根类名为arco-btn。修改后可实现主题样式隔离或自定义命名空间;当prefixCls非arco时,ConfigProvider 还会额外用IconContext.Provider同步图标前缀(见 index.tsx)。 - size:配置组件的默认尺寸,取值
'mini' | 'small' | 'default' | 'large',默认default。只对支持size属性的组件生效。 - autoInsertSpaceInButton(2.3.0):当按钮内恰为两个汉字时,自动在中间插入一个空格,提升排版可读性。
- loadingElement:全局加载中图标(ReactNode),作用于所有支持 loading 的组件。
- getPopupContainer:全局弹出层挂载的父级节点,签名
(node: HTMLElement) => Element,默认() => document.body,常用于解决弹层被overflow: hidden容器裁剪的问题。 - focusLock(2.13.0):全局配置弹出层的焦点锁定与自动聚焦,作用于
Modal、Drawer。类型为{ modal?: boolean | { autoFocus?: boolean }; drawer?: boolean | { autoFocus?: boolean } },默认值{ modal: { autoFocus: true }, drawer: { autoFocus: true } }。 - zIndex:全局 zIndex 基础值(见 interface.ts)。
API 参考
ConfigProvider 属性总览
| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| autoInsertSpaceInButton | 当按钮中是两个汉字时,自动在两个汉字中添加一个空格。 | boolean | - |
2.3.0 |
| effectGlobalModal | 是否全局设置所有 Modal 的配置。 |
boolean | true |
2.61.0 |
| effectGlobalNotice | 是否全局设置所有 Message 和 Notification 的配置。如果用了 useMessage 的 hook 局部设置请设置为 false |
boolean | true |
2.40.0 |
| rtl | 视图的表现形式是从右开始向左结束。 | boolean | - |
2.36.0 |
| prefixCls | 全局组件类名前缀 | string | arco |
- |
| size | 配置组件的默认尺寸,只会对支持 size 属性的组件生效。 |
'mini' | 'small' | 'default' | 'large' | default |
- |
| loadingElement | 全局的加载中图标,作用于所有组件。 | ReactNode | - |
- |
| componentConfig | 用于全局配置所有组件的默认参数 | ComponentConfig | - |
2.23.0 |
| focusLock | 全局配置弹出框的 focusLock,作用于 Modal Drawer 组件。 |
{modal?: boolean | { autoFocus?: boolean };drawer?: boolean | { autoFocus?: boolean };} | { modal: { autoFocus: true }, drawer: { autoFocus: true } } |
2.13.0 |
| locale | 设置语言包 | Locale | - |
- |
| tablePagination | Table 全局的分页配置。 | PaginationProps | - |
2.6.0 |
| theme | 主题配置 | ThemeConfig | - |
- |
| getPopupContainer | 全局弹出框挂载的父级节点。 | (node: HTMLElement) => Element | () => document.body |
- |
| renderEmpty | 全局配置组件内的空组件。 | (componentName?: string) => ReactNode | - |
2.10.0 |
ComponentConfig
componentConfig 的完整类型定义(与 interface.ts 一致),覆盖了组件库中几乎所有组件,包括复合组件名:
export type ComponentConfig = {
Affix?: AffixProps;
Alert?: AlertProps;
AutoComplete?: AutoCompleteProps;
Avatar?: AvatarProps;
"Avatar.Group"?: AvatarGroupProps;
Anchor?: AnchorProps;
"Anchor.Link"?: AnchorLinkProps;
BackTop?: BackTopProps;
Badge?: BadgeProps;
Breadcrumb?: BreadcrumbProps;
Button?: ButtonProps;
Calendar?: CalendarProps;
Card?: CardProps;
Carousel?: CarouselProps;
Cascader?: CascaderProps;
Checkbox?: CheckboxProps;
Collapse?: CollapseProps;
Comment?: CommentProps;
ColorPicker?: ColorPickerProps;
DatePicker?: Omit<
DatePickerCommonProps,
| "placeholder"
| "onChange"
| "onSelect"
| "onOk"
| "defaultPickerValue"
| "pickerValue"
| "onPickerValueChange"
| "inputProps"
>;
Descriptions?: DescriptionsProps;
Divider?: DividerProps;
Drawer?: DrawerProps;
Dropdown?: DropdownProps;
"Dropdown.Button"?: DropdownButtonProps;
Empty?: EmptyProps;
"Typography.Ellipsis"?: TypographyEllipsisProps;
Form?: FormProps;
"Grid.Row"?: RowProps;
"Grid.Col"?: ColProps;
Grid?: GridProps;
"Grid.GridItem"?: GridItemProps;
Image?: ImageProps;
Input?: InputProps;
InputNumber?: InputNumberProps;
VerificationCode?: VerificationCodeProps;
Watermark?: WatermarkProps;
InputTag?: InputTagProps;
Layout?: LayoutProps;
Link?: LinkProps;
List?: ListProps;
"List.Item"?: ListItemProps;
Mentions?: MentionsProps;
Menu?: MenuProps;
Modal?: ModalProps;
PageHeader?: PageHeaderProps;
Pagination?: PaginationProps;
Popconfirm?: PopconfirmProps;
Popover?: PopoverProps;
Progress?: ProgressProps;
Radio?: RadioProps;
"Radio.Group"?: RadioGroupProps;
Rate?: RateProps;
ResizeBox?: ResizeBoxProps;
Result?: ResultProps;
Select?: SelectProps;
Skeleton?: SkeletonProps;
Slider?: SliderProps;
Space?: SpaceProps;
Spin?: SpinProps;
Statistic?: StatisticProps;
Steps?: StepsProps;
Switch?: SwitchProps;
Table?: TableProps;
Tabs?: TabsProps;
TreeProps?: TreeProps;
TriggerProps?: TriggerProps;
Tag?: TagProps;
Timeline?: TimelineProps;
"Timeline.Item"?: TimelineItemProps;
TimePicker?: TimePickerCommonProps;
Tooltip?: TooltipProps;
Transfer?: TransferProps;
Tree?: TreeProps;
TreeSelect?: TreeSelectProps;
Trigger?: TriggerProps;
Upload?: UploadProps;
};
注意 interface.ts 中还包含 'Input.TextArea' 一项,完整类型以源码为准。
Locale
locale 语言包的结构(与 components/locale/interface.tsx 一致),按组件维度组织文案:
export interface Locale {
locale: string;
dayjsLocale?: string;
Calendar: CalendarType;
DatePicker: {
Calendar: CalendarType;
[key: string]: any;
};
Drawer: Record<string, any>;
Empty: Record<string, any>;
Modal: Record<string, any>;
Pagination: Record<string, any>;
Popconfirm: Record<string, any>;
Table: Record<string, any>;
TimePicker: Record<string, any>;
Upload: Record<string, any>;
Progress: Record<string, any>;
Typography: Record<string, any>;
Transfer: Record<string, any>;
ImagePreview: Record<string, any>;
Form?: Record<string, any>;
ColorPicker: Record<string, any>;
}
CalendarType
Locale 中日历相关文案的结构:
type CalendarType = {
today: string;
view: Record<string, any>;
month: {
short: Record<string, any>;
long: Record<string, any>;
};
week: {
short: Record<string, any>;
long: Record<string, any>;
};
formatYear?: string;
formatMonth?: string;
monthBeforeYear?: boolean;
};
(接口源码中另含 monthFormat、yearFormat 可选字段,见 components/locale/interface.tsx。)
ThemeConfig
export type ThemeConfig = Record<string, any>;
设计细节与最佳实践
- 组合使用以构建多语言 + 多主题站点:将
locale、theme、rtl、componentConfig同时挂在最外层ConfigProvider上,配合 state 即可实现运行时语言、主题、布局方向的动态切换,无需逐个组件传参。 - 局部配置与全局配置隔离:当页面内存在需要特殊 RTL / prefixCls 的局部区域时,用内层
ConfigProvider包裹,并按需关闭effectGlobalNotice/effectGlobalModal,避免影响全局静态调用。 - 默认值认知:未显式传入的
locale为仓库内置的 default.tsx 语言包,prefixCls为arco,getPopupContainer为() => document.body,size为default,focusLock默认开启 Modal / Drawer 的autoFocus(见 context.tsx)。 - 测试保障:组件库通过 demo.test.ts 对上述全部 demo 进行快照与渲染回归测试,确保
locale、theme、componentConfig等配置的稳定行为。
版本演进脉络
根据 changelog/index.zh-CN.md,ConfigProvider 的核心能力按如下版本逐步增强:
- 2.3.0:新增
autoInsertSpaceInButton; - 2.4.0:暴露
ConfigContext(ConfigProvider.ConfigContext); - 2.6.0:新增全局 Table 分页配置
tablePagination; - 2.10.0:新增
renderEmpty全局空元素; - 2.13.0:新增全局
focusLock与autoFocus(作用于 Modal / Drawer); - 2.23.0:新增
componentConfig,可全局配置所有组件的默认参数; - 2.28.0:支持法语、意大利语、德语、西班牙语语言包;
- 2.33.0:
componentConfig支持Timeline.Item; - 2.40.0:新增
effectGlobalNotice,支持局部控制 Message / Notification 配置; - 2.59.1:修复 Notice 调用时误改默认值的问题;
- 2.61.0:新增
effectGlobalModal,支持局部控制 Modal 配置。
小结
ConfigProvider 是 Arco Design 应用架构中的"总控开关":locale 统一语言、theme 动态换色、componentConfig 批量设定组件默认参数、tablePagination 统一表格分页、renderEmpty 定制空状态、rtl 切换阅读方向,另有 prefixCls、size、focusLock、getPopupContainer 等基础设施参数。其实现分别依托 React Context 注入与模块级全局配置同步(index.tsx、Modal/config.ts)两套机制,配合 useMergeProps 完成"默认值 → 全局配置 → 组件 props"的优先级合并。掌握这些用法与原理,你就能以最小的侵入成本构建高度可配置、可国际化的企业级界面。