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替代。圖標升級
在antd@3.9.0中，我們引入了 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# 或者全局安裝# 使用 npmnpm i -g @ant-design/codemod-v4# 或者使用 yarnyarn 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 進行反饋。我們會儘快響應和相應改進這篇文檔。