@aotoo/ergateform

前言

ErgateForm 是配置化的 antd form(react) 组件。通过配置化生成表单。实现了表单联动、动态表等单功能，表单属性仍沿用 antd form 各个组件的属性。

我自己在做 ToB 类项目时，比较头疼大量的表单业务。会将表单等组件重新封装一下，使用 JSON 来配置化自动生成表单。即方便 CV，也方便各种抽离，对于模块化也比较友好，下图是我做的 DEMO，可以很方便的组合成各种表单

基础使用

安装

npm install @aotoo/ergateform

# or

yarn add @aotoo/ergateform

基础表单

import ErgateForm from '@aotoo/ergateform'
import {Form}  from 'antd'

function App(){
  const form = Form.useForm()
  const formConfig = {
    labelCol:{ span: 8 }
    wrapperCol: { span: 16 }
    layout: "horizontal"
    initialValues: {textbox: 'hello world'}
    form: form  // antd的form实例
    data: [
      {
        label: '文本框',
        name: 'textbox',
        $input: {
          type: 'text',
        },
      },
    ]
  }

  return (
    <ErgateForm {...formConfig}/>
  )
}

联动表单

表单值同步

import ErgateForm from '@aotoo/ergateform'
import {Form}  from 'antd'

function App(){
  const form = Form.useForm()  // antd的form实例
  const formConfig = {
    labelCol:{ span: 8 }
    wrapperCol: { span: 16 }
    layout: "horizontal"
    initialValues: {textbox: 'hello world'}
    form: form
    data: [
      {
        label: '目标文本框',
        name: 'target-input',
        $input: { type: 'text'},
      },
      {
        label: '响应文本框',
        name: 'response-input',
        $input: { type: 'text' },
        union: {
          target: 'target-input',
          event: 'onChange',
          callback(e){
            console.log(e.target.value)
            form.setFieldValue('response-input', e.target.value)
          }
        }
      },
    ]
  }

  return (
    <ErgateForm {...formConfig}/>
  )
}

支持的表单类型

{
  $input: { type: '???', }  // type 用来设置表单类型
}

button => Button
text => Input 表单的别名
textarea => Input.TextArea 别名
search => Input.Search
password => Input.Password
cascader => Cascader
select => Select
autocomplete => AutoComplete
inputnumber => InputNumber
rate => Rate
slider => Slider
switch => Switch
timepicker => TimePicker
timerange => TimePicker.RangePicker 别名
treeselect => TreeSelect
datepicker => DatePicker
daterange => DatePicker.RangePicker 别名
checkbox => Checkbox
checkboxGroup => Checkbox.Group
radio => Radio
radioGroup => Radio.Group
transfer => Transfer
upload => Upload

配置

Form 配置

在ErgateForm中使用最外层的非data属性来配置 Form 属性

Form.state
这是 ErgateForm 的属性，原生 antd Form 表单无此属性，该属性作用是用来方便模块化时能够方便设置状态值得变更，使用 React 的 useState 实现

ergateform 的写法

const formConfig = {
  labelCol:{ span: 8 }
  wrapperCol: { span: 16 }
  layout: "horizontal"
  ...
  data: [...]  // data用来配置 Form.Item 集合
}

return <ErgateForm {...formConfig}/>

// 或者

return <ErgateForm
  labelCol= {{span: 8}}
  wrapperCol={{span: 16}}
  layout={'horizontal'}
  ...
  data: [...]
/>

antd form 原生写法

<Form labelCol={{ span: 8 }} wraperCol={{ span: 16 }} layout="horizontal">
  ...
</Form>

FormItem 配置

Form.Item 是 antd 表单的基础结构。ErgateForm 使用data的数据项来配置Form.Item属性及表单属性

ergateform 的写法

data 为数组

// 配置
{
  data: [
    {
      label: '标题名',  // 对应 Form.Item 的label属性
      name: 'uniq-name' // 对应 Form.Item 的name属性
      $input: { ... } // 配置表单属性
    },
    JSX,
    union(...)
  ]
}

data 配置为方法
可以将 data 设置为方法，只要数组项数组即可。该方法接收state, setState两个参数，这样我们可以在配置中灵活设置一些状态

data: function(state, setState){
  return [
    ...
  ]
}

数据项可以是 JSX，或者union方法返回的结构，union 方法后面会讲到

antd form 原生写法

<Form.Input label="标题名" name="uniq-name">
  <input {...$input} />
</Form.Input>

横向排列

ErgateForm 默认使用Space组件来横向排列表单，只需要将$input配置成数组即可，来看配置

{
  data: [
    {
      ...,  // 此时这里的属性会自动添加到Space组件中
      $input: [
        {
          label: 'UserName',
          name: 'username',
          $input: {  // 嵌套表单仍然使用`$input`属性
            type: 'text',
          }
        },
        {
          label: 'Password',
          name: 'password',
          $input: {
            type: 'password'
          }
        }
      ]
    }
  ]
}

radio / checkbox 的竖向排列，官网是使用 Space 组件包裹，这里直接添加$input.direction

特殊属性

ErgateFome加入的属性，用来控制配置结构和联动

$input
union

$input

$input用来配置具体的表单/表单组，如 Input, Select等支持的表单元件，api 属性与官网一致

$input.type

该属性用来标识使用那个表单组件，

antd 的 Button 组件包含 type 属性，请使用 buttonType 替换

union

用来设置表单联动，union 的实现思路有点类似于监视者的角色，当目标值变更时及时做出响应。union 属性包含三个必须设置的参数 target、event、callback

union.target

描述对齐的目标 name

union.event

