Arco Design ConfigProvider 全局配置完全指南:国际化、主题、组件默认参数与 RTL 布局

原创2026-10-12 23:13:001,928 阅读
文章标签:UI组件前端设计系统

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;

注意两点:

  1. 局部 props 优先级更高:componentConfig 只是"默认参数",当组件自身显式传入同名属性时,组件属性会覆盖全局配置(这一合并逻辑由 useMergeProps 实现)。
  2. 部分组件对全局默认配置做了字段裁剪:例如 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>;

设计细节与最佳实践

  1. 组合使用以构建多语言 + 多主题站点:将 locale、theme、rtl、componentConfig 同时挂在最外层 ConfigProvider 上,配合 state 即可实现运行时语言、主题、布局方向的动态切换,无需逐个组件传参。
  2. 局部配置与全局配置隔离:当页面内存在需要特殊 RTL / prefixCls 的局部区域时,用内层 ConfigProvider 包裹,并按需关闭 effectGlobalNotice / effectGlobalModal,避免影响全局静态调用。
  3. 默认值认知:未显式传入的 locale 为仓库内置的 default.tsx 语言包,prefixCls 为 arco,getPopupContainer 为 () => document.body,size 为 default,focusLock 默认开启 Modal / Drawer 的 autoFocus(见 context.tsx)。
  4. 测试保障:组件库通过 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"的优先级合并。掌握这些用法与原理,你就能以最小的侵入成本构建高度可配置、可国际化的企业级界面。

登录后查看全文
arco-design