详细剖析｜袋鼠云数栈前端框架Antd 3.x 升级 4.x 的踩坑之路

                                                            作者 数栈UED团队

                                                            编辑 阿晗

袋鼠云数栈从2016年发布第⼀个版本开始，就始终坚持着以技术为核⼼、安全为底线、提效为⽬标、中台为战略的思想，坚定不移地⾛国产化信创路线，不断推进产品功能迭代、技术创新、服务细化和性能升级。

在数栈过去的产品迭代中受限于当前组件的版本，积累了很多待解决的问题，随着新的功能需求不断增加，很多原先的组件以及交互设计需要进行优化。

2月，伴随着数栈 UI5.0 的焕新升级，数栈前端团队一起将组件框架 antd 从 v3.x 升级到了 v4.x，更新组件的 UI，提升产品的交互体验，使数栈产品能够更加灵活地适应未来产品功能迭代的需求。

本文将总结归纳袋鼠云数栈前端框架Antd 从3.x 升级到4.x 的相关步骤，及在这个过程中踩过的坑，解决的问题。

或许是考虑到部分组件升级的毁坏性，antd4.x 中依然保留了对 3.x 版本的兼容，废弃的组件通过 @ant-design/compatible 保持兼容，例如 Icon、Form。

注意：建议 @ant-design/compatible 仅在升级过程中稍作依赖，升级 4.x 请完全剔除对该过渡包的依赖。

@ant-design/codemod-v4 自带升级脚本，会自动替换代码。

# 通过 npx 直接运行
npx -p @ant-design/codemod-v4 antd4-codemod apps/xxxx


# 或者全局安装
# 使用 npm
npm i -g @ant-design/codemod-v4
# 或者使用 yarn
yarn global add @ant-design/codemod-v4


# 运行
antd4-codemod src

该命令完成的工作：
    1. 将 Form 与 Mention 组件通过 @ant-design/compatible 包引入 
    2. 用新的 @ant-design/icons 替换字符串类型的 icon 属性值 
    3. 将 Icon 组件 + type =“” 通过 @ant-design/icons 引入 
    4. 将 v3 LocaleProvider 组件转换成 v4 ConfigProvider 组件 
    5. 将 Modal.method() 中字符串 icon 属性的调用转换成从 @ant-design/icons 中引入

不要使用兼容包的 icon。
在 3.x 版本中，Icon 会全量引入所有 svg 图标文件，增加了打包产物；
在 4.x 版本中，对 Icon 进行了按需加载，将每个 svg 封装成一个组件。

注意：antd 不再内置 Icon 组件，请使用独立的包 @ant-design/icons。

import { Icon } from 'antd';
mport { SmileOutlined } from '@ant-design/icons';


const Demo = () => (
  <div>
     <Icon type="smile" >
     <SmileOutlined >
     <Button icon={<SmileOutlined >} >
  </div>
);

import { Icon } from '@ant-design/compatible';
const Demo = () => (
  <div>
    <Icon type="smile" >
    <Button icon="smile" >
  </div>
);

在 3.x 中，表单中任意一项的修改，都会导致 Form.create() 包裹的表单重新渲染，造成性能消耗；
在 4.x 中，Form.create() 不再使用。
如果需要使用 form 的 api，例如 setFieldsValue 等，需要通过 Form.useForm() 创建 Form 实体进行操作。

// antd v4
const Demo = () => {
  const [form] = Form.useForm();


  React.useEffect(() => {
    form.setFieldsValue({
      username: 'Bamboo',
    });
  }, []);


  return (
    <Form form={form} {...props}> ... </Form>
  )
};

class Demo extends React.Component {
  formRef = React.createRef();


  componentDidMount() {
    this.formRef.current.setFieldsValue({
      username: 'Bamboo',
    });
  }


  render() {
    return (
      <Form ref={this.formRef}>
        <Form.Item name="username" rules={[{ required: true }]}>
          <Input >
        </Form.Item>
      </Form>
    );
  }
}

当我们使用 From.create() 的时候，可能会传入参数，做数据处理，例如：

export const FilterForm: any = Form.create<Props>({
  onValuesChange: (props, changedValues, allValues) => {
    const { onChange } = props;
    onChange(allValues);
  },
})(Filter);

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

<Form
  ref={this.formRef}
  layout="vertical"
  className="meta_form"
  onValuesChange={(_, allValues) => {
    const { onChange } = this.props;
    onChange(allValues);
  }}
