Ant Design 4.0 發佈，來看看如何升級？
- 2020 年 3 月 2 日
- 筆記
Ant Design 4.0 正式版於 2 月 28 日提前發佈，本文將幫助你從 antd 3.x 版本升級到 antd 4.x 版本。
升級準備
- 請先升級到 3.x 的最新版本，按照控制台 warning 信息移除/修改相關的 API。
- 升級項目 React 16.12.0 以上。
- 如果你仍在使用 React 15，請參考React 16 升級文檔
- 其餘 React 16 廢棄生命周期 API 請參考 遷移導引
4.0 有哪些不兼容的變化
設計規範調整
- 行高從
1.5(21px) 調整為1.5715(22px)。 - 基礎圓角調整，由
4px改為2px。 - Selected 顏色和 Hovered 顏色進行了交換。
- 全局陰影優化，調整為三層陰影區分控件層次關係。
- 氣泡確認框中圖標的使用改變，由問號改為感嘆號。
- 部分組件選中顏色統一改為
@blue-1: #E6F7FF，對應hover顏色改為@gray-2: #FAFAFA。 - 報錯色色值調整，由
@red-5: #F5222D改為@red-5: #FF4D4F。 - 分割線顏色明度降低，由
#E8E8E8改為#F0F0F0。 - DatePicker 交互重做，面板和輸入框分離，範圍選擇現可單獨選擇開始和結束時間。
- Table 默認背景顏色從透明修改為白色。
- Tabs 火柴棍樣式縮短為和文字等長。
兼容性調整
- 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替代。
圖標升級
在 [email protected] 中，我們引入了 svg 圖標（為何使用 svg 圖標？）。使用了字符串命名的圖標 API 無法做到按需加載，因而全量引入了 svg 圖標文件，這大大增加了打包產物的尺寸。在 4.0 中，我們調整了圖標的使用 API 從而支持 tree shaking，減少 antd 默認包體積約 150 KB(Gzipped)。
舊版 Icon 使用方式將被廢棄：
import { Icon, Button } from 'antd'; const Demo = () => ( <div> <Icon type="smile" /> <Button icon="smile" /> </div> );
4.0 中會採用按需引入的方式：
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';
你將仍然可以通過兼容包繼續使用：
import { Button } from 'antd'; import { Icon } from '@ant-design/compatible'; const Demo = () => ( <div> <Icon type="smile" /> <Button icon="smile" /> </div> );
組件重構
- Form 重寫
- 不再需要
Form.create。 - 嵌套字段支持從
'xxx.yyy'改成['xxx', 'yyy']。 - DatePicker 重寫
- 提供
picker屬性用於選擇器切換。 - 範圍選擇現在可以單獨選擇開始和結束時間。
onPanelChange在面板值變化時也會觸發。- 自定義單元格樣式的類名從
ant-calendar-date改為ant-picker-cell-inner。
- 不再需要
- Tree、Select、TreeSelect、AutoComplete 重新寫
- 使用虛擬滾動。
onBlur時不再修改選中值。dropdownMatchSelectWidth不再自動適應內容寬度，請用數字設置下拉寬度。- AutoComplete 不再支持
optionLabelProp，請直接設置 Optionvalue屬性。
- Grid 組件使用 flex 布局。
- Button 的
danger現在作為一個屬性而不是按鈕類型。 - Input、Select 的
value為undefined時改為非受控狀態。 - Table 重寫
- 在沒有
columns時仍然會保留一列。 - 嵌套
dataIndex支持從'xxx.yyy'改成['xxx', 'yyy']。
- 在沒有
<Table columns={[ { title: 'Age', - dataIndex: 'user.age', + dataIndex: ['user', 'age'], }, ]} />
開始升級
你可以手動對照上面的列表逐條檢查代碼進行修改，另外，我們也提供了一個 codemod cli 工具 @ant-design/codemod-v4 以幫助你快速升級到 v4 版本。
在運行 codemod cli 前，請先提交你的本地代碼修改。
# 通過 npx 直接運行 npx -p @ant-design/codemod-v4 antd4-codemod src # 或者全局安裝 # 使用 npm npm i -g @ant-design/codemod-v4 # 或者使用 yarn yarn global add @ant-design/codemod-v4 # 運行 antd4-codemod src
對於無法自動修改的部分，codemod 會在命令行進行提示，建議按提示手動修改。修改後可以反覆運行上述命令進行檢查。
注意 codemod 不能涵蓋所有場景，建議還是要按不兼容的變化逐條排查。
遷移工具修改詳情
@ant-design/codemod-v4 會幫你遷移到 antd v4, 廢棄的組件則通過 @ant-design/compatible 保持運行, 一般來說你無需手動遷移。下方內容詳細介紹了整體的遷移和變化，你也可以參照變動手動修改。
將已廢棄的 Form 和 Mention 組件通過 @ant-design/compatible 包引入
- import { Form, Input, Button, Mention } from 'antd'; + import { Form, Mention } from '@ant-design/compatible'; + import '@ant-design/compatible/assets/index.css'; + import { Input, Button } from 'antd'; ReactDOM.render( ( <div> <Form> {getFieldDecorator('username')(<Input />)} <Button>Submit</Button> </Form> <Mention style={{ width: '100%' }} onChange={onChange} defaultValue={toContentState('@afc163')} defaultSuggestions={['afc163', 'benjycui']} onSelect={onSelect} /> </div> );
**注意：**從
@ant-design/compatible引入的老版本 Form 組件，樣式類名會從.ant-form變成.ant-legacy-form，如果你對其進行了樣式覆蓋，也需要相應修改。
用新的 @ant-design/icons 替換字符串類型的 icon 屬性值
import { Avatar, Button, Result } from 'antd'; + import { QuestionOutlined, UserOutlined } from '@ant-design/icons'; ReactDOM.render( <div> - <Button type="primary" shape="circle" icon="search" /> + <Button type="primary" shape="circle" icon={SearchOutlined} /> - <Avatar shape="square" icon="user" /> + <Avatar shape="square" icon={UserOutlined} /> <Result - icon="question" + icon={<QuestionOutlined />} title="Great, we have done all the operations!" extra={<Button type="primary">Next</Button>} /> </div>, mountNode, );
將 v3 Icon 組件轉換成 @ant-design/icons 中引入
- import { Icon, Input } from 'antd'; + import { Input } from 'antd'; + import Icon, { CodeFilled, SmileOutlined, SmileTwoTone } from '@ant-design/icons'; const HeartSvg = () => ( <svg width="1em" height="1em" fill="currentColor" viewBox="0 0 1024 1024"> <path d="M923 plapla..." /> </svg> ); const HeartIcon = props => <Icon component={HeartSvg} {...props} />; ReactDOM.render( <div> - <Icon type="code" theme="filled" /> + <CodeFilled /> - <Icon type="smile" theme="twoTone" twoToneColor="#eb2f96" /> + <SmileTwoTone twoToneColor="#eb2f96" /> - <Icon type="code" theme={props.fill ? 'filled' : 'outlined'} /> + <LegacyIcon type="code" theme={props.fill ? 'filled' : 'outlined'} /> <HeartIcon /> <Icon viewBox="0 0 24 24"> <title>Cool Home</title> <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z" /> </Icon> <Input suffix={<SmileOutlined />} /> </div>, mountNode, );
將 v3 LocaleProvider 組件轉換成 v4 ConfigProvider 組件
- import { LocaleProvider } from 'antd'; + import { ConfigProvider } from 'antd'; ReactDOM.render( - <LocaleProvider {...yourConfig}> + <ConfigProvider {...yourConfig}> <Main /> - </LocaleProvider> + </ConfigProvider> mountNode, );
將 Modal.method() 中字符串 icon 屬性的調用轉換成從 @ant-design/icons 中引入
import { Modal } from 'antd'; + import { AntDesignOutlined } from '@ant-design/icons'; Modal.confirm({ - icon: 'ant-design', + icon: <AntDesignOutlined />, title: 'Do you Want to delete these items?', content: 'Some descriptions', onOk() { console.log('OK'); }, onCancel() { console.log('Cancel'); }, });
遇到問題
v4 做了非常多的細節改進和重構，我們儘可能收集了已知的所有不兼容變化和相關影響，但是有可能還是有一些場景我們沒有考慮到。如果你在升級過程中遇到了問題，請到 GitHub issues 和 codemod Issues 進行反饋。我們會儘快響應和相應改進這篇文檔。
更多內容請查看官方文檔：https://ant.design/docs/react/migration-v4-cn
