袋鼠云數(shù)棧從2016年發(fā)布第?個版本開始，就始終堅持著以技術為核?、安全為底線、提效為?標、中臺為戰(zhàn)略的思想，堅定不移地?國產化信創(chuàng)路線，不斷推進產品功能迭代、技術創(chuàng)新、服務細化和性能升級。

在數(shù)棧過去的產品迭代中受限于當前組件的版本，積累了很多待解決的問題，隨著新的功能需求不斷增加，很多原先的組件以及交互設計需要進行優(yōu)化。

2月，伴隨著數(shù)棧 UI5.0 的煥新升級，數(shù)棧前端團隊一起將組件框架?antd 從 v3.x 升級到了 v4.x，更新組件的 UI，提升產品的交互體驗，使數(shù)棧產品能夠更加靈活地適應未來產品功能迭代的需求。

本文將總結歸納袋鼠云數(shù)棧前端框架Antd 從3.x 升級到4.x 的相關步驟，及在這個過程中踩過的坑，解決的問題。

兼容性問題

第三方依賴兼容問題

· React - 最低 v16.9，部分組件使用 hooks 重構 （ react 升級相關文檔：https://sourl.cn/6bM4Ep）

· Less - 最低 v3.1.0，建議升級到 less 4.x；

· @ant-design/icons-antd - 不再內置 Icon 組件，請使用獨立的包。

對 3.x 的兼容性處理

或許是考慮到部分組件升級的毀壞性，antd4.x 中依然保留了對 3.x 版本的兼容，廢棄的組件通過 @ant-design/compatible 保持兼容，例如 Icon、Form。

注意：建議 @ant-design/compatible 僅在升級過程中稍作依賴，升級 4.x 請完全剔除對該過渡包的依賴。

升級步驟

只有一步

@ant-design/codemod-v4 自帶升級腳本，會自動替換代碼。

注意：該命令和腳本只會進行代碼替換，不會進行 AntD 的版本升級，需要手動將其升級至4.22.5。

antd4-codemod

上圖這類報錯是 Icon 組件自動替換錯誤，有 2 種處理方式：

· 報錯文件的 Icon 比較少的情況，可以直接手動替換該文件中的 Icon 組件，具體替換成 Icon 中的哪個組件可以根據 type 在 Icon 文檔中找（ Icon文檔：https://sourl.cn/neHBVS?）；

· 下圖中是具體報錯的節(jié)點，可以看到 JSXSpreadAttribute 節(jié)點也就是拓展運算符中沒有 name 屬性，所以把 Icon 組件的拓展運算符改一下再執(zhí)行替換腳本就可以了。

antd4 問題修復

styled-components

styled-components 依賴需要轉換寫法。

Icon

不要使用兼容包的 icon。 在 3.x 版本中，Icon 會全量引入所有 svg 圖標文件，增加了打包產物； 在 4.x 版本中，對 Icon 進行了按需加載，將每個 svg 封裝成一個組件。

注意：antd 不再內置 Icon 組件，請使用獨立的包 @ant-design/icons。

· 使用

· 兼容

Form

antd Form 從 v3 到 v4：https://sourl.cn/7TiRfp

● Form.create()

在 3.x 中，表單中任意一項的修改，都會導致 Form.create() 包裹的表單重新渲染，造成性能消耗； 在 4.x 中，F(xiàn)orm.create() 不再使用。 如果需要使用 form 的 api，例如 setFieldsValue 等，需要通過 Form.useForm() 創(chuàng)建 Form 實體進行操作。

· 函數(shù)組件寫法

· 如果是 class component，也可以通過 ref 獲取

當我們使用 From.create() 的時候，可能會傳入參數(shù)，做數(shù)據處理，例如：

由于 Form.create 的刪除，需要放到 < Form> 中。

● getFieldDecorator

在 4.x 中，不在需要 getFieldDecorator 對 Item 進行包裹。注意以下問題：

