source/ant-design
1
0
Fork 0
mirror of https://github.com/ant-design/ant-design.git synced 2026-02-09 02:49:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: v5 -> v6 (#55783)

Browse Source 
* docs: v5 -> v6

* docs: update docs

* docs: update docs
This commit is contained in:
二货爱吃白萝卜
2025-11-21 14:36:44 +08:00
committed by GitHub
parent f3a03f2372
commit 241a2b27de
4 changed files with 256 additions and 750 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
docs/react/migration-v5.en-US.md
View File

@@ -1,378 +0,0 @@
---
group:
title: Migration
order: 2
order: 0
title: V4 to V5
---
This document will help you upgrade from antd `4.x` version to antd `5.x` version. If you are using `3.x` or older version, please refer to the previous [upgrade document](https://4x.ant.design/docs/react/migration-v4) to 4.x.
## Upgrade preparation
1. Please upgrade to the latest version of 4.x first, and remove / modify related APIs according to the console warning message.
## Incompatible changes in v5
### Design specification
- Basic rounded corner adjustment, changed from `2px` to four layers of radius, which are `2px` `4px` `6px` and `8px`. For example, radius of default Button is modified from `2px` to `6px`.
- Primary color adjustment, changed from `#1890ff` to `#1677ff`.
- Global shadow optimization, adjusted from three layers of shadows to two layers, which are used in common components (Card .e.g) and popup components (Dropdown .e.g).
- Overall reduction in wireframe usage.
### Technology adjustment
- Remove less, adopt CSS-in-JS, for better support of dynamic themes. The bottom layer uses [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) as a solution.
- All less files are removed, and less variables are no longer exported.
- CSS files are no longer included in package. Since CSS-in-JS supports importing on demand, the original `antd/dist/antd.css` has also been abandoned. If you need to reset some basic styles, please import `antd/dist/reset.css`.
- If you need to reset the style of the component, but you don't want to introduce `antd/dist/reset.css` to pollute the global style, You can try using the [App](/components/app) in the outermost layer to solve the problem that native elements do not have antd specification style.
- Remove css variables and dynamic theme built on top of them.
- LocaleProvider has been deprecated in 4.x (use `<ConfigProvider locale />` instead), we removed the related folder `antd/es/locale-provider` and `antd/lib/locale-provider` in 5.x.
- Replace built-in Moment.js with Dayjs. For more: [Use custom date library](/docs/react/use-custom-date-library/).
- `babel-plugin-import` is no longer supported. CSS-in-JS itself has the ability to import on demand, and plugin support is no longer required. Umi users can remove related configurations.
```diff
// config/config.ts
export default {
antd: {
- import: true,
},
};
```
### Compatibility
- DO NOT support IE browser anymore.
#### Component API adjustment
- The classname API of the component popup box is unified to `popupClassName`, and `dropdownClassName` and other similar APIs will be replaced.
- AutoComplete
- Cascader
- Select
- TreeSelect
- TimePicker
- DatePicker
- Mentions
```diff
import { Select } from 'antd';
const App: React.FC = () => (
<Select
- dropdownClassName="my-select-popup"
+ popupClassName="my-select-popup"
/>
);
export default App;
```
- The controlled visible API of the component popup is unified to `open`, and `visible` and other similar APIs will be replaced.
- Drawer `visible` changed to `open`.
- Modal `visible` changed to `open`.
- Dropdown `visible` changed to `open`.
- Tooltip `visible` changed to `open`.
- Tag `visible` is removed.
- Slider `tooltip` related API converged to `tooltip` property.
- Table `filterDropdownVisible` changed to `filterDropdownOpen`.
```diff
import { Modal, Tag, Table, Slider } from 'antd';
const App: React.FC = () => {
const [visible, setVisible] = useState(true);
return (
<>
- <Modal visible={visible}>content</Modal>
+ <Modal open={visible}>content</Modal>
- <Tag visible={visible}>tag</Tag>
+ {visible && <Tag>tag</Tag>}
<Table
data={[]}
columns={[
{
title: 'Name',
dataIndex: 'name',
- filterDropdownVisible: visible,
+ filterDropdownOpen: visible,
}
]}
/>
- <Slider tooltipVisible={visible} />
+ <Slider tooltip={{ open: visible }} />
</>
);
}
export default App;
```
- `getPopupContainer`: All `getPopupContainer` are guaranteed to return a unique div. This method will be called repeatedly under React 18 concurrent mode.
- Upload List structure changes. [#34528](https://github.com/ant-design/ant-design/pull/34528)
- Notification
- Static methods are no longer allowed to dynamically set `prefixCls` `maxCount` `top` `bottom` `getContainer` in `open`, Notification static methods will now have only one instance. If you need a different configuration, use `useNotification`.
- `close` was renamed to `destroy` to be consistent with message.
- Drawer `style` & `className` are migrated to Drawer panel node, the original properties are replaced by `rootClassName` and `rootStyle`.
- The deprecated `message.warn` in 4.x is now completely removed, please use `message.warning` instead.
#### Component refactoring and removal
- Remove `locale-provider` Directory. `LocaleProvider` was removed in v4, please use `ConfigProvider` instead.
- Move Comment component into `@ant-design/compatible`.
- Move PageHeader component into `@ant-design/pro-components`.
```diff
- import { PageHeader, Comment } from 'antd';
+ import { Comment } from '@ant-design/compatible';
+ import { PageHeader } from '@ant-design/pro-components';
const App: React.FC = () => (
<>
<PageHeader />
<Comment />
</>
);
export default App;
```
- BackTop is deprecated in `5.0.0`, and is merged into FloatButton.
```diff
- import { BackTop } from 'antd';
+ import { FloatButton } from 'antd';
const App: React.FC = () => (
<div>
- <BackTop />
+ <FloatButton.BackTop />
</div>
);
export default App;
```
## Start upgrading
Use git to save your code and install latest version:
```bash
npm install --save antd@5.x
```
If you want to use v4 deprecated component like `Comment` or `PageHeader`. You can install `@ant-design/compatible` and `@ant-design/pro-components` for compatible:
```bash
npm install --save @ant-design/compatible@v5-compatible-v4
npm install --save @ant-design/pro-components
```
You can manually check the code one by one against the above list for modification. In addition, we also provide a codemod cli tool [@ant-design/codemod-v5](https://github.com/ant-design/codemod-v5) To help you quickly upgrade to v5.
Before running codemod cli, please submit your local code changes.
```shell
# Run directly through npx
npx -p @ant-design/codemod-v5 antd5-codemod src
# Or run directly through pnpm
pnpm --package=@ant-design/codemod-v5 dlx antd5-codemod src
```
<video autoplay="" loop="" style="width: 100%; max-height: 600px; object-fit: contain;">
<source src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/file/A*Sjy5ToW6ow0AAAAAAAAAAAAADrJ8AQ" type="video/webm">
<source src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/file/A*hTDYQJ2HFTYAAAAAAAAAAAAADrJ8AQ" type="video/mp4">
</video>
> Note that codemod cannot cover all scenarios, and it is recommended to check for incompatible changes one by one.
### less migration
If you using antd less variables, you can use compatible package to covert it into v4 less variables and use less-loader to inject them:
```js
const { theme } = require('antd/lib');
const { convertLegacyToken, defaultTheme } = require('@ant-design/compatible/lib');
const { defaultAlgorithm, defaultSeed } = theme;
const mapV5Token = defaultAlgorithm(defaultSeed);
const v5Vars = convertLegacyToken(mapV5Token);
const mapV4Token = theme.getDesignToken(defaultTheme);
const v4Vars = convertLegacyToken(mapV4Token);
// Webpack Config
module.exports = {
// ... other config
loader: 'less-loader',
options: {
lessOptions: {
modifyVars: v5Vars, // or v4Vars
},
},
};
```
And then remove antd less reference in your less file:
```diff
// Your less file
-- @import (reference) '~antd/es/style/themes/index';
or
-- @import '~antd/es/style/some-other-less-file-ref';
```
### Remove babel-plugin-import
Remove `babel-plugin-import` from package.json and modify `.babelrc`:
```diff
"plugins": [
- ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
]
```
Umi user can disable by config：
```diff
// config/config.ts or .umirc
export default {
antd: {
- import: true,
+ import: false,
},
};
```
### Replace Day.js locale
Replace moment.js locale with day.js locale:
```diff
- import moment from 'moment';
+ import dayjs from 'dayjs';
- import 'moment/locale/zh-cn';
+ import 'dayjs/locale/zh-cn';
- moment.locale('zh-cn');
+ dayjs.locale('zh-cn');
```
🚨 You need to pay attention to the day.js plugin system. If you find that the function originally in moment.js cannot be used in day.js, please refer to the [day.js plugin document](https://day.js.org/docs/en/plugin/plugin).
If you do not want to replace with day.js, you can use `@ant-design/moment-webpack-plugin` to keep moment.js:
```bash
npm install --save-dev @ant-design/moment-webpack-plugin
```
```javascript
// webpack-config.js
import AntdMomentWebpackPlugin from '@ant-design/moment-webpack-plugin';
module.exports = {
// ...
plugins: [new AntdMomentWebpackPlugin()],
};
```
### Switch to theme of v4
If you don't want the style to change after upgrade, we have provided a v4 theme in `@ant-design/compatible` that can restore v4 style.
````diff
```sandpack
const sandpackConfig = {
dependencies: {
'@ant-design/compatible': 'v5-compatible-v4',
},
};
import {
defaultTheme, // Default theme
darkTheme, // Dark theme
} from '@ant-design/compatible';
import { ConfigProvider, Button, Radio, Space } from 'antd';
export default () => (
<ConfigProvider theme={defaultTheme}>
<Space direction="vertical">
<Button type="primary">Button</Button>
<Radio.Group>
<Radio value={1}>A</Radio>
<Radio value={2}>B</Radio>
<Radio value={3}>C</Radio>
<Radio value={4}>D</Radio>
</Radio.Group>
</Space>
</ConfigProvider>
);
````
### Legacy browser support
Ant Design v5 using `:where` css selector to reduce CSS-in-JS hash priority. You can use `@ant-design/cssinjs` `StyleProvider` to cancel this function. Please ref [Compatible adjustment](/docs/react/customize-theme#compatible-adjustment).
## Multiple versions coexist
We do not recommend multiple versions coexist, it will make the application more complex (such as style override, ConfigProvider not reused, etc.). It's better to use micro-applications such as [qiankun](https://qiankun.umijs.org/) for page level development.
### Install v5 through alias
```bash
$ npm install --save antd-v5@npm:antd@5
# or
$ yarn add antd-v5@npm:antd@5
# or
$ pnpm add antd-v5@npm:antd@5
```
The package.json will be:
```json
{
"antd": "4.x",
"antd-v5": "npm:antd@5"
}
```
Now, antd in your project is still v4, and antd-v5 is v5.
```tsx
import React from 'react';
import { Button as Button4 } from 'antd'; // v4
import { Button as Button5 } from 'antd-v5'; // v5
export default () => (
<>
<Button4 />
<Button5 />
</>
);
```
Then config `prefixCls` of ConfigProvider to avoid style conflict:
```tsx
import React from 'react';
import { ConfigProvider as ConfigProvider5 } from 'antd-v5';
export default () => (
<ConfigProvider5 prefixCls="ant5">
<MyApp />
</ConfigProvider5>
);
```
## Encounter problems
If you encounter problems during the upgrade, please go to [GitHub issues](https://new-issue.ant.design/) for feedback. We will respond and improve this document as soon as possible.

372
docs/react/migration-v5.zh-CN.md
View File

@@ -1,372 +0,0 @@
---
group:
title: 迁移
order: 2
order: 0
title: 从 v4 到 v5
---
本文档将帮助你从 antd `4.x` 版本升级到 antd `5.x` 版本，如果你是 `3.x` 或者更老的版本，请先参考之前的[升级文档](https://4x.ant.design/docs/react/migration-v4-cn)升级到 4.x。
## 升级准备
1. 请先升级到 4.x 的最新版本，按照控制台 warning 信息移除/修改相关的 API。
## 5.0 有哪些不兼容的变化
### 设计规范调整
- 基础圆角调整，由统一的 `2px` 改为四级圆角，分别为 `2px` `4px` `6px` `8px`，分别应用于不同场景，比如默认尺寸的 Button 的圆角调整为了 `6px`。
- 主色调整，由 `#1890ff` 改为 `#1677ff`。
- 整体阴影调整，由原本的三级阴影调整为两级，分别用于常驻页面的组件（如 Card）和交互反馈（如 Dropdown）。
- 部分组件内间距调整。
- 整体去线框化。
### 技术调整
- 弃用 less，采用 CSS-in-JS，更好地支持动态主题。底层使用 [@ant-design/cssinjs](https://github.com/ant-design/cssinjs) 作为解决方案。
- 所有 less 文件全部移除，less 变量不再支持透出。
- 产物中不再包含 css 文件。由于 CSS-in-JS 支持按需引入，原本的 `antd/dist/antd.css` 也已经移除，如果需要重置一些基本样式请引入 `antd/dist/reset.css`。
- 如果需要组件重置样式，又不想引入 `antd/dist/reset.css` 从而导致污染全局样式的话，可以尝试在应用最外层使用[App 组件](/components/app-cn)，解决原生元素没有 antd 规范样式的问题。
- 移除 css variables 以及在此之上构筑的动态主题方案。
- LocaleProvider 在 4.x 中已经废弃（使用 `<ConfigProvider locale />` 替代），我们在 5.x 里彻底移除了相关目录 `antd/es/locale-provider`、`antd/lib/locale-provider`。
- 内置的时间库使用 Dayjs 替代 Moment.js，具体请查看 [使用自定义日期库](/docs/react/use-custom-date-library-cn/)。
- 不再支持 `babel-plugin-import`，CSS-in-JS 本身具有按需加载的能力，不再需要插件支持。
### 兼容性调整
- 不再支持 IE 浏览器。
#### 组件 API 调整
- 组件弹框的 classname API 统一为 `popupClassName`，`dropdownClassName` 等类似 API 都会被替换。
- AutoComplete 组件
- Cascader 组件
- Select 组件
- TreeSelect 组件
- TimePicker 组件
- DatePicker 组件
- Mentions 组件
```diff
import { Select } from 'antd';
const App: React.FC = () => (
<Select
- dropdownClassName="my-select-popup"
+ popupClassName="my-select-popup"
/>
);
export default App;
```
- 组件弹框的受控可见 API 统一为 `open`，`visible` 等类似 API 都会被替换。
- Drawer 组件 `visible` 变为 `open`。
- Modal 组件 `visible` 变为 `open`。
- Dropdown 组件 `visible` 变为 `open`。
- Tooltip 组件 `visible` 变为 `open`。
- Tag 组件 `visible` 已移除。
- Slider 组件 `tooltip` 相关 API 收敛到 `tooltip` 属性中。
- Table 组件 `filterDropdownVisible` 变为 `filterDropdownOpen`。
```diff
import { Modal, Tag, Table, Slider } from 'antd';
const App: React.FC = () => {
const [visible, setVisible] = useState(true);
return (
<>
- <Modal visible={visible}>content</Modal>
+ <Modal open={visible}>content</Modal>
- <Tag visible={visible}>tag</Tag>
+ {visible && <Tag>tag</Tag>}
<Table
data={[]}
columns={[
{
title: 'Name',
dataIndex: 'name',
- filterDropdownVisible: visible,
+ filterDropdownOpen: visible,
}
]}
/>
- <Slider tooltipVisible={visible} />
+ <Slider tooltip={{ open: visible }} />
</>
);
}
export default App;
```
- `getPopupContainer`: 所有的 `getPopupContainer` 都需要保证返回的是唯一的 div。React 18 concurrent 下会反复调用该方法。
- Upload List dom 结构变化。[#34528](https://github.com/ant-design/ant-design/pull/34528)
- Notification
- 静态方法不再允许在 `open` 中动态设置 `prefixCls` `maxCount` `top` `bottom` `getContainer`，Notification 静态方法现在将只有一个实例。如果需要不同配置，请使用 `useNotification`。
- `close` 改名为 `destroy`，和 message 保持一致。
- Drawer `style` 和 `className` 迁移至 Drawer 弹层区域上，原属性替换为 `rootClassName` 和 `rootStyle`。
- 4.x 中已经废弃的 `message.warn` 现在被彻底移除，请使用 `message.warning` 代替。
#### 组件重构与移除
- 移除 `locale-provider` 目录。`LocaleProvider` 在 v4 中已移除，请使用 `ConfigProvider` 替代。
- 移除 Comment 组件，移至 `@ant-design/compatible` 中维护。
- 移除 PageHeader 组件，移至 `@ant-design/pro-components` 中维护。
```diff
- import { PageHeader, Comment } from 'antd';
+ import { Comment } from '@ant-design/compatible';
+ import { PageHeader } from '@ant-design/pro-components';
// 如果是蚂蚁内网用户建议从 @alipay/tech-ui 引入
// import { PageHeader } from '@alipay/tech-ui';
const App: React.FC = () => (
<>
<PageHeader />
<Comment />
</>
);
export default App;
```
- BackTop 组件在 `5.0.0` 中废弃，移至 FloatButton 悬浮按钮中。如需使用，可以从 FloatButton 中引入。
```diff
- import { BackTop } from 'antd';
+ import { FloatButton } from 'antd';
const App: React.FC = () => (
<>
- <BackTop />
+ <FloatButton.BackTop />
</>
);
export default App;
```
## 开始升级
通过 git 保存你的代码，然后按照上述文档进行依赖安装：
```bash
npm install --save antd@5.x
```
如果你需要使用 v4 废弃组件如 `Comment`、`PageHeader`，请安装 `@ant-design/compatible` 与 `@ant-design/pro-components` 做兼容：
```bash
npm install --save @ant-design/compatible@v5-compatible-v4
npm install --save @ant-design/pro-components
```
你可以手动对照上面的列表逐条检查代码进行修改，另外，我们也提供了一个 codemod cli 工具 [@ant-design/codemod-v5](https://github.com/ant-design/codemod-v5) 以帮助你快速升级到 v5 版本。
在运行 codemod cli 前，请先提交你的本地代码修改。
```shell
# 使用 npx 直接运行
npx -p @ant-design/codemod-v5 antd5-codemod src
# 或者使用 pnpm 直接运行
pnpm --package=@ant-design/codemod-v5 dlx antd5-codemod src
```
<video autoplay="" loop="" style="width: 100%; max-height: 600px; object-fit: contain;">
<source src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/file/A*Sjy5ToW6ow0AAAAAAAAAAAAADrJ8AQ" type="video/webm">
<source src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/file/A*hTDYQJ2HFTYAAAAAAAAAAAAADrJ8AQ" type="video/mp4">
</video>
> 注意 codemod 不能涵盖所有场景，建议还是要按不兼容的变化逐条排查。
### less 迁移
如果你使用到了 antd 的 less 变量，通过兼容包将 v5 变量转译成 v4 版本，并通过 less-loader 注入：
```js
const { theme } = require('antd/lib');
const { convertLegacyToken, defaultTheme } = require('@ant-design/compatible/lib');
const { defaultAlgorithm, defaultSeed } = theme;
const mapV5Token = defaultAlgorithm(defaultSeed);
const v5Vars = convertLegacyToken(mapV5Token);
const mapV4Token = theme.getDesignToken(defaultTheme);
const v4Vars = convertLegacyToken(mapV4Token);
// Webpack Config
module.exports = {
// ... other config
loader: 'less-loader',
options: {
lessOptions: {
modifyVars: v5Vars, // or v4Vars
},
},
};
```
同时移除对 antd less 文件的直接引用：
```diff
// Your less file
-- @import (reference) '~antd/es/style/themes/index';
or
-- @import '~antd/es/style/some-other-less-file-ref';
```
### 移除 babel-plugin-import
从 package.json 中移除 `babel-plugin-import`，并从 `.babelrc` 移除该插件：
```diff
"plugins": [
- ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
]
```
Umi 用户可以在配置文件中关闭：
```diff
// config/config.ts or .umirc
export default {
antd: {
- import: true,
+ import: false,
},
};
```
### 替换 Day.js 语言包
将 moment.js 的 locale 替换为 day.js 的 locale 引入：
```diff
- import moment from 'moment';
+ import dayjs from 'dayjs';
- import 'moment/locale/zh-cn';
+ import 'dayjs/locale/zh-cn';
- moment.locale('zh-cn');
+ dayjs.locale('zh-cn');
```
🚨 需要注意 day.js 通过插件系统拓展功能。如果你发现原本 moment.js 的功能在 day.js 中无法使用，请查阅 [day.js 官方文档](https://day.js.org/docs/en/plugin/plugin)。
如果你暂时不想替换 day.js，也可以使用 `@ant-design/moment-webpack-plugin` 插件将 day.js 替换回 moment.js：
```bash
npm install --save-dev @ant-design/moment-webpack-plugin
```
```javascript
// webpack-config.js
import AntdMomentWebpackPlugin from '@ant-design/moment-webpack-plugin';
module.exports = {
// ...
plugins: [new AntdMomentWebpackPlugin()],
};
```
### 使用 V4 主题包
如果你不希望样式在升级后发生变化，我们在兼容包中提供了完整的 V4 主题，可以还原到 V4 的样式。
```sandpack
const sandpackConfig = {
dependencies: {
'@ant-design/compatible': 'v5-compatible-v4',
},
};
import {
defaultTheme, // 默认主题
darkTheme, // 暗色主题
} from '@ant-design/compatible';
import { ConfigProvider, Button, Radio, Space } from 'antd';
export default () => (
<ConfigProvider theme={defaultTheme}>
<Space direction="vertical">
<Button type="primary">Button</Button>
<Radio.Group>
<Radio value={1}>A</Radio>
<Radio value={2}>B</Radio>
<Radio value={3}>C</Radio>
<Radio value={4}>D</Radio>
</Radio.Group>
</Space>
</ConfigProvider>
);
```
### 旧版浏览器兼容
Ant Design v5 使用 `:where` css selector 降低 CSS-in-JS hash 值优先级，如果你需要支持旧版本浏览器（如 IE 11、360 浏览器 等等）。可以通过 `@ant-design/cssinjs` 的 `StyleProvider` 去除降权操作。详情请参阅 [兼容性调整](/docs/react/customize-theme-cn#兼容性调整)。
## 多版本共存
一般情况下，并不推荐多版本共存，它会让应用变得复杂（例如样式覆盖、ConfigProvider 不复用等问题）。我们更推荐使用微应用如 [qiankun](https://qiankun.umijs.org/) 等框架进行分页研发。
### 通过别名安装 v5
```bash
$ npm install --save antd-v5@npm:antd@5
# or
$ yarn add antd-v5@npm:antd@5
# or
$ pnpm add antd-v5@npm:antd@5
```
对应的 package.json 为：
```json
{
"antd": "4.x",
"antd-v5": "npm:antd@5"
}
```
现在，你项目中的 antd 还是 v4 版本，antd-v5 是 v5 版本。
```tsx
import React from 'react';
import { Button as Button4 } from 'antd'; // v4
import { Button as Button5 } from 'antd-v5'; // v5
export default () => (
<>
<Button4 />
<Button5 />
</>
);
```
接着配置 ConfigProvider 将 v5 `prefixCls` 改写，防止样式冲突：
```tsx
import React from 'react';
import { ConfigProvider as ConfigProvider5 } from 'antd-v5';
export default () => (
<ConfigProvider5 prefixCls="ant5">
<MyApp />
</ConfigProvider5>
);
```
需要注意的是，npm 别名并不是所有的包管理器都有很好的支持。
## 遇到问题
如果您在升级过程中遇到了问题，请到 [GitHub issues](https://new-issue.ant.design/) 进行反馈。我们会尽快响应和相应改进这篇文档。

130
docs/react/migration-v6.en-US.md Normal file
View File

@@ -0,0 +1,130 @@
---
group:
title: Migration
order: 2
order: 0
title: From v5 to v6
---
This document will help you upgrade antd from version `5.x` to `6.x`. This release is primarily a technical upgrade, most component APIs remain compatible, you will need to ensure your environment meets the new requirements before upgrading.
## Before you upgrade
1. First upgrade to the latest v5 release and address any deprecation warnings shown in the console.
2. Make sure your project runs on React 18 or above — v6 no longer supports React 17 or earlier.
3. v6 only supports modern browsers and uses CSS variables by default, so IE is not supported.
Install:
```bash
npm install --save antd@6
# or
yarn add antd@6
# or
pnpm add antd@6
```
## What incompatible changes are in v6
### React version support
- `antd@6` requires React >= 18 and no longer supports React 17 or earlier.
- You no longer need the `@ant-design/v5-patch-for-react-19` package to support React 19; you can remove it if present.
```diff
- import '@ant-design/v5-patch-for-react-19';
```
### DOM adjustments
- v6 upgrades and optimizes the DOM structure of many components to improve maintainability and consistency.
- For most projects that rely on standard antd styling this should have no effect.
- ⚠️ If your project contains custom styles that target internal DOM nodes of components (for example, relying on specific selectors or hierarchy), you may need to inspect and adjust those styles after upgrading.
### Overlay components (Modal, Drawer, etc.)
- v6 introduces the `mask` overlay option and supports a blur effect.
- The blur is enabled by default. To disable blur:
```tsx
import { ConfigProvider, Drawer, Modal } from 'antd';
export default () => (
<ConfigProvider
modal={{
mask: {
blur: false,
},
}}
drawer={{
mask: {
blur: false,
},
}}
>
<Modal />
<Drawer />
</ConfigProvider>
);
```
### Tag margin adjustment
v6 removes the trailing default margin from the `Tag` component (previously a horizontal list of Tags left an extra `margin-inline-end` on the last one). If your layout or custom styles relied on that implicit spacing, reintroduce it via `ConfigProvider` `tag.styles`:
```tsx
import { ConfigProvider, Tag } from 'antd';
export default () => (
<ConfigProvider
tag={{
styles: {
root: {
marginInlineEnd: 8,
},
},
}}
>
<Tag>Tag A</Tag>
<Tag>Tag B</Tag>
<Tag>Tag C</Tag>
</ConfigProvider>
);
```
If you only need the old spacing in specific areas, prefer local container overrides instead of global configuration to avoid unintended impact elsewhere.
### Form `onFinish` no longer includes all data from Form.List
In v5, Form.List was treated as a single Field, causing `onFinish` to include all data within the Form.List structure, even for items without a registered Form.Item. In v6, Form.List no longer includes data from unregistered child items. Therefore, you no longer need to use `getFieldsValue({ strict: true })` to filter out unregistered fields.
```diff
const onFinish = (values) => {
-- const realValues = getFieldsValue({ strict: true });
++ const realValues = values;
// ...
}
<Form onFinish={onFinish} />
```
### Browser support changes
- CSS variables are enabled by default and only modern browsers are supported.
- IE is no longer supported. Some older domestic browsers may have compatibility issues — please verify target browsers before shipping your app.
## Upgrade checklist
To ensure your app works correctly after upgrading to v6, please go through the following checklist:
- React version: confirm your app uses React >= 18 and has removed `@ant-design/v5-patch-for-react-19`.
- Browser compatibility: confirm your target user browsers are modern and support CSS variables.
- Custom styles: if you have CSS that targets component internal DOM nodes, verify they still work under v6 and adjust if necessary.
- Overlay mask configuration: decide whether Modal, Drawer, etc. need the mask blur disabled; leave defaults if not needed.
- Build configuration: ensure your build completes without errors and CSS variables / CSS-in-JS work correctly.
- Console warnings: run the app and resolve any legacy API warnings shown in the console.
## Need help?
If you run into problems while upgrading, please open an issue at https://new-issue.ant.design/. We'll respond as soon as possible and improve the documentation.

126
docs/react/migration-v6.zh-CN.md Normal file
View File

@@ -0,0 +1,126 @@
---
group:
title: 迁移
order: 2
order: 0
title: 从 v5 到 v6
---
本文档将帮助你从 antd `5.x` 版本升级到 antd `6.x` 版本。本次升级为一次技术升级，虽然组件 API 保持兼容，但在升级前您需要确保您的环境满足新的要求。
## 升级准备
1. 请先升级到 **v5 最新版本**，按照控制台 warning 信息处理已废弃 API。
2. 确认项目可以运行在 **React 18 及以上**版本，v6 不再支持 React 17 及以下。
3. v6 仅支持现代浏览器，并默认使用 **CSS variables**，因此不再支持 IE。
```bash
npm install --save antd@6
# 或
yarn add antd@6
# 或
pnpm add antd@6
```
## v6 有哪些不兼容的变化
### React 版本支持调整
- `antd@6` 要求 React 版本 >= 18，不再支持 React 17 及以下。
- 不再需要 `@ant-design/v5-patch-for-react-19` 来兼容 React 19，如果使用可以移除该依赖。
```diff
- import '@ant-design/v5-patch-for-react-19';
```
### DOM 调整
- v6 对大量组件的 DOM 结构进行了升级和优化，以提升可维护性和一致性。
- 对于大多数正常使用 antd 样式的项目，这不会产生影响。
- ⚠️ 如果你的项目中存在针对组件内部 DOM 节点的自定义样式（例如依赖特定选择器或层级结构），升级后可能需要手动检查并调整样式。
### 弹层类组件（Modal、Drawer 等）
- 新增 `mask` 蒙层功能，并支持模糊效果。
- 默认开启，可通过以下方式关闭模糊：
```tsx
import { ConfigProvider, Drawer, Modal } from 'antd';
export default () => (
<ConfigProvider
modal={{
mask: {
blur: false,
},
}}
drawer={{
mask: {
blur: false,
},
}}
>
<Modal />
<Drawer />
</ConfigProvider>
);
```
### Tag margin 调整
v6 移除了 `Tag` 组件末尾的默认外边距（以前 Tag 末尾会额外留出一段 `margin-inline-end`）。如果你的布局或自定义样式依赖这一行为，请使用 `ConfigProvider` 的 `tag.styles` 进行补充：
```tsx
import { ConfigProvider, Tag } from 'antd';
export default () => (
<ConfigProvider
tag={{
styles: {
root: {
marginInlineEnd: 8,
},
},
}}
>
<Tag>Tag A</Tag>
<Tag>Tag B</Tag>
<Tag>Tag C</Tag>
</ConfigProvider>
);
```
### Form `onFinish` 取值不再包含 Form.List 全部数据
v5 版本中，Form.List 会被认为是一个 Field，以至于提交时会包含 Form.List 下的所有数据结构即便其子元素的 Form.Item 没有注册过。在 v6 中，Form.List 不再包含未注册的子项数据。因而你不再需要通过 `getFieldsValue({ strict: true })` 来过滤未注册字段。
```diff
const onFinish = (values) => {
-- const realValues = getFieldsValue({ strict: true });
++ const realValues = values;
// ...
}
<Form onFinish={onFinish} />
```
### 浏览器支持调整
- 默认开启 **CSS variables**，仅支持现代浏览器。
- IE 浏览器不再支持，部分旧版国产浏览器可能存在兼容性问题，请在应用发布前确认目标浏览器的支持情况。
## 升级影响排查 Checklist
为了确保升级到 v6 后项目正常运行，请参考以下检查清单逐项确认：
- **React 版本**：确认项目使用的 React 版本 >= 18，并且不再引入 `@ant-design/v5-patch-for-react-19`。
- **浏览器兼容性**：确认目标用户浏览器均为现代浏览器，且支持 CSS variables。
- **自定义样式检查**：如果有针对组件内部 DOM 节点的 CSS 定制，验证在 v6 下是否依然生效。
- **弹层蒙层配置**：Modal、Drawer 等弹层是否需要关闭 `mask` 的模糊效果，如不需要可保持默认。
- **构建工具配置**：确认升级后构建无报错，CSS 变量和 CSS-in-JS 能正常工作。
- **控制台 warning**：运行应用并观察控制台，处理所有 `legacy API` 的提示。
## 遇到问题
如果您在升级过程中遇到问题，请到 [GitHub issues](https://new-issue.ant.design/) 进行反馈。我们会尽快响应并在文档中完善相关说明。