From 241a2b27decfc4670f68d94ecd4bba2ead037a6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BA=8C=E8=B4=A7=E7=88=B1=E5=90=83=E7=99=BD=E8=90=9D?= =?UTF-8?q?=E5=8D=9C?= Date: Fri, 21 Nov 2025 14:36:44 +0800 Subject: [PATCH] docs: v5 -> v6 (#55783) * docs: v5 -> v6 * docs: update docs * docs: update docs --- docs/react/migration-v5.en-US.md | 378 ------------------------------- docs/react/migration-v5.zh-CN.md | 372 ------------------------------ docs/react/migration-v6.en-US.md | 130 +++++++++++ docs/react/migration-v6.zh-CN.md | 126 +++++++++++ 4 files changed, 256 insertions(+), 750 deletions(-) delete mode 100644 docs/react/migration-v5.en-US.md delete mode 100644 docs/react/migration-v5.zh-CN.md create mode 100644 docs/react/migration-v6.en-US.md create mode 100644 docs/react/migration-v6.zh-CN.md diff --git a/docs/react/migration-v5.en-US.md b/docs/react/migration-v5.en-US.md deleted file mode 100644 index e3a2253b9a..0000000000 --- a/docs/react/migration-v5.en-US.md +++ /dev/null @@ -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 `` 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 = () => ( - - ); - - 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 ( - <> - - content - + content - - - tag - + {visible && tag} - - - - - - + - - ); - } - - 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 = () => ( - <> - - - - ); - - export default App; - ``` - -- BackTop 组件在 `5.0.0` 中废弃，移至 FloatButton 悬浮按钮中。如需使用，可以从 FloatButton 中引入。 - - ```diff - - import { BackTop } from 'antd'; - + import { FloatButton } from 'antd'; - - const App: React.FC = () => ( - <> - - - + - - ); - - 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 -``` - - - -> 注意 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 () => ( - - - - - A - B - C - D - - - -); -``` - -### 旧版浏览器兼容 - -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 () => ( - <> - - - -); -``` - -接着配置 ConfigProvider 将 v5 `prefixCls` 改写，防止样式冲突： - -```tsx -import React from 'react'; -import { ConfigProvider as ConfigProvider5 } from 'antd-v5'; - -export default () => ( - - - -); -``` - -需要注意的是，npm 别名并不是所有的包管理器都有很好的支持。 - -## 遇到问题 - -如果您在升级过程中遇到了问题，请到 [GitHub issues](https://new-issue.ant.design/) 进行反馈。我们会尽快响应和相应改进这篇文档。 diff --git a/docs/react/migration-v6.en-US.md b/docs/react/migration-v6.en-US.md new file mode 100644 index 0000000000..bd62343ee5 --- /dev/null +++ b/docs/react/migration-v6.en-US.md @@ -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 () => ( + + + + +); +``` + +### 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 () => ( + + Tag A + Tag B + Tag C + +); +``` + +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; + + // ... + } + +
+``` + +### 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. diff --git a/docs/react/migration-v6.zh-CN.md b/docs/react/migration-v6.zh-CN.md new file mode 100644 index 0000000000..79ddbe408f --- /dev/null +++ b/docs/react/migration-v6.zh-CN.md @@ -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 () => ( + + + + +); +``` + +### Tag margin 调整 + +v6 移除了 `Tag` 组件末尾的默认外边距（以前 Tag 末尾会额外留出一段 `margin-inline-end`）。如果你的布局或自定义样式依赖这一行为，请使用 `ConfigProvider` 的 `tag.styles` 进行补充： + +```tsx +import { ConfigProvider, Tag } from 'antd'; + +export default () => ( + + Tag A + Tag B + Tag C + +); +``` + +### 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; + + // ... + } + + +``` + +### 浏览器支持调整 + +- 默认开启 **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/) 进行反馈。我们会尽快响应并在文档中完善相关说明。