order: 6 title: 0.x 到 1.x 升级方案 toc: content

hide: true

升级方案

三个改变

FormRender v1.0.0 的升级，从使用方视角来看，最主要的变动归结为三条：

  1. 提交的方法收束（即统一提供 submit 方法），formData 和校验信息内置

  2. Schema 书写规则更加清晰，更加贴近组件 props

  3. 自定义组件不再要“套壳”，很多 antd 组件直接拿来能用

第 1 条是为了更加强大的功能，后两条则为了更加快捷和舒适的开发体验。FormRender 1.0 带来了哪些新功能，详见文章底部 Changelog 思考

迁移方案如下

FormRender v0.x 的代码如下：

  1. import React, { useState } from 'react';
  2. import FormRender from 'form-render/lib/antd';
  4. const schema = {
  5.   type: 'object',
  6.   properties: {
  7.     string: {
  8.       title: '字符串',
  9.       type: 'string',
  10.     },
  11.   },
  12. };
  14. function Demo() {
  15.   const [formData, setData] = useState({});
  16.   const [valid, setValid] = useState([]);
  17.   const onSubmit = () => {
  18.     if (valid.length > 0) {
  19.       alert(`校验未通过字段：${JSON.stringify(valid)}`);
  20.     } else {
  21.       alert(JSON.stringify(formData));
  22.     }
  23.   };
  24.   return (
  25.     <div>
  26.       <FormRender
  27.         schema={schema}
  28.         formData={formData}
  29.         onChange={setData}
  30.         onValidate={setValid}
  31.       />
  32.       <button onClick={onSubmit}>提交</button>
  33.     </div>
  34.   );
  35. }
  37. export default Demo;

新版本升级改动

完全使用新 api，formData 和 onChange 这些原本暴露在外的属性收束，submit 方法由 form 实例提供，一般情况下迁移也快的，只是要注意所有在外部使用到 formData 的场景，需要替换为 form.getValues()，所有使用到 onChange 的地方需要修改为 form.setValues()

  1. /**
  2.  * transform: true
  3.  * defaultShowCode: true
  4.  */
  5. import React from 'react';
  6. import FormRender, { useForm } from 'form-render'; // 1. 改 import
  8. const schema = {
  9.   type: 'object',
  10.   properties: {
  11.     string: {
  12.       title: '字符串',
  13.       type: 'string',
  14.       required: true,
  15.     },
  16.   },
  17. };
  19. function Demo() {
  20.   const form = useForm(); // 2. 获取 form 实例，现在所有表单方法都挂在上面
  21.   // 3 onSubmit 的入参
  22.   const onSubmit = (formData, valid) => {
  23.     if (valid.length > 0) {
  24.       alert(`校验未通过字段：${JSON.stringify(valid)}`);
  25.     } else {
  26.       alert(JSON.stringify(formData));
  27.     }
  28.   };
  29.   return (
  30.     <div>
  31.       <FormRender
  32.         form={form} // 4 补上
  33.         schema={schema}
  34.         onFinish={onSubmit} // 5. 补上
  35.         // formData={formData} // 6. 干掉
  36.         // onChange={setData}
  37.         // onValidate={setValid}
  38.       />
  39.       <button onClick={form.submit}>提交</button>
  40.     </div>
  41.   );
  42. }
  43. export default Demo;

由于新版的 formData/onChange/validate/onValidate 全部内置了，所以在迁移时，外部所有使用到三者的地方一律使用 form 方法替换：

  1. formData  ->  form.getValues()
  2. onChange  ->  form.setValues(data)
  3. validate  ->  form.errorFields
  4. onValidate  ->  直接去掉

