ant-design/docs/react/migration-v5.zh-CN.md

group	order	title	tag
title order 迁移 2	0	从 v4 到 v5	Updated

本文档将帮助你从 antd 4.x 版本升级到 antd 5.x 版本，如果你是 3.x 或者更老的版本，请先参考之前的升级文档升级到 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 作为解决方案。
  • 所有 less 文件全部移除，less 变量不再支持透出。
  • 产物中不再包含 css 文件。由于 CSS-in-JS 支持按需引入，原本的 antd/dist/antd.css 也已经移除，如果需要重置一些基本样式请引入 antd/dist/reset.css。
  • 如果需要组件重置样式，又不想引入 antd/dist/reset.css 从而导致污染全局样式的话，可以尝试在应用最外层使用App 组件，解决原生元素没有 antd 规范样式的问题。
• 移除 css variables 以及在此之上构筑的动态主题方案。
• LocaleProvider 在 4.x 中已经废弃（使用 <ConfigProvider locale /> 替代），我们在 5.x 里彻底移除了相关目录 antd/es/locale-provider、antd/lib/locale-provider。
• 内置的时间库使用 Dayjs 替代 Moment.js，具体请查看 使用自定义日期库。
• 不再支持 babel-plugin-import，CSS-in-JS 本身具有按需加载的能力，不再需要插件支持。

兼容性调整

• 不再支持 IE 浏览器。

组件 API 调整

• 组件弹框的 classname API 统一为 popupClassName，dropdownClassName 等类似 API 都会被替换。

  • AutoComplete 组件
  • Cascader 组件
  • Select 组件
  • TreeSelect 组件
  • TimePicker 组件
  • DatePicker 组件
  • Mentions 组件

    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。

    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

• 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 中维护。

  - 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 中引入。

  - import { BackTop } from 'antd';
  + import { FloatButton } from 'antd';
  
    const App: React.FC = () => (
      <>
  -     <BackTop />
  +     <FloatButton.BackTop />
      </>
    );
  
    export default App;
  

开始升级

通过 git 保存你的代码，然后按照上述文档进行依赖安装：

npm install --save antd@5.x

如果你需要使用 v4 废弃组件如 Comment、PageHeader，请安装 @ant-design/compatible 与 @ant-design/pro-components 做兼容：

npm install --save @ant-design/compatible@v5-compatible-v4
npm install --save @ant-design/pro-components

你可以手动对照上面的列表逐条检查代码进行修改，另外，我们也提供了一个 codemod cli 工具 @ant-design/codemod-v5 以帮助你快速升级到 v5 版本。

在运行 codemod cli 前，请先提交你的本地代码修改。

# 使用 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 注入：

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 文件的直接引用：

// 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 移除该插件：

"plugins": [
- ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],
]

Umi 用户可以在配置文件中关闭：

// config/config.ts or .umirc
export default {
  antd: {
-   import: true,
+   import: false,
  },
};

替换 Day.js 语言包

将 moment.js 的 locale 替换为 day.js 的 locale 引入：

-   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 官方文档。

如果你暂时不想替换 day.js，也可以使用 @ant-design/moment-webpack-plugin 插件将 day.js 替换回 moment.js：

npm install --save-dev @ant-design/moment-webpack-plugin

// webpack-config.js
import AntdMomentWebpackPlugin from '@ant-design/moment-webpack-plugin';

module.exports = {
  // ...
  plugins: [new AntdMomentWebpackPlugin()],
};

使用 V4 主题包

如果你不希望样式在升级后发生变化，我们在兼容包中提供了完整的 V4 主题，可以还原到 V4 的样式。

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 去除降权操作。详情请参阅 兼容性调整。

多版本共存

一般情况下，并不推荐多版本共存，它会让应用变得复杂（例如样式覆盖、ConfigProvider 不复用等问题）。我们更推荐使用微应用如 qiankun 等框架进行分页研发。

通过别名安装 v5

$ 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 为：

{
  "antd": "4.x",
  "antd-v5": "npm:antd@5"
}

现在，你项目中的 antd 还是 v4 版本，antd-v5 是 v5 版本。

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 改写，防止样式冲突：

import React from 'react';
import { ConfigProvider as ConfigProvider5 } from 'antd-v5';

export default () => (
  <ConfigProvider5 prefixCls="ant5">
    <MyApp />
  </ConfigProvider5>
);

需要注意的是，npm 别名并不是所有的包管理器都有很好的支持。

遇到问题

如果您在升级过程中遇到了问题，请到 GitHub issues 进行反馈。我们会尽快响应和相应改进这篇文档。