全局化配置

为组件提供统一的全局化配置。

使用

ConfigProvider 使用 React 的 context 特性，只需在应用外围包裹一次即可全局生效。

import React from 'react';
import { ConfigProvider } from 'antd';

// ...
const Demo: React.FC = () => (
  <ConfigProvider direction="rtl">
    <App />
  </ConfigProvider>
);

export default Demo;

内容安全策略（CSP）

部分组件为了支持波纹效果，使用了动态样式。如果开启了 Content Security Policy (CSP)，你可以通过 csp 属性来进行配置：

<ConfigProvider csp={{ nonce: 'YourNonceCode' }}>
  <Button>My Button</Button>
</ConfigProvider>

代码演示

• 国际化 · locale
• 方向 · direction
• 组件尺寸 · size
• 主题 · theme
• 自定义波纹 · wave
• 静态方法 · holderRender

API

ConfigProvider.config()

设置 Modal、Message、Notification 静态方法配置，只会对非 hooks 的静态方法调用生效。

ConfigProvider.config({
  // 5.13.0+
  holderRender: (children) => (
    <ConfigProvider
      prefixCls="ant"
      iconPrefixCls="anticon"
      theme={{ token: { colorPrimary: 'red' } }}
    >
      {children}
    </ConfigProvider>
  ),
});

ConfigProvider.useConfig() <Badge>5.3.0+</Badge>

获取父级 Provider 的值，如 DisabledContextProvider、SizeContextProvider。

const {
  componentDisabled, // 5.3.0+
  componentSize, // 5.3.0+
} = ConfigProvider.useConfig();

组件配置

以下配置项用于设置对应组件的通用属性或全局效果配置，具体 API 见链接：

• affix：Affix（自 6.0.0 起支持）
• alert：Alert（自 5.7.0 起支持）
• anchor：Anchor（自 6.0.0 起支持）
• app：App（自 6.3.0 起支持）
• avatar：Avatar（自 5.7.0 起支持）
• badge：Badge（自 5.7.0 起支持）
• borderBeam：BorderBeam（自 6.4.0 起支持）
• breadcrumb：Breadcrumb（自 5.7.0 起支持）
• button：Button（自 5.6.0 起支持）
• calendar：Calendar（自 6.0.0 起支持）
• card：Card（自 5.14.0 起支持）
• cardMeta：Card.Meta（自 6.0.0 起支持）
• carousel：Carousel（自 5.7.0 起支持）
• cascader：Cascader（自 5.13.0 起支持）
• checkbox：Checkbox（自 6.0.0 起支持）
• collapse：Collapse（自 5.15.0 起支持）
• colorPicker：ColorPicker（自 6.3.0 起支持）
• datePicker：DatePicker（自 5.7.0 起支持）
• rangePicker：RangePicker（自 5.11.0 起支持）
• descriptions：Descriptions（自 5.23.0 起支持）
• divider：Divider（自 5.10.0 起支持）
• drawer：Drawer（自 5.10.0 起支持）
• dropdown：Dropdown（自 5.11.0 起支持）
• empty：Empty（自 5.23.0 起支持）
• flex：Flex（自 5.10.0 起支持）
• floatButton：FloatButton（自 6.0.0 起支持）
• floatButtonGroup：FloatButton.Group（自 5.16.0 起支持）
• form：Form（自 4.8.0 起支持）
• image：Image（自 5.14.0 起支持）
• input：Input（自 4.2.0 起支持）
• inputNumber：InputNumber（自 5.19.0 起支持）
• otp：Input.OTP（自 6.0.0 起支持）
• inputPassword：Input.Password（自 6.4.0 起支持）
• inputSearch：Input.Search（自 6.4.0 起支持）
• textArea：Input.TextArea（自 5.15.0 起支持）
• layout：Layout（自 5.7.0 起支持）
• list：List（自 5.7.0 起支持）
• listy：Listy（自 6.6.0 起支持）
• masonry：Masonry（自 6.0.0 起支持）
• menu：Menu（自 5.15.0 起支持）
• mentions：Mentions（自 5.13.0 起支持）
• message：Message（自 5.7.0 起支持）
• modal：Modal（自 5.10.0 起支持）
• notification：Notification（自 5.14.0 起支持）
• pagination：Pagination（自 6.0.0 起支持）
• progress：Progress（自 5.7.0 起支持）
• radio：Radio（自 6.0.0 起支持）
• rate：Rate（自 5.7.0 起支持）
• result：Result（自 6.0.0 起支持）
• ribbon：Badge.Ribbon（自 6.0.0 起支持）
• skeleton：Skeleton（自 6.0.0 起支持）
• segmented：Segmented（自 6.0.0 起支持）
• select：Select（自 5.13.0 起支持）
• slider：Slider（自 5.23.0 起支持）
• switch：Switch（自 6.0.0 起支持）
• space：Space（自 5.6.0 起支持）
• splitter：Splitter（自 5.21.0 起支持）
• spin：Spin（自 5.20.0 起支持）
• statistic：Statistic（自 6.0.0 起支持）
• steps：Steps（自 5.10.0 起支持）
• table：Table（自 6.2.0 起支持）
• tabs：Tabs（自 5.14.0 起支持）
• tag：Tag（自 5.14.0 起支持）
• timeline：Timeline（自 6.0.0 起支持）
• timePicker：TimePicker（自 5.13.0 起支持）
• tour：Tour（自 5.14.0 起支持）
• tooltip：Tooltip（自 6.1.0 起支持）
• popover：Popover（自 5.23.0 起支持）
• popconfirm：Popconfirm（自 5.23.0 起支持）
• qrcode：QRCode（自 6.0.0 起支持）
• transfer：Transfer（自 5.7.0 起支持）
• tree：Tree（自 6.0.0 起支持）
• treeSelect：TreeSelect（自 5.19.0 起支持）
• typography：Typography（自 6.4.0 起支持）
• upload：Upload（自 5.27.0 起支持）
• watermark：Watermark（自 6.0.0 起支持）
• wave：WaveConfig（自 5.8.0 起支持）