自定义组件侧的 0.x 与 1.x 的使用对比：

  1. // 0.x
  2. const schema = {
  3.   title: '自定义',
  4.   type: 'string',
  5.   'ui:widget': 'myWidget',
  6.   'ui:options': {
  7.     prefix: 'hello',
  8.   },
  9. };
  11. const MyWidget = ({ name, value, onChange, options }) => {
  12.   const handleChange = e => {
  13.     onChange(name, e.target.value);
  14.   };
  15.   return (
  16.     <div>
  17.       <Input value={value} onChange={handleChange} {...options} />
  18.       <span>注意事项</span>
  19.     </div>
  20.   );
  21. };
  22. // 1.x
  23. const schema = {
  24.   title: '自定义',
  25.   type: 'string',
  26.   widget: 'myWidget',
  27.   props: {
  28.     prefix: 'hello',
  29.   },
  30. };
  32. const MyWidget = props => {
  33.   return (
  34.     <div>
  35.       <Input {...props} />
  36.       <span>注意事项</span>
  37.     </div>
  38.   );
  39. };
  1. onChange 不再接收 name 作为第一个入参，而改为更为自然的只有一个入参 value
  2. 所有ui:options的内容会直接在 props 里拿到，而不需要再从 props.options 里获取 （ui:options 已更名为 props，不过在顶层做了 schema 字段的兼容）

schema 细节上的改动

单选组件不再默认选中第一项，默认值为 undefined，除非通过 default 字段指明。

  1. // 单选
  2. {
  3.   "title": "单选",
  4.   "type": "string",
  5.   "enum": ["hz", "wh", "gy"],
  6.   "enumNames": ["杭州", "武汉", "贵阳"],
  7.   "default": "hz"
  8. }

旧版 schema 转换器：

  1. import React, { useState } from 'react';
  2. import { Input, Button } from 'antd';
  3. import { updateSchemaToNewVersion } from 'form-render/src/form-render-core/src/utils.js';
  5. const TextArea = Input.TextArea;
  7. const old = {
  8.   type: 'object',
  9.   properties: {
  10.     number: {
  11.       title: '数字输入框',
  12.       type: 'number',
  13.       'ui:disabled': true,
  14.     },
  15.     checkbox: {
  16.       title: '是否选择',
  17.       type: 'boolean',
  18.       'ui:widget': 'switch',
  19.     },
  20.   },
  21.   required: ['number'],
  22. };
  24. const Translator = () => {
  25.   const [oldSchema, setOld] = useState(JSON.stringify(old));
  26.   const [newSchema, setNew] = useState({});
  28.   const handleClick = () => {
  29.     try {
  30.       const _newSchema = updateSchemaToNewVersion(JSON.parse(oldSchema));
  31.       setNew(_newSchema);
  32.     } catch (err) {
  33.       console.log(err);
  34.     }
  35.   };
  37.   const onOldChange = e => {
  38.     setOld(e.target.value);
  39.   };
  41.   const formatOld = () => {
  42.     setOld(JSON.stringify(JSON.parse(oldSchema), null, 2));
  43.   };
  45.   return (
  46.     <div>
  47.       <div>填入旧版schema：</div>
  48.       <TextArea
  49.         style={{ minHeight: 400, marginTop: 12, marginBottom: 12 }}
  50.         value={oldSchema}
  51.         onChange={onOldChange}
  52.       />
  53.       <Button style={{ marginRight: 12 }} onClick={formatOld}>
  54.         格式化旧schema
  55.       </Button>
  56.       <Button type="primary" onClick={handleClick}>
  57.         生成新版schema
  58.       </Button>
  59.       <TextArea
  60.         style={{ minHeight: 400, marginTop: 12 }}
  61.         value={JSON.stringify(newSchema, null, 2)}
  62.       />
  63.     </div>
  64.   );
  65. };
  67. export default Translator;

Changelog 思考

在最后罗列一下细节上 FormRender 0.x -> 1.0 细节上的改动 & 思考