· 將之前寫在 getFieldDecorator 中的 name/rules 等移到屬性中；

· 初始化在 form 中處理，避免同名字段沖突問題；

· 關于表單聯(lián)動的問題，官方提供了 shouldUpdate 方法。

● initialValue

· 歷史問題

initialValue 從字面意來看，就是初始值 defaultValue，但是可能會有部分同學使用他的時候會誤以為 initialValue 等同于 value。造成這樣的誤解是因為在 3.x 的版本中，一直存在一個很神奇的問題，受控組件的值會跟隨 initialValue 改變。

看下面的例子，點擊 button 修改 username, input 框的 value 也會隨之改變。

但當 input 框被編輯過，initialValue 和 input 的綁定效果就消失了，正確的做法應該是通過 setFieldsVlaue 方法去 set 值。

· 4.x 版本的 initialValue

在 4.x，antd 團隊已經把這個 bug 給解了，并且一是為了 name 重名問題，二是再次強調其初始值的功能，現(xiàn)在提到 Form 中了。當然，如果繼續(xù)寫在 Form. Item 中也是可以的，但需要注意優(yōu)先級。

● shouldUpdate

前面有說過，form 表單不再會因為表單內部某個值的改變而重新渲染整個結構，而設有 shouldUpdate 為 true 的 Item，任意變化都會使該 Form. Item 重新渲染。

它會接收 render props，從而允許你對此進行控制。這里稍微注意一下，請勿在設置 shouldUpdate 的外層 Form. Item 上添加 name， 否則，你會得到一個 error。

在使用 shouldUpdate 的時候，需要在第一個 Form.Item 上加上 noStyle，否則就會出現(xiàn)下面這種留白占位的情況。

● validateTrigger

onBlur 時不再修改選中值，且返回 React 原生的 event 對象。如果你在使用兼容包的 Form 且配置了 validateTrigger 為 onBlur ，請改至 onChange 以做兼容。

● validator

在 antd3 時，我們使用 callback 返回報錯。但是 antd4 對此做了修改，自定義校驗，接收 Promise 作為返回值。示例參考如下：

· antd3 的寫法

· antd4 的寫法

● validateFields

不再支持 callback，該方法會直接返回一個 Promise，可以通過 then / catch 處理。

或者使用 async/await。

● validateFieldsAndScroll

該 api 被拆分了，將其拆分為更為獨立的 scrollToField 方法。

● form.name

在 antd 3.x 版本，綁定字段時，可以采用 . 分割的方式。如：

在最終獲取 values 時，antd 3.x 的版本會對字段進行匯總，得到如下：

而在 antd 4.x下，會得到如下的 values 結果：

· 解決方法

在 antd 4.x 版本傳入數(shù)組。

使用 setFieldsValue 設置值：

當我們使用 name={['sideTableParam', 'primaryKey']} 方式綁定值的時候，與其關聯(lián)的 dependencies/getFieldValue 都需要設置為['sideTableParam', 'primaryKey']，例如：

當我們希望通過 validateFields 拿到的數(shù)據是數(shù)組時，例如這樣：

我們可以設置為這樣：

● Tooltip

Form 支持屬性 tooltip，能夠在 label 后產生一個問號直接做提示。

● extra

針對于想放置于組件下面內容可以使用 extra 來實現(xiàn)。

● Form 在數(shù)棧的變化

通過這次 UI 升級和 antd 升級之后，F(xiàn)orm 表單在數(shù)棧中的應用發(fā)生了較大的變化，從老版本的 label/component 橫向排版改為了縱向改版，在橫向空間不?的情況下，使?上下結構能有效提?填寫表單的效率。

Select

● rc-select

· 底層重寫

? 解決些許歷史問題

1）rc-select & rc-select-tree 的 inputValue & searchValue 之爭。rc-select-tree 是 rc-select 結合 tree 寫的一個組件，相似但又不同，searchValue 就是其中一點，也不是沒人提過 issue，只是人的忘性很大，時間長了就忘了、混淆了，導致在 rc-select 中甚至出現(xiàn)了 searchValue 的字樣。

