mirror of
https://gitee.com/ant-design/ant-design.git
synced 2024-12-11 01:21:46 +08:00
9d4d16682e
* docs: v5 migrage * docs: v5 migration * docs: remove v5-note * docs: add design update * docs: migration v5 en * chore: replace with * docs: add diff * docs: add codemod desc * docs: add babel-plugin-import desc
6.0 KiB
6.0 KiB
order | title |
---|---|
8 | 从 v4 到 v5 |
本文档将帮助你从 antd 4.x
版本升级到 antd 5.x
版本,如果你是 3.x
或者更老的版本,请先参考之前的升级文档升级到 4.x。
升级准备
- 请先升级到 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
。
- 移除 css variables 以及在此之上构筑的动态主题方案。
- 移除
lib
产物,只提供dist
和es
产物。 - 不再支持
babel-plugin-import
,CSS-in-JS 本身具有按需加载的能力,不再需要插件支持。Umi 用户可以移除相关配置。
// config/config.ts
export default {
antd: {
- import: true,
},
};
兼容性调整
- 不再支持 IE 浏览器。
组件 API 调整
- 组件弹框的 classname API 统一为
popupClassName
,dropdownClassName
等类似 API 都会被替换。- AutoComplete 组件
- Cascader 组件
- Select 组件
- TreeSelect 组件
- TimePicker 组件
- DatePicker 组件
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
。
- Drawer 组件
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 下会反复调用该方法。- Dropdown
- 魔改包裹元素样式移除,请使用 Space 组件。
- Dropdown.Button 的
prefixCls
改为dropdown
。
- Upload List 结构变化。
- Notification
- 静态方法不在允许在
open
中动态设置prefixCls
maxCount
top
bottom
getContainer
,Notification 静态方法现在将只有一个实例。如果需要不同配置,请使用useNotification
。 close
改名为destroy
和 message 保持一致。
- 静态方法不在允许在
- Drawer
style
&className
迁移至 Drawer Panel 中,原属性替换为rootClassName
和rootStyle
。
组件重构与移除
- PageHeader 和 Comment 组件在 ant-design 中移除,移至 pro-components 中维护,如果仍需使用可以从兼容包中引入。
- import { PageHeader, Comment, Input, Button } from 'antd';
+ import { PageHeader, Comment } from '@ant-design/compatible';
+ import '@ant-design/compatible/assets/index.css';
+ import { Input, Button } from 'antd';
const App: React.FC = () => (
<div>
<PageHeader />
<Comment />
</div>
);
export default App;
开始升级
使用迁移工具修改
# 通过 npx 直接运行
npx -p @ant-design/codemod-v5 antd5-codemod <path>
# 或者全局安装
# 使用 npm
npm i -g @ant-design/codemod-v5
# 或者使用 yarn
yarn global add @ant-design/codemod-v5
# 运行
antd5-codemod src
注意 codemod 不能涵盖所有场景,建议还是要按不兼容的变化逐条排查。
同时也可以针对某项改动使用迁移工具单独执行,下面是所有迁移脚本的说明:
popup-visible-to-open
将含有弹出框的组件属性 visible
改为 open
。
antd5-codemod popup-visible-to-open <path>
popup-classname-to-popupClassName
将弹出框的 className
属性统一为 popupClassName
。
antd5-codemod popup-classname-to-popupClassName <path>
安装兼容包
安装 @ant-design/compatible
通过指定 v5-compatible-v4
tag 确认为 v5 兼容 v4 版本:
npm install --save @ant-design/compatible@v5-compatible-v4
遇到问题
如果你在升级过程中遇到了问题,请到 GitHub issues 进行反馈。我们会尽快响应和相应改进这篇文档。