WaveConfig

FAQ

如何增加一个新的语言包？

参考《增加语言包》。

为什么时间类组件的国际化 locale 设置不生效？

参考 FAQ 为什么时间类组件的国际化 locale 设置不生效？。

配置 getPopupContainer 导致 Modal 报错？

相关 issue：https://github.com/ant-design/ant-design/issues/19974

当如下全局设置 getPopupContainer 为触发节点的 parentNode 时，由于 Modal 的用法不存在 triggerNode，这样会导致 triggerNode is undefined 的报错，需要增加一个判断条件。

 <ConfigProvider
-  getPopupContainer={triggerNode => triggerNode.parentNode}
+  getPopupContainer={node => {
+    if (node) {
+      return node.parentNode;
+    }
+    return document.body;
+  }}
 >
   <App />
 </ConfigProvider>

为什么 message.info、notification.open 或 Modal.confirm 等方法内的 ReactNode 无法继承 ConfigProvider 的属性？比如 prefixCls 和 theme。

静态方法是使用 ReactDOM.render 重新渲染一个 React 根节点上，和主应用的 React 节点是脱离的。我们建议使用 useMessage、useNotification 和 useModal 来使用相关方法。原先的静态方法在 5.0 中已被废弃。

Vite 生产模式打包后国际化 locale 设置不生效？

相关 issue：#39045

由于 Vite 生产模式下打包与开发模式不同，cjs 格式的文件会多一层，需要 zhCN.default 来获取。推荐 Vite 用户直接从 antd/es/locale 目录下引入 esm 格式的 locale 文件。

prefixCls 优先级(前者被后者覆盖)

1. ConfigProvider.config({ prefixCls: 'prefix-1' })
2. ConfigProvider.config({ holderRender: (children) => <ConfigProvider prefixCls="prefix-2">{children}</ConfigProvider> })
3. message.config({ prefixCls: 'prefix-3' })

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

• vendor/components/config-provider/DisabledContext.tsx
• vendor/components/config-provider/MotionWrapper.tsx
• vendor/components/config-provider/PropWarning.tsx
• vendor/components/config-provider/SizeContext.tsx
• vendor/components/config-provider/context.ts
• vendor/components/config-provider/defaultRenderEmpty.tsx
• vendor/components/config-provider/index.tsx

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。