2）inputValue 歷史問題，this.state.inputValue。

3）onSelect 清空了值，又會被 onChange 賦值回來。

? 模塊復用

在新版的 rc-select 中，antd 官方抽取了一個 generator 方法。它主要接收一個 OptionList 的自定義組件用于渲染下拉框部分。這樣我們就可以直接復用選擇框部分的代碼，而自定義 Select 和 TreeSelect 對應的列表或者樹形結構了。

● labelInValue

在 3.x 版本為 {key: string, label: ReactNode}

在 4.x 版本為 {value: string, label: ReactNode}

Table

● fixed

固定列時，文字過長導致錯位的問題，被完美解決了。

· 歷史原因

3.x 中對 table fixed 的實現(xiàn)，是寫了兩個 table, 頂層 fixed 的是一個，底層滾動的是一個，這樣出現(xiàn)這種錯位的問題就很好理解了。

要解決也不是沒有辦法，可以在特定的節(jié)點去測算表格列的高度，但是這個行為會導致重排，影響性能問題。

· 解決方案

4.x 中，table fixed 不在通過兩個 table 來實現(xiàn)，他使用了一個 position 的新特性：position: sticky;

元素根據正常文檔流進行定位，然后相對它的最近滾動祖先（nearest scrolling ancestor）和 containing block (最近塊級祖先 nearest block-level ancestor)，包括 table-related 元素，基于 top、right、bottom 和 left 的值進行偏移，偏移值不會影響任何其他元素的位置。

優(yōu)點：

? 根據正常文檔流進行定位

? 相對最近滾動祖先 & 最近塊級祖先進行偏移

缺點：

? 不兼容 <= IE11

解決了使用 absolute | fixed 脫離文檔流無法撐開高度的問題，也不再需要對高度進行測量。

● table.checkbox

· 問題描述

升級后，checkbox 寬度被擠壓了。

· 解決方案

通過在 rowSelection 中設置 columnWidth 和 fixed 解決。

● 渲染條件

antd4 Table 對渲染條件進行了優(yōu)化，對 props 進行“淺比較”，如果沒有變化不會觸發(fā) render。

● 類名更改

.ant-table-content 更改為 .ant-table-container

.ant-form-explain 更改為 .ant-form-item-explain

● dataIndex 修改

在 antd3.0 的時候，我們采用 user.userName 能夠讀到嵌套的屬性。

antd4.0 對此做了修改，同 Form 的 name。

● table pagination showSizeChanger

· 問題描述

升級 antd4 后，發(fā)現(xiàn)一些表格分頁器多了 pageSize 切換的功能，代碼中 onChange 又未對 size 做處理，會導致底部分頁器 pageSize 和數(shù)據對不上，因此需要各自排查 Table 的 pagination 和 Pagination 組件，和請求列表接口的參數(shù)。

antd4.0 對此做了修改，同 Form 的 name。

另外，一些同學在 Table 中既寫了 onChange，也寫了 onShowSizeChange，這個時候要注意，當切換頁碼條數(shù)的時候兩個方法都會觸發(fā)，onShowSizeChange 先觸發(fā)，onChange 后觸發(fā)，這個時候如果 onChange 內未對 pageSize 做處理可能導致切頁失敗，看下面代碼就明白了，寫的時候稍微注意一下即可。

● table sorter columnKey

· 問題描述

表格中如果要對表格某一字段進行排序需要在 columns item 里設置 sorter 字段，然后在 onChange 里拿到 sorter 對象進行參數(shù)處理，再請求數(shù)據。

需要注意的是，很多用到了 sorter.columnKey 來進行判斷，容易出現(xiàn)問題，sorter.columnKey === columns item.key，如果未設置 key，那么獲取到的 columnKey 就為空，導致搜索失效，要么設置 key，再進行獲取。同理， sorter.field === columns item.dataIndex，設置 dataIndex，通過 sorter.field 進行獲取，兩者都可以。