功能增强

  1. 展示升级

    • 列表的展示支持三种模式，分别支持每个 item 1-2 个元素，3-5 个元素和复杂结构
    • 对象的展示支持二种模式
    • 校验的展示和 antd 效果一致
    • 展示类型除了基础的 column 和 row，还支持了 inline 模式

  2. 内置组件更丰富

    • 新增了 rate，treeSelect, cascader 等组件的内置支持

  3. 自定义组件开发更便捷，功能更强大

    • props 直接透传了，不再需要从 options 字段里去取得
    • onChange 方法的入参不再需要传 name 作为第一个参数（这个设计其实很不自然和没有必要），同时如果原生组件的 onChange 返回的是 event，也会处理一步自动能拿到 value 值
    • 自定义组件内置了 onItemChange(namePath, value) 方法，可以方便的在一个自定义组件中修改表单任何数据的值

    • 这些细节的目标，是让自定义组件的书写贴近拿来一个组件直接能用，而不是像之前一样再简单的场景也需要做一步包装处理，从原本的：

      1. const schema = {
      2.   title: '自定义',
      3.   type: 'string',
      4.   'ui:widget': 'myWidget',
      5.   'ui:options': {
      6.     prefix: 'hello',
      7.   },
      8. };
      10. const MyWidget = ({ name, value, onChange, options }) => {
      11.   const handleChange = e => {
      12.     onChange(name, e.target.value);
      13.   };
      14.   return (
      15.     <div>
      16.       <Input value={value} onChange={handleChange} {...options} />
      17.       <span>注意事项</span>
      18.     </div>
      19.   );
      20. };

    • 变为：

      1. const schema = {
      2.   title: '自定义',
      3.   type: 'string',
      4.   widget: 'myWidget',
      5.   props: {
      6.     prefix: 'hello',
      7.   },
      8. };
      10. const MyWidget = props => {
      11.   return (
      12.     <div>
      13.       <Input {...props} />
      14.       <span>注意事项</span>
      15.     </div>
      16.   );
      17. };

  4. 校验丰富度和体验大幅升级

    • 校验的展示 & 展示实际终于符合用户习惯了
    • 不再只支持 pattern 校验了，现在支持包括自定义 validator 的所有 antd form 支持的校验
    • 校验支持异步了
    • 校验支持外部校验结果回填展示了

  5. 其他

    • 未压缩的包体积从 76k -> 11k
    • 对 typescript 的内置支持
    • 渲染会根据 schema 的结构来渲染，不再会因为 formData 值的顺序变化影响到展示
    • 提交的 formData，不展示的 key 不会返回

设计取舍

  1. 暂时不支持 fusion 了：fusion 与 antd 展示上非常类似，但组件 api 本身以及构建层面的配置上还是有不少不同的，对两者的同时支持花了大量的精力。FormRender 选择暂时放弃 fusion，更加贴合 antd，在功能深入实现和迭代效率上都会有很大的提高。但组件库的入口是一直开放着的（widgets props），欢迎 pr 支持 fusion 侧的组件的独立支持。

  2. 只允许使用字符串类型的函数表达式：由于 schema 可以是 js 对象，所以之前支持 schema 里有函数类型的表达式，会在渲染前计算出函数的 return 作为渲染值。但组件的 props 以及校验函数可能本身就是函数，这些函数是不希望被提前计算的，而只是作为 props 传入。FR 并没有很好的办法区分一个函数是需要被直接执行还是原样作为函数透传，所以这里的取舍是，不允许函数 props 或者不允许函数式的表达式。由于表达式已经有字符串的书写方式，功能是完全等价的，所以为了允许函数作为 props，我们不再支持函数作为表达式。

    1. showMore: {
    2.   title: "显示更多",
    3.   type: "boolean"
    4. },
    5. input1: {
    6.   title: '输入框1',
    7.   type: 'string',
    8.   'ui:hidden': (formData) => !formData.showMore
    9. }
    11. // 请转换为：
    12. showMore: {
    13.   title: "显示更多",
    14.   type: "boolean"
    15. },
    16. input1: {
    17.   title: '输入框1',
    18.   type: 'string',
    19.   'ui:hidden': '{{!formData.showMore}}',
    20. }

  3. 不再计算初始值：这是一个内部的改动。新的 FormRender，不会每次 onChange 后都执行 resolve 生成一份 formData 的骨架，没有填的框的值就是 undefined。而只在提交和校验时会生成骨架。这避免了很多在自定义组件中尝试修改 formData 时容易产生死循环或者修改无效的问题，也避免了外部没有很好的方法拿到黑箱的 resolve 后的数据。