>

const Demo = () => (
  <Form initialValues={{ username: 'yuwan' }}>
    <Form.Item name="username" rules={[{ required: true }]}>
      <Input >
    </Form.Item>
  </Form>
);

initialValue 从字面意来看，就是初始值 defaultValue，但是可能会有部分同学使用他的时候会误以为 initialValue 等同于 value。造成这样的误解是因为在 3.x 的版本中，一直存在一个很神奇的问题，受控组件的值会跟随 initialValue 改变。

看下面的例子，点击 button 修改 username, input 框的 value 也会随之改变。

const Demo = ({ form: { getFieldDecorator } }) => (
  const [username, setUsername] = useState('');
  const handleValueChange = () => {
    setUsername('yuwan');
  }
  return (
    <Fragment>
      <Form>
        <Form.Item>
          {getFieldDecorator('username', {
             initialValue: username,
             rules: [{ required: true }],
          })(<Input >)}
        </Form.Item>
      </Form>
      <Button onClick={handleValueChange}>Change</Button>
    </Fragment>
  )
);


const WrappedDemo = Form.create()(Demo);

前面有说过，form 表单不再会因为表单内部某个值的改变而重新渲染整个结构，而设有 shouldUpdate 为 true 的 Item，任意变化都会使该 Form. Item 重新渲染。

它会接收 render props，从而允许你对此进行控制。这里稍微注意一下，请勿在设置 shouldUpdate 的外层 Form. Item 上添加 name， 否则，你会得到一个 error。

<Form.Item shouldUpdate={(prev, next) => prev.name !== next.name}>
  {form => form.getFieldValue('name') === 'antd' && (
    <Form.Item name="version">
      <Input >
    </Form.Item>
  )}
</Form.Item>

在使用 shouldUpdate 的时候，需要在第一个 Form.Item 上加上 noStyle，否则就会出现下面这种留白占位的情况。

· antd3 的写法

<FormItem label="具体时间" {...formItemLayout}>
  {getFieldDecorator('specificTime', {
    rules: [
      {
        required: true,
        validator: (_, value, callback) => {
          if (!value || !value.hour || !value.min) {
             return callback('具体时间不可为空');
          }
          callback();
        },
      },
    ],
  })(<SpecificTime >)}
</FormItem>

<FormItem
  label="具体时间"
  {...formItemLayout}
  name="specificTime"
  rules={[
    {
      required: true,
      validator: (_, value) => {
        if (!value || !value.hour || !value.min) {
            return Promise.reject('具体时间不可为空');
        }
        return Promise.resolve();
      },
    },
  ]}
>
  <SpecificTime >)
</FormItem>

不再支持 callback，该方法会直接返回一个 Promise，可以通过 then catch 处理。

this.formRef.validateFields()
  .then((values) => {
    onOk({ ...values, id: appInfo.id || '' });
})
  .catch(({ errorFields }) {
    this.formRef.scrollToField(errorFields[0].name);
  })

或者使用 async/await。

try {
  const values = await validateFields();
} catch ({ errorFields }) {
  scrollToField(errorFields[0].name);
}

该 api 被拆分了，将其拆分为更为独立的 scrollToField 方法。

onFinishFailed = ({ errorFields }) => {
  form.scrollToField(errorFields[0].name);
};

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

getFieldDecorator('sideTableParam.primaryKey')
getFieldDecorator('sideTableParam.primaryValue')
getFieldDecorator('sideTableParam.primaryName')

在最终获取 values 时，antd 3.x 的版本会对字段进行汇总，得到如下：

const values = {
  sideTableParam: {
    primaryKey: xxx,
    primaryValue: xxx,
    primaryName: xxx,
  }
}

而在 antd 4.x下，会得到如下的 values 结果：

const values = {
  'sideTableParam.primaryKey': xxx,
  'sideTableParam.primaryValue': xxx,
  'sideTableParam.primaryName': xxx,
}

在 antd 4.x 版本传入数组。

name={['sideTableParam', 'primaryKey']}
name={['sideTableParam', 'primaryValue']}
name={['sideTableParam', 'primaryName']}

使用 setFieldsValue 设置值：

setFieldsValue({
  sideTableParam: [
    {
      primaryKey: 'xxx',
      primaryValue: 'xxx',
      primaryName: 'xxx',
    },
  ],
});