● Table 在數(shù)棧的變化

通過這次 UI 升級和 antd 升級之后，表格在數(shù)棧中的應用發(fā)生了較大的變化，減?了表格默認?度，增加?屏可瀏覽的數(shù)據數(shù)量。

Tree

Tree 組件取消 value 屬性，現(xiàn)在只需要添加 key 屬性即可。

特別注意， 此問題會導致功能出問題，需要重點關注?。?！

在項目中經常在 TreeItem 中增加參數(shù)，如：< TreeItem value={value} data={data} >。在拖拽等回調中就可以通過 nodeData.props.data 的方式獲取到 data 的值。但在 antd4 中，獲取參數(shù)的數(shù)據結構發(fā)生了改變，原先直接通過 props 點出來的不行了。

· 有兩種方式取值：

1）不使用props。直接采用 nodeData.data 的方式，也可以直接拿到。

2）繼續(xù)使用 props。在antd4中，還是可以通過 props 找到參數(shù)，只不過 antd 會把所有參數(shù)使用 data 進行包裹，就需要改成 nodeData.props.data.data。

· 新版數(shù)據結構如下：

· drag

拖拽節(jié)點位置的確定與 3.x 相比進行了變更，官網并沒有說明。具體如下圖：

左側為 3.x，右側為 4.x。 在3.x版本，只要把節(jié)點拖拽成目標節(jié)點的上中下，即代表著目標節(jié)點的同級上方，子集，同級下方；

在 4.x 版本，是根據當前拖拽節(jié)點與目標節(jié)點的相對位置進行確定最終的拖拽結果。

當拖拽節(jié)點處于目標節(jié)點的下方，且相對左側對齊的位置趨近于零，則最終的位置為目標節(jié)點的同級下方。

當拖拽節(jié)點處于目標節(jié)點的下方，且相對左側一個縮近的位置，則最終的位置為目標節(jié)點的子集。

當拖拽節(jié)點處于目標節(jié)點的上方，且相對左側對齊的位置趨近于零，則最終的位置為目標節(jié)點的同級上方。

Pagination

Pagination自 4.1.0 版本起，會默認將 showSizeChanger 參數(shù)設置為 true ，因而在數(shù)據條數(shù)超過50時，pageSize 切換器會默認顯示。這個變化同樣適用于 Table 組件，可通過 showSizeChanger: false 關閉。

如果 size 屬性值為 small，則刪除 size 屬性。

Drawer

當我們在 Drawer 上 設置了 getContainer={false} 屬性之后，Drawer 會添加上 .ant-drawer-inline 的類名導致我們 position: fixed 失效。

Button

在 antd 3.0 中危險按鈕采用 type。

使用如下：涉及改動點 type、dangr 屬性。

Tabs

使標簽頁不被選中。

總結

該篇文章詳細講解了數(shù)棧前端團隊如何從 antd3 升級到 antd4 的詳細步驟，以及團隊在實踐過程中發(fā)現(xiàn)的一些問題和對應的解決方案，為后續(xù)產品的開發(fā)體驗打了基礎，也提供了一種更好的交互體驗。

未來數(shù)棧前端團隊將會持續(xù)關注產品體驗以及開發(fā)中的技術痛點，以開發(fā)更好的產品為導向，助力業(yè)務發(fā)展。

《數(shù)據治理行業(yè)實踐白皮書》下載地址：https://fs80.cn/380a4b

想了解或咨詢更多有關袋鼠云大數(shù)據產品、行業(yè)解決方案、客戶案例的朋友，瀏覽袋鼠云官網：https://www.dtstack.com/?src=szbzhan

同時，歡迎對大數(shù)據開源項目有興趣的同學加入「袋鼠云開源框架釘釘技術 qun」，交流最新開源技術信息，qun 號碼：30537511，項目地址：https://github.com/DTStack