表单组件一般都有几个事件方法，例如 Search 表单组件有 onSearch 和 onChange 等事件，我们只想关注 onChange 事件时将 union.event 设置为 onChange 即可

union.callback

事件响应方法，当对齐目标表单状态发生改变时，触发该方法

多联动

一个表单需要关注多个表单时设置，将 union 设置为数组即可实现多联动

示例 code

[
  {
    label: '我是目标表单',
    name: 'name-target',
    $input: {type: 'select', ...}
  },

  // 单联动
  {
    label: '单联动响应表单',
    name: 'name-response',
    union: {
      target: 'name-target',
      event: 'onChange',
      callback(value, option){
        /** do something */
      }
    }
  },

  // 多联动
  {
    label: '多联动响应表单',
    name: 'mul-response',
    union: [
      {target: 'name-target', event: 'onChange', callback: ...},
      {target: 'name-target', event: 'onSearch', callback: ...},
    ]
  }
]

union 方法

在设计表单时，有些结构需要根据状态来显示，此时可以引入 union 方法来实现这种类型的需求。

union 方法实现的原理是通过 antd 的form.useWatch对观测表单的状态改变做出响应。需要注意，如果表单组件不包含value属性，会提示报错。例如 Checkbox 组件就不包含 value 属性，需要通过 state 来控制 Checkbox 的状态。幸运的是其他所有表单都有 value 属性

union 方法的用法

union 有三种设置方法

对表单响应
对 state 属性响应
无响应，但会在表单完成时反馈出结构(useEffect 实现)

// 联动组件
union('target-name', function (value) {
  return JSX;
});

// 联动state
union('state.xxx', function (value) {
  return JSX;
});

// 无响应
union('任意字串描述，不可以和组件name/state[name]重名即可', function (value) {
  return JSX;
});

union 方法中也可以设置其他表单组件的属性，但一定要加上延迟，否则会造成渲染冲突，这一点后面会讲到

示例 CODE

注意下面的 union 方法的使用的位置

import ErgateForm {union} from '@aotoo/ergateform'
import {Form} from 'antd'

function App(){
  const form = Form.useForm()
  const formConfig = {
    ... // Form配置项
    data: function(state, setState){
      return [
        {
          $input: [ // 表单组
            {
              label: '文本框',
              name: 'target-select',
              $input: {
                type: 'select',
                options: [
                  {label: '选项一', value: '1'},
                  ...
                ]
              }
            },
            // 组内union
            union('target-select', function(value){
              if (value === '3'){
                return <div>response vlaue 3</div>
              }
            })
          ],
        },

        <button>按钮</button>,  // 支持直接插入JSX

        // 组外union
        union('target-input', function(value){
          if (value === '1') {
            return <div>response value 1</div>
          }
          if (value === '2') {
            return <div>response value 2</div>
          }
        }),

        // state联动
        union('state.xxx', function(value){
          return JSX
        })
      ]
    }
  }

  return <ErgateForm {...formConfig}/>
}

return <App />

union 方法不需要设置 event 参数，内部使用了 antd 的 Form.useWatch 实现值变更追踪

暂时不支持 async await promise 的使用

复杂使用

getForm 方法

Ergate 使用的是 antd 的最新版本(5.0.3)，antd Form 可以使用 form 的实例来做很多事情，具体使用方法可以参考官方文档

getForm 方法是为了模块化时能方便取到 form 实例，ErgateForm 会拦截每个表单事件的回调方法，重构后并还原成原来的使用方式

data = [
  {
    label: 'title',
    name: 'name',
    $input: {
      type: 'button',
      buttonType: '...', // 注意button组件是没有value的，不能够使用union来追踪
      onClick() {
        const form = this.getForm(); // 获取form的实例
        form.setFieldValue('xxx-name', value);
      },
    },
  },
];

setOptions 方法

setOptions可以很方便的设置表单内的各个 Select 组件的下拉列表

data = [
   {
     label: 'title',
     name: 'select-name',
     $input: {
       type: 'select',
       options: []
     }
   },

   {
     $input: {
       type: 'button',
       onClick(){
         const form = this.getForm()
         form.setOptions('select-name', [
           {label: '选项一', value: '1'},
           {label: '选项二', value: '2'},
           ...
         ])
       }
     }
   }
 ]

union 方法中设置其他表单属性

不建议在 union 的回调方法中设置其他表单的属性，如果非要设置请加上延迟方法，否则会造成渲染冲突
示例 code

{
  data: [
    ...,

    {
      label: '选择框',
      name: 'select-box',
      $input: {
        options: [
          {lable: 'a', value: 'a'},
          {lable: 'b', value: 'b'},
        ]
      }
    },

    union('select-box', function(value){
      const form = this.getForm()
      if (value === 'b') {
        setTimeout(()=>{
          form.setOptions('select-box', [...])
        }, 100)
      }
      return JSX || null
    })
  ]
}

使用 state

const stateData = {
  checked: false
}

{
  layout="horizontal"
  onFinish={onFinish}
  ...
  state={stateData}
  data: function(state, setState){
    return [
      {
        name: 'check-box',
        $input: {
          type: 'checkbox',
          checked: state.checked,
          onChange(){
            setState({
              checked: !state.checked
            })
          }
        }
      },

      union('state.checked', function(value){
        console.log(value)
      })
    ]
  }
}

@aotoo/ergateform

前言

基础使用

安装

基础表单

联动表单

支持的表单类型

配置

Form 配置

FormItem 配置

横向排列

特殊属性

$input

$input.type

union

union.target

union.event

union.callback

多联动

示例 code

union 方法

union 方法的用法

示例 CODE

复杂使用

getForm 方法

setOptions 方法

union 方法中设置其他表单属性

使用 state

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads