docs: 📝 Add more detail in migration-v4 (#20558)

* 📝 more detail in migration-v4

* add link

* add v3 removed api

* components change

* update link

* add todo marker

* remove v2 doc

* docs: update icons part

* update docs for mssing content

* add color update

* docs: Add Table style breaking change

* Update migration-v4.zh-CN.md

* Update migration-v4.zh-CN.md

* Update migration-v4.zh-CN.md

* adjust data of gzipped

* update desc

* docs: Add english version

* Update docs/react/migration-v4.zh-CN.md

Co-Authored-By: 偏右 <afc163@gmail.com>

* more adjust

* clean up changelog

* use value intead of px

* Add form warning

* Add cn changelog

* update docs

* Update docs/react/migration-v4.zh-CN.md

Co-Authored-By: 偏右 <afc163@gmail.com>

* update quota

* re-order changelog

* add english version

* docs: add some images for codemod

* update version

Co-authored-by: 二货机器人 <smith3816@gmail.com>
Co-authored-by: vagusX <vagusX@users.noreply.github.com>
This commit is contained in:
偏右 2020-01-04 07:06:13 +08:00 committed by 二货机器人
parent 7c8d942034
commit 22e9ec6eec
5 changed files with 400 additions and 5234 deletions

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -3,31 +3,149 @@ order: 8
title: V3 to V4 title: V3 to V4
--- ---
We provide a codemod cli tool [@ant-design/codemod-v4](https://github.com/ant-design/codemod-v4) to help you quickly upgrade to antd v4. This document will help you upgrade from antd `3.x` version to antd `4.x` version. If you are using `2.x` or older version, please refer to the previous [upgrade document] (https: / /github.com/ant-design/ant-design/blob/2adf8ced24da7b3cb46a3475854a83d76a98c536/CHANGELOG.zh-CN.md#300) to 3.x.
## Usage ## Upgrade preparation
Before running the codemod cli, please submit your local code changes. 1. Please upgrade to the latest version of 3.x first, and remove / modify related APIs according to the console warning message.
2. Upgrade project React 16.12.0 or above.
- If you are still using React 15, please refer to [React 16 Upgrade Documentation](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes).
- For the remaining React 16 obsolete lifecycle APIs, please refer to [Migration Guide](https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path).
## Incompatible changes in v4
### Design specification
- Line height changes from `1.5`(`21px`) to `1.5715`(`22px`).
- Basic rounded corner adjustment, changed from `4px` to `2px`.
- Global shadow optimization, adjusted to three layers of shadows to distinguish control hierarchies.
- Icon in the bubble confirmation box has been changed from a question mark to an exclamation mark.
- The color of selected components is changed to `@blue-1: #E6F7FF`, and the corresponding hover color is changed to `@gray-2: #FAFAFA`.
- The color of the error was adjusted from `@red-5: #F5222D` to`@red-5: #FF4D4F`.
- The color brightness of the dividing line has been reduced from `#E8E8E8` to`#F0F0F0`.
- DatePicker interactive redo, range selection can now select start and end time separately.
- Table change default background color from transparent to white.
### Compatibility
- The minimum supported version of IE is IE 11.
- The minimum supported version of React is React 16.9, and some components have started to refactor using hooks.
#### Remove deprecated API
- LocaleProvider has been removed, please use `ConfigProvider` instead.
- Mention removed, use `Mentions` instead.
- Removed the `iconType` property of Alert. Please use `icon` instead.
- Removed the `iconType` attribute of Modal.xxx. Please use `icon` instead.
- Removed the Form.create method, `form` is now available in `Form.useForm`.
- Removed the `id` attribute of Form.Item. Please use `htmlFor` instead.
- The `setContentRef` property of Typography has been removed, please use `ref` instead.
- Removed the `allowEmpty` property of TimePicker, please use `allowClear` instead.
- Removed `AfterClose` attribute of Tag, please use `OnClose` instead.
- Removed the `noHovering` property of Card, please use `hoverable` instead.
- Removed the `vertical` property of Carousel. Please use `dotPosition` instead.
- Removed `wrapClassName` property of Drawer, please use `className` instead.
- Removed the `autosize` property of TextArea. Please use `autoSize` instead.
- Removed the `offset` attribute of Affix. Please use `offsetTop` instead.
- Removed the `onSearchChange` property of Transfer. Please use `onSearch` instead.
- Removed the `body` attribute of Transfer. Please use `children` instead.
- Removed the `lazy` attribute of Transfer, which did not really optimize the effect.
- Removed `combobox` mode, please use `AutoComplete` instead.
#### Icon upgrade
In `antd @ 3.9.0`, we introduced the svg icon ([Why use the svg icon?](Https://github.com/ant-design/ant-design/issues/10353)). The icon API using the string name cannot be loaded on demand, so the svg icon file is fully introduced, which greatly increases the size of the packaged product. In 4.0, we adjusted the icon usage API to support tree shaking, reducing the default package size of antd by about 150 KB (Gzipped).
Legacy Icon usage will be discarded:
```jsx
import { Icon, Button } from 'antd';
const Demo = () => (
<div>
<Icon type="smile" />
<Button icon="smile" />
</div>
);
```
It will be imported on demand in v4:
```diff
import { Button } from 'antd';
// tree-shaking supported
- import { Icon } from 'antd';
+ import { SmileOutlined } from '@ant-design/icons';
const Demo = () => (
<div>
- <Icon type="smile" />
+ <SmileOutlined />
<Button icon={<SmileOutlined />} />
</div>
);
// or directly import
import SmileOutlined from '@ant-design/icons/SmileOutlined';
```
You will still be able to continue using the compatibility pack:
```jsx
import { Button } from 'antd';
import { Icon } from '@ant-design/compatible';
const Demo = () => (
<div>
<Icon type="smile" />
<Button icon="smile" />
</div>
);
```
#### Component refactoring
- Form rewrite. No need to use `Form.create`. See [here](/components/form/v3) for migration documentation.
- DatePicker rewrite
- Provide the `picker` property for selector switching.
- Range selection can now select start and end times individually.
- Tree, Select, TreeSelect, AutoComplete use virtual scrolling.
- `dropdownMatchSelectWidth` no longer automatically adapts to the content width, please set the dropdown width with numbers.
- The Grid component uses flex layout.
- Button's `danger` is now treated as a property instead of a button type.
## Start upgrading
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-v4](https://github.com/ant-design/codemod-v4) To help you quickly upgrade to v4.
Before running codemod cli, please submit your local code changes.
```shell ```shell
# run directly with npx # Run directly through npx
npx -p @ant-design/codemod-v4 antd4-codemod src npx -p @ant-design/codemod-v4 antd4-codemod src
# or global installation # Or global installation
# use npm # Use npm
npm i -g @ant-design/codemod-v4 npm i -g @ant-design/codemod-v4
# or use yarn # Use yarn
yarn add -g @ant-design/codemod-v4 yarn add -g @ant-design/codemod-v4
# run # Execute
antd4-codemod src antd4-codemod src
``` ```
## TL;DR For parts that cannot be modified automatically, codemod will prompt on the command line, and it is recommended to modify them manually as prompted. After modification, you can run the above command repeatedly to check.
`@ant-design/codemod-v4` will help you migrate to antd v4, `@ant-design/compatible` is the workaround for the deprecated APIs and components, so you don't need to do it yourself in general. The blew content is the migration detail. ![contains an invalid icon](https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KQwWSrPirlUAAAAAAAAAAABkARQnAQ)
#### Replace deprecated `Form` and `Mention` from `@ant-design/compatible` > Note that codemod cannot cover all scenarios, and it is recommended to check for incompatible changes one by one.
### Migration tool modification details
`@ant-design/codemod-v4` will help you migrate to antd v4. Obsolete components will be kept running through @ant-design/compatible. Generally, you don't need to migrate manually. The following sections detail the overall migration and changes.
#### Import the obsolete Form and Mention components via @ant-design/compatible package
```diff ```diff
- import { Form, Input, Button, Mention } from 'antd'; - import { Form, Input, Button, Mention } from 'antd';
@ -52,7 +170,9 @@ antd4-codemod src
); );
``` ```
#### Replace components string icon prop with new `@ant-design/icons` > **Note:** Old Form imported from `@ ant-design / compatible` has change the class name from `.ant-form` to `.ant-legacy-form`. Need to be modified accordingly if override the style.
#### Replace component's string icon prop with the new `@ant-design/icons`
```diff ```diff
import { Avatar, Button, Result } from 'antd'; import { Avatar, Button, Result } from 'antd';
@ -76,7 +196,7 @@ antd4-codemod src
``` ```
#### Replace v3 Icon with the new `@ant-design/icons` #### Replace v3 Icon with `@ant-design/icons`
```diff ```diff
- import { Icon, Input } from 'antd'; - import { Icon, Input } from 'antd';
@ -111,7 +231,7 @@ antd4-codemod src
``` ```
#### Replace v3 LocaleProvider with v4 ConfigProvider component #### Replace v3 LocaleProvider with v4 ConfigProvider
```diff ```diff
- import { LocaleProvider } from 'antd'; - import { LocaleProvider } from 'antd';
@ -127,7 +247,7 @@ antd4-codemod src
); );
``` ```
#### Replace `Modal.method()` string icon property with the new `@ant-design/icons` #### Replace `Modal.method()` icon string with `@ant-design/icons`
```diff ```diff
import { Modal } from 'antd'; import { Modal } from 'antd';
@ -146,3 +266,7 @@ antd4-codemod src
}, },
}); });
``` ```
## Encounter problems
v4 made a lot of detailed improvements and refactoring. We collected all known incompatible changes and related impacts as much as possible, but there may be some scenarios we have not considered. If you encounter problems during the upgrade, please go to [GitHub issues](http://new-issue.ant.design/) and [codemod Issues](https://github.com/ant-design/codemod-v4/issues) for feedback. We will respond and improve this document as soon as possible.

View File

@ -3,9 +3,121 @@ order: 8
title: 从 v3 到 v4 title: 从 v3 到 v4
--- ---
我们提供了一个 codemod cli 工具 [@ant-design/codemod-v4](https://github.com/ant-design/codemod-v4) 以帮助你快速升级到 v4 版本 本文档将帮助你从 antd `3.x` 版本升级到 antd `4.x` 版本,如果你是 `2.x` 或者更老的版本,请先参考之前的[升级文档](https://github.com/ant-design/ant-design/blob/2adf8ced24da7b3cb46a3475854a83d76a98c536/CHANGELOG.zh-CN.md#300)升级到 3.x
## 使用 ## 升级准备
1. 请先升级到 3.x 的最新版本,按照控制台 warning 信息移除/修改相关的 API。
2. 升级项目 React 16.12.0 以上。
- 如果你仍在使用 React 15请参考[React 16 升级文档](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes)
- 其余 React 16 废弃生命周期 API 请参考 [迁移导引](https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)
## 4.0 有哪些不兼容的变化
### 设计规范调整
- 行高从 `1.5`(`21px`) 调整为 `1.5715`(`22px`)。
- 基础圆角调整,由`4px` 改为 `2px`
- 全局阴影优化,调整为三层阴影区分控件层次关系。
- 气泡确认框中图标的使用改变,由问号改为感叹号。
- 部分组件选中颜色统一改为 `@blue-1: #E6F7FF`,对应 `hover` 颜色改为 `@gray-2: #FAFAFA`
- 报错色色值调整,由 `@red-5: #F5222D` 改为 `@red-5: #FF4D4F`
- 分割线颜色明度降低,由 `#E8E8E8` 改为 `#F0F0F0`
- DatePicker 交互重做,面板和输入框分离,范围选择现可单独选择开始和结束时间。
- Table 默认背景颜色从透明修改为白色。
### 兼容性调整
- IE 最低支持版本为 IE 11。
- React 最低支持版本为 React 16.9,部分组件开始使用 hooks 进行重构。
#### 移除废弃的 API
- 移除了 LocaleProvider请使用 `ConfigProvider` 替代。
- 移除了 Mention请使用 `Mentions` 替代。
- 移除了 Alert 的 `iconType` 属性,请使用 `icon` 替代。
- 移除了 Modal.xxx 的 `iconType` 属性,请使用 `icon` 替代。
- 移除了 Form.create 方法,`form` 现可由 `Form.useForm` 获取。
- 移除了 Form.Item 的 `id` 属性,请使用 `htmlFor` 替代。
- 移除了 Typography 的 `setContentRef` 属性,请使用 `ref` 替代。
- 移除了 TimePicker 的 `allowEmpty` 属性,请使用 `allowClear` 替代。
- 移除了 Tag 的 `afterClose` 属性,请使用 `onClose` 替代。
- 移除了 Card 的 `noHovering` 属性,请使用 `hoverable` 替代。
- 移除了 Carousel 的 `vertical` 属性,请使用 `dotPosition` 替代。
- 移除了 Drawer 的 `wrapClassName` 属性,请使用 `className` 替代。
- 移除了 TextArea 的 `autosize` 属性,请使用 `autoSize` 替代。
- 移除了 Affix 的 `offset` 属性,请使用 `offsetTop` 替代。
- 移除了 Transfer 的 `onSearchChange` 属性,请使用 `onSearch` 替代。
- 移除了 Transfer 的 `body` 属性,请使用 `children` 替代。
- 移除了 Transfer 的 `lazy` 属性,它并没有起到真正的优化效果。
- 移除了 Select 的 `combobox` 模式,请使用 `AutoComplete` 替代。
#### 图标升级
`antd@3.9.0` 中,我们引入了 svg 图标([为何使用 svg 图标?](https://github.com/ant-design/ant-design/issues/10353))。使用了字符串命名的图标 API 无法做到按需加载,因而全量引入了 svg 图标文件,这大大增加了打包产物的尺寸。在 4.0 中,我们调整了图标的使用 API 从而支持 tree shaking减少 antd 默认包体积约 150 KB(Gzipped)。
旧版 Icon 使用方式将被废弃:
```jsx
import { Icon, Button } from 'antd';
const Demo = () => (
<div>
<Icon type="smile" />
<Button icon="smile" />
</div>
);
```
4.0 中会采用按需引入的方式:
```diff
import { Button } from 'antd';
// tree-shaking supported
- import { Icon } from 'antd';
+ import { SmileOutlined } from '@ant-design/icons';
const Demo = () => (
<div>
- <Icon type="smile" />
+ <SmileOutlined />
<Button icon={<SmileOutlined />} />
</div>
);
// or directly import
import SmileOutlined from '@ant-design/icons/SmileOutlined';
```
你将仍然可以通过兼容包继续使用:
```jsx
import { Button } from 'antd';
import { Icon } from '@ant-design/compatible';
const Demo = () => (
<div>
<Icon type="smile" />
<Button icon="smile" />
</div>
);
```
#### 组件重构
- Form 重写,不再需要 `Form.create`,迁移文档请查看[此处](/components/form/v3)。
- DatePicker 重写
- 提供 `picker` 属性用于选择器切换。
- 范围选择现在可以单独选择开始和结束时间。
- Tree、Select、TreeSelect、AutoComplete 使用虚拟滚动。
- `dropdownMatchSelectWidth` 不再自动适应内容宽度,请用数字设置下拉宽度。
- Grid 组件使用 flex 布局。
- Button 的 `danger` 现在作为一个属性而不是按钮类型。
## 开始升级
你可以手动对照上面的列表逐条检查代码进行修改,另外,我们也提供了一个 codemod cli 工具 [@ant-design/codemod-v4](https://github.com/ant-design/codemod-v4) 以帮助你快速升级到 v4 版本。
在运行 codemod cli 前,请先提交你的本地代码修改。 在运行 codemod cli 前,请先提交你的本地代码修改。
@ -23,9 +135,15 @@ yarn add -g @ant-design/codemod-v4
antd4-codemod src antd4-codemod src
``` ```
## 写在前面 对于无法自动修改的部分codemod 会在命令行进行提示,建议按提示手动修改。修改后可以反复运行上述命令进行检查。
`@ant-design/codemod-v4` 会帮你迁移到 antd v4, 废弃的 API 和组件则通过 `@ant-design/compatible` 保持运行, 一般来说你无需手动迁移。下方内容详细介绍了整体的迁移和变化。 ![contains an invalid icon](https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*KQwWSrPirlUAAAAAAAAAAABkARQnAQ)
> 注意 codemod 不能涵盖所有场景,建议还是要按不兼容的变化逐条排查。
### 迁移工具修改详情
`@ant-design/codemod-v4` 会帮你迁移到 antd v4, 废弃的组件则通过 `@ant-design/compatible` 保持运行, 一般来说你无需手动迁移。下方内容详细介绍了整体的迁移和变化,你也可以参照变动手动修改。
#### 将已废弃的 `Form``Mention` 组件通过 `@ant-design/compatible` 包引入 #### 将已废弃的 `Form``Mention` 组件通过 `@ant-design/compatible` 包引入
@ -52,7 +170,9 @@ antd4-codemod src
); );
``` ```
#### 用新的 `@ant-design/icons` 替换组件的字符串 icon prop > **注意:**从 `@ant-design/compatible` 引入的老版本 Form 组件,样式类名会从 `.ant-form` 变成 `.ant-legacy-form`,如果你对其进行了样式覆盖,也需要相应修改。
#### 用新的 `@ant-design/icons` 替换字符串类型的 `icon` 属性值
```diff ```diff
import { Avatar, Button, Result } from 'antd'; import { Avatar, Button, Result } from 'antd';
@ -146,3 +266,7 @@ antd4-codemod src
}, },
}); });
``` ```
## 遇到问题
v4 做了非常多的细节改进和重构,我们尽可能收集了已知的所有不兼容变化和相关影响,但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题,请到 [GitHub issues](http://new-issue.ant.design/) 和 [codemod Issues](https://github.com/ant-design/codemod-v4/issues) 进行反馈。我们会尽快响应和相应改进这篇文档。

View File

@ -1,6 +1,6 @@
{ {
"name": "antd", "name": "antd",
"version": "4.0.0-beta.1", "version": "4.0.0-rc.0",
"description": "An enterprise-class UI design language and React components implementation", "description": "An enterprise-class UI design language and React components implementation",
"keywords": [ "keywords": [
"ant", "ant",