slowly

0%

Ant Design 2.x 升级至 3.x 纪要

发表于 更新于 Changyan：

antd 做为最火热的前端 UI 组件库之一，早在 2017年12月 就已发布 3.0 版本，在此之前产品目前使用的版本还是 2.x 版本, 并且 2.x 版本官方在18年6月份就没有维护啦，可见升级迫在眉睫。幸运的是，趁此次产品 UI 改造之际，正好借此机会将 antd 升级至 3.x 最新版本。

现在开始

升级之前建议读者可以先阅读下antd changlog 日志。
话不多说，直接将 antd 升级至目前 3.x 最高版本（3.26.13）。升级之后，由于人肉查找代码中的废弃用法过于低效，antd 官方提供了 antd-migration-helper 用于扫描代码中的废弃用法。扫描的截图如下：

一看这截图是不是很开心（ps: 这检测工具好像没啥用啊），升级之后貌似很完美，npm run dev 项目正常启动，但事实上真如此吗？

升级报错修复

一些常见报错问题我们按照升级日志修复即可，笔者这边为了更加清晰、直观地呈现，采用报错截图+解决方式的书写形式。

默认语言设置


语言由之前的默认中文设置为默认英文（ps: 可能为了吸引更多的国外开发者）。
通过新增的 ConfigProvider 组件在应用外围包裹一次设置为中文即可全局生效。

Form 提示 warning

升级之后，mapPropsToFields 返回的字段都需要由 createFormField 方法创建的。

1
2
3
4
5
mapPropsToFields() {
    return {
				name: Form.createFormField({ value: 'zhangsan' }),
   	}
 };

Tree 组件自定义图标消失

2.x 版本自定义图标我们通过给 .ant-tree-icon__close 类增加背景图实现，升级之后 span.ant-tree-iconEle:empty 会导致空元素display: none，所以导致自定义图标消失。

解决方案：

  1. 在已有基础上，通过给空元素设置 display: inline-block 解决。
  2. 3.x 版本 Tree 组件通过 icon 设置自定义图标。

Tree 组件展开报错导致页面空白

这类报错你会发现 chrome 等搜索引擎中没有相关资料，咱们回到 Tree 组件本身，对比两个 antd 版本的 expandedKeys API 的接受数据类型，都只接受 string[]， 阅读项目代码之后发现，项目中 expandedKeys 默认值是字符串导致的。可见 3.x 对 api 数据类型要求更为严格。

CheckBox、Switch 组件等 waring

升级之后对于使用了 CheckBox、Switch 组件的页面，我们也许会看到诸如之类的 warning 信息。

其实这类 warning 是由于之前组件写法不规范导致的，只是 3.x 将这些不规范写法通通抛出来了。
解决方案：当我们使用 Form getFieldDecorator 包裹这些组件时需要使用 valuePropName 指定 Form 接管的属性值；并且通过 initialValue 设置表单域默认值。

不规范写法：

1
2
3
4
5
6
7
8
9
<FormItem
>
  {getFieldDecorator('enableHadoop', {
    rules: [],
  	initialValue: true
  })(
  	<Checkbox defaultChecked={true}>Hadoop</Checkbox>
  )}
</FormItem>

规范写法：

1
2
3
4
5
6
7
8
9
10
<FormItem
>
  {getFieldDecorator('enableHadoop', {
    rules: [],
    valuePropName: 'checked',
    initialValue: true
  })(
  	<Checkbox>Hadoop</Checkbox>
  )}
</FormItem>

Input.TextArea、Card 组件 api 替换

Warning 简易明了，3.x Input.TextArea 使用 autoSize 驼峰式替代之前 autosize;
Card 使用 hoverable (默认值 false) 替代 noHovering

动态改变 Input prefix/suffix 时，Input 会失去焦点

1
2
- const suffix = searchValue ? <Icon type="close-circle" onClick={this.emptySearchValue} /> : null;
+ const suffix = searchValue ? <Icon type="close-circle" onClick={this.emptySearchValue} /> :  <span />;

当 Input 动态添加或者删除 prefix/suffix 时，React 会重新创建 DOM 结构而新的 input 是没有焦点的。可以预设一个空的 来保持 DOM 结构不变即可解决。

Icon 组件失效

之前通过引用 Icon 组件 DOM 元素写法可能会导致图标无法显示。

1
2
`<i class="anticon anticon-database"></i>`
`<i class="anticon anticon-check-circle"></i>`;

不同版本 Icon 组件 DOM 元素如下：
2.x

3.x

对比之后发现 2. x 通过 :: before 伪元素实现，3.x 内嵌 svg 图标实现，所以我们需要重新定义 DOM 结构或者直接引用 Icon 组件。

页面样式错乱

由于一些组件的 DOM 结构有所变更，使项目中一些元素的 height 属性无法继承，从而导致页面错乱。
这类问题需要自己根据不同情况编写 css 解决。

Api 汇总：

组件名称 API
Table ellipsis、onRow
Icon component、theme、twoToneColor
DatePicker mode、onPanelChange
Select dropdownRender
Spin indicator
Switch loading
新增 List 组件

讲在最后

以上这些问题，仅仅是笔者的项目中遇到的，更多的升级问题修复还请参考升级文档。
在升级完成之后，其实会感觉 antd 对其 api 的类型约束会比之前更为严格，由之前的 warning 到现在的 error，由此可见，类型定义尤为重要。另外，3.x 修复了许多 2.x 存在的已知 bug，所以建议能升级的尽早升级吧～～

-------------本文结束, 感谢您的阅读-------------