当我们使用 name={['sideTableParam', 'primaryKey']} 方式绑定值的时候，与其关联的 dependencies/getFieldValue 都需要设置为['sideTableParam', 'primaryKey']，例如：

<FormItem dependencies={[['alert', 'sendTypeList']]} noStyle>
  {({ getFieldValue }) => {
    const isShowWebHook = getFieldValue(['alert', 'sendTypeList'])?.includes(
      ALARM_TYPE.DING
    );
   return (
     isShowWebHook &&
       RenderFormItem({
         item: {
           label: 'WebHook',
           key: ['alert', 'dingWebhook'],
           component: <Input placeholder="请输入WebHook地址" />,
           rules: [
             {
               required: true,
               message: 'WebHook地址为必填项',
             },
           ],
           initialValue: taskInfo?.alert?.dingWebhook || '',
         },
       })
     );
  }}
</FormItem>

当我们希望通过 validateFields 拿到的数据是数组时，例如这样：

我们可以设置为这样：

const formItems = keys.map((k: React.Key) => (
  <Form.Item key={k} required label="名称">
    <Form.Item
      noStyle
      name={['names', k]}
      rules={[
        { required: true, message: '请输入标签名称' },
        { validator: utils.validateInputText(2, 20) },
      ]}
    >
      <Input placeholder="请输入标签名称" style={{ width: '90%', marginRight: 8 }} />
    </Form.Item>
     <i className="iconfont iconicon_deletecata" onClick={() => this.removeNewTag(k)} />
  </Form.Item>
));

<FormItem
  label="过滤条件"
  extra={
    <Tooltip title={customSystemParams}>
      系统参数配置&nbsp;
       <QuestionCircleOutlined />
     </Tooltip>
   }
>
  <Input.TextArea />
</FormItem>

在新版的 rc-select 中，antd 官方抽取了一个 generator 方法。它主要接收一个 OptionList 的自定义组件用于渲染下拉框部分。这样我们就可以直接复用选择框部分的代码，而自定义 Select 和 TreeSelect 对应的列表或者树形结构了。

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

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

固定列时，文字过长导致错位的问题，被完美解决了。

3.x 中对 table fixed 的实现，是写了两个 table, 顶层 fixed 的是一个，底层滚动的是一个，这样出现这种错位的问题就很好理解了。

要解决也不是没有办法，可以在特定的节点去测算表格列的高度，但是这个行为会导致重排，影响性能问题。

4.x 中，table fixed 不在通过两个 table 来实现，他使用了一个 position 的新特性：position: sticky;

优点：

• 根据正常文档流进行定位

• 相对最近滚动祖先 & 最近块级祖先进行偏移

缺点：

• 不兼容 <= IE11

解决了使用 absolute | fixed 脱离文档流无法撑开高度的问题，也不再需要对高度进行测量。

通过在 rowSelection 中设置 columnWidth 和 fixed 解决。

const rowSelection = {
  fixed: true,
  columnWidth: 45,
  selectedRowKeys,
  onChange: this.onSelectChange,
};

antd4 Table 对渲染条件进行了优化，对 props 进行“浅比较”，如果没有变化不会触发 render。

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

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

在 antd3.0 的时候，我们采用 user.userName 能够读到嵌套的属性。

{
  title: '账号',
  dataIndex: 'user.userName',
  key: 'userName',
  width: 200,
}

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

{
  title: '账号',
  dataIndex: ['user', 'userName'],
  key: 'userName',
  width: 200,
}

<Table
  rowKey="userId"
  pagination={{
  total: users.totalCount,
    defaultPageSize: 10,
  }}
  onChange={this.handleTableChange}
  style={{ height: tableScrollHeight }}
  loading={this.state.loading}
  columns={this.initColumns()}
  dataSource={users.data}
  scroll={{ x: 1100, y: tableScrollHeight }}
/>


handleTableChange = (pagination: any) => {
  this.setState(
    {
      current: pagination.current,
    },
    this.search
  );
};


search = (projectId?: any) => {
  const { name, current } = this.state;
  const { project } = this.props;
  const params: any = {
    projectId: projectId || project.id,
    pageSize: 10,
    currentPage: current || 1,
    name: name || undefined,
    removeAdmin: true,
  };
  this.loadUsers(params);
};

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

<Table
  rowKey="userId"
  pagination={{
    showTotal: (total) => `共${total}条`,
    total: users.totalCount,
    current,
    pageSize,
  }}
  onChange={this.handleTableChange}
  style={{ height: tableScrollHeight }}
  loading={this.state.loading}
  columns={this.initColumns()}
  dataSource={users.data}
  scroll={{ x: 1100, y: tableScrollHeight }}
/>


handleTableChange = (pagination: any) => {
  this.setState(
    {
      current: pagination.current,
      pageSize: pagination.pageSize,
    },
    this.search
  );
};


search = (projectId?: any) => {
  const { name, current, pageSize } = this.state;
  const { project } = this.props;
  const params: any = {
    projectId: projectId || project.id,
    pageSize,
    currentPage: current || 1,
    name: name || undefined,
    removeAdmin: true,
  };
  this.loadUsers(params);
};

另外，一些同学在 Table 中既写了 onChange，也写了 onShowSizeChange，这个时候要注意，当切换页码条数的时候两个方法都会触发，onShowSizeChange 先触发，onChange 后触发，这个时候如果 onChange 内未对 pageSize 做处理可能导致切页失败，看下面代码就明白了，写的时候稍微注意一下即可。

表格中如果要对表格某一字段进行排序需要在 columns item 里设置 sorter 字段，然后在 onChange 里拿到 sorter 对象进行参数处理，再请求数据。

需要注意的是，很多用到了 sorter.columnKey 来进行判断，容易出现问题，sorter.columnKey === columns item.key，如果未设置 key，那么获取到的 columnKey 就为空，导致搜索失效，要么设置 key，再进行获取。同理， sorter.field === columns item.dataIndex，设置 dataIndex，通过 sorter.field 进行获取，两者都可以。

columns={
  [
    {
      title: '创建时间',
      dataIndex: 'gmtCreate1',
      key: 'aa',
      sorter: true,
      render(n: any, record: any) {
        return DateTime.formatDateTime(record.gmtCreate);
      }
    },
    ...
  ]
}
onChange={(pagination: any, filters: any, sorter: any) {
  console.log(pagination, '--pagination');
  console.log(filters, '--filters');
  console.log(sorter, '--sorter');
}}

Tree 组件取消 value 属性，现在只需要添加 key 属性即可。

特别注意， 此问题会导致功能出问题，需要重点关注！！！

在项目中经常在 TreeItem 中增加参数，如：<TreeItem value={value} data={data} >。在拖拽等回调中就可以通过 nodeData.props.data 的方式获取到 data 的值。但在 antd4 中，获取参数的数据结构发生了改变，原先直接通过 props 点出来的不行了。

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

2）继续使用 props。在antd4中，还是可以通过 props 找到参数，只不过 antd 会把所有参数使用 data 进行包裹，就需要改成 nodeData.props.data.data。

左侧为 3.x，右侧为 4.x。
在3.x版本，只要把节点拖拽成目标节点的上中下，即代表着目标节点的同级上方，子集，同级下方；

在 4.x 版本，是根据当前拖拽节点与目标节点的相对位置进行确定最终的拖拽结果。

当拖拽节点处于目标节点的下方，且相对左侧对齐的位置趋近于零，则最终的位置为目标节点的同级下方。

Pagination自 4.1.0 版本起，会默认将 showSizeChanger 参数设置为 true ，因而在数据条数超过50时，pageSize 切换器会默认显示。这个变化同样适用于 Table 组件，可通过 showSizeChanger: false 关闭。

如果 size 属性值为 small，则删除 size 属性。

当我们在 Drawer 上 设置了 getContainer={false} 属性之后，Drawer 会添加上 .ant-drawer-inline 的类名导致我们 position: fixed 失效。

使用如下：涉及改动点 type、dangr 属性。

使标签页不被选中。

// 3.x
activeKey={undefined}
// 4.x
activeKey={null}

该篇文章详细讲解了数栈前端团队如何从 antd3 升级到 antd4 的详细步骤，以及团队在实践过程中发现的一些问题和对应的解决方案，为后续产品的开发体验打了基础，也提供了一种更好的交互体验。

未来数栈前端团队将会持续关注产品体验以及开发中的技术痛点，以开发更好的产品为导向，助力业务发展。

▫ 《数据治理行业实践白皮书》正式发布，开辟数据治理新范式（附下载）

▫  Teradata在华落幕，国产化崛起，袋鼠云数栈会是更好的选择吗？

▫  袋鼠云数栈UI5.0焕新升级，全新设计语言DT Design，更懂视觉更懂你！

▫  袋鼠云数栈UI5.0体验升级背后的故事：可用性原则与交互升级