浅谈 formily v2 之于 formily

浅谈：v2 对于 v1 来说，看似具有推翻性变更，但实际上它的核心思想是不变的，即通过字段(SchemaField/JsonSchema)的形式去描述并且渲染成对应的表单，只不过是 v2 用了新的实现方式重写了api，加了一些概念化的东西并且使api更加精细化。

1. 官方文档也越来越精细，具体版本升级的区别就不再赘述，请参考文档。

2. 表单项获取异步选择数据

这部分我们需要了解四点：

① 相较之前版本 type 多用于基本数据类型，v2在此基础上添加了 void 类型用于专门描述非字段型表单项，比如用于布局的虚拟字段。

② 相较之前版本 直接通过 x-component 注入组件，v2在此基础上添加了 x-decorator 用于渲染更加贴近表单项的装饰组件，其可以自定义，见下面第4小节。

③ 相较之前版本 字段内部所需要用到的数据源(如 select 选项)只能通过 props.enum 或者在 props 里面自定义传入，v2 版本取而代之使用 dataSource 统一保存数据源。

④ 相较之前版本 x-linkage 的内部联动，v2版本取而代之使用 x-reactions，实现更加丰富强大的联动方式。

// 部分json schema
// ... 
{
  method: {
    type: 'number',
    required: true,
    title: '异步获取会员',
    enum: [
      {
        label: "异步会员",
        value: 1
      },
      {
        label: "静态会员",
        value: 2
      }
    ],
    'x-decorator': 'FormItem',
    'x-component': 'Select',
  },
  member: {
    type: 'string',
    required: true,
    title: '会员',
    'x-decorator': 'FormItem',
    'x-component': 'Select',
    'x-reactions': '{{fetchAsyncDataSource(fetchSelectOption)}}',
  },
}
// ...

const SchemaField = createSchemaField({
  components: {
    // ...
    FormItem,
    Select,
  },
  scope: {
    /** 异步加载select选项数据 */
    fetchSelectOption: async (field) => {
      const method = field.query('method').get('value')
      return new Promise((resolve) => {
        if(method === 1) {
          resolve([
              { label: '异步会员2', value: 2 }
            ])
        } else {
          resolve([])
        }
      })
    },
    fetchAsyncDataSource: (service) => (field) => {
      field.loading = true;
      service(field).then(action.bound((data) => {
        field.dataSource = data;
        field.loading = false;
      }))
    },
  },
})

export default () => {
  const [loading, setLoading] = useState(true)

  return (
    <Card title="编辑">
      <Spin spinning={loading}>
        <Form
          form={form}
          labelCol={5}
          wrapperCol={16}
          onAutoSubmit={console.log}
        >
          <SchemaField schema={schema} />
          <FormButtonGroup.FormItem>
            <Submit block size="large">
              提交
            </Submit>
          </FormButtonGroup.FormItem>
        </Form>
      </Spin>
    </Card>
  )
}

3. 自定义组件

这部分我们需要了解两点：

① 使用 useField() 可以获取操作当前字段的属性和方法，不在字段上下文环境下使用将返回 undefined。

② 使用 useForm() 可以获取操作当前表单的属性和方法。

// 字段json schema
// ...
{
  customMember: {
    type: 'string',
    required: true,
    title: '自定义组件字段',
    'x-decorator': 'FormItem',
    'x-component': 'CustomComponent',
  }
}
// ...

// 自定义组件
const CustomComponent = (props) => {
  const { value } = props
  const [state, setState] = useState({
    name: value?.name,
    job:value?.job
  })

  // 通过此hook 可以获取操作当前字段的api
  const field = useField()

  // // 通过此hook 可以获取操作当前表单的api
  // const form = useForm()

  useEffect(() => {
    if(value) {
      setState({
        name: value?.name,
        job:value?.job
      })
    }
  }, [value])

  const changeValue = (e, key) => {
    setState({
      ...state,
      [key]: e.target.value
    })
  }

  const onBlur = () => {
    field.setValue(state)
  }

  return (
    <div style={{display: "flex"}}>
      <p>名称</p>
      <Input value={state?.name} onChange={(e)=>changeValue(e, 'name')} onBlur={onBlur} />
      <p>职位</p>
      <Input value={state?.job} onChange={(e)=>changeValue(e, 'job')} onBlur={onBlur} />
    </div>
  )
}

// 引用渲染代码
const SchemaField = createSchemaField({
  components: {
    // ...
    FormItem,
    CustomComponent,
  },
  scope: {
    // ...
  }
})

export default () => {
  const [loading, setLoading] = useState(true)

  return (
    <Card title="编辑">
      <Spin spinning={loading}>
        <Form
          form={form}
          labelCol={5}
          wrapperCol={16}
          onAutoSubmit={console.log}
        >
          <SchemaField schema={schema} />
          <FormButtonGroup.FormItem>
            <Submit block size="large">
              提交
            </Submit>
          </FormButtonGroup.FormItem>
        </Form>
      </Spin>
    </Card>
  )
}

4. 自定义表单装饰器

// Json schema
// type: {
//   type: 'string',
//   title: '自定义表单装饰器',
//   required: true,
//   'x-decorator': 'CustomFormItem',
//   'x-component': 'Input',
// },

const CustomFormItem = (props) => {
  const field = useField()
  const { title } = field.getState()

  return (<div style={{border: "1px solid red"}}>
    <p>{title}</p>
    <p>{props.children}</p>
  </div>)
}

5. 联动

5.1 effects 生命周期方式联动

生命周期 hook 的回调参数和 useField()实例是同一个对象，可用于操作当前上下文的字段。

import React, { useState, useEffect } from 'react'
import { createForm, onFieldReact, onFieldValueChange } from '@formily/core'
import { createSchemaField, useField, useForm } from '@formily/react'
import {
  Form,
  FormItem,
  FormLayout,
  Input,
  Select,
  Submit,
  FormGrid,
  FormButtonGroup,
} from '@formily/antd'
import { Card, Button, Spin } from 'antd'

const form = createForm({
  validateFirst: true,
  effects: () => {
    onFieldValueChange('quantity', (field) => {
      const quantity = field.value
      const price = field.query('price').value()
      form.setFieldState('amount', (state) => {
        state.value = price * quantity
      })
    })
    onFieldValueChange('price', (field) => {
      const quantity = field.query('quantity').value()
      const price = field.value || 0
      form.setFieldState('amount', (state) => {
        state.value = quantity * price
      })
    })
  }
})

const SchemaField = createSchemaField({
  components: {
    FormItem,
    FormLayout,
    Input,
    Select,
  },
  scope: {},
})

const schema = {
  type: 'object',
  properties: {
    layout: {
      type: 'void',
      'x-component': 'FormLayout',
      'x-component-props': {
        labelCol: 6,
        wrapperCol: 10,
        layout: "vertical",
      },
      properties: {
        control: {
          type: 'number',
          required: true,
          title: '显示/隐藏总价',
          enum: [
            { label: '显示', value: 1 },
            { label: '隐藏', value: 0 },
          ],
          'x-decorator': 'FormItem',
          'x-component': 'Select',
        },
        quantity: {
          type: 'number',
          required: true,
          title: '数量',
          'x-decorator': 'FormItem',
          'x-component': 'Input',
        },
        price: {
          type: 'number',
          required: true,
          title: '单价',
          'x-decorator': 'FormItem',
          'x-component': 'Input',
        },
        amount: {
          type: 'number',
          required: true,
          title: '总价',
          'x-decorator': 'FormItem',
          'x-component': 'Input',
        },
      },
    }
  }
}

export default () => {
  return (
    <div>
      <Card title="编辑用户" style={{ width: 620 }}>
        <Spin spinning={loading}>
          <Form
            form={form}
            labelCol={5}
            wrapperCol={16}
            onAutoSubmit={console.log}
          >
            <SchemaField schema={schema} />
            <FormButtonGroup.FormItem>
              <Submit block size="large">
                提交
              </Submit>
            </FormButtonGroup.FormItem>
          </Form>
        </Spin>
      </Card>
    </div>
  )
}

5.2 effects 全局响应式联动

全局响应式联动依靠 onFieldReact 来实现，案例大部分代码可复用5.1小节，核心的区别在于 effects 代码块。

// ... 
effects() {
  onFieldReact('amount', (field) => {
    field.value = field.query('price').value() * field.query('quantity').value()
  })
}
// ...

5.3 x-reactions 式联动

此类联动仅在 Json Schema 层面起作用，所以不涉及到 JavaScript 代码的逻辑，Schema 的联动无需刻意区分主动还是被动，指定 target 字段即向目标字段发起联动，未指定 target 字段即需要依靠依赖项，依赖项的字段变动触发执行条件，从而改变自身字段的状态。

// Json Schema 
{
  quantity: {
    type: 'number',
    required: true,
    title: '数量',
    'x-decorator': 'FormItem',
    'x-component': 'Input',
    'x-reactions': {
      target: 'amount',
      dependencies: ['price'],
      effects: ['onFieldInputValueChange'],
      fulfill: {
        state: {
          value: '{{ $deps[0] !== undefined ? $deps[0] * $self.value : $target.value }}'
        }
      }
    }
  },
  price: {
    type: 'number',
    required: true,
    title: '单价',
    'x-decorator': 'FormItem',
    'x-component': 'Input',
    'x-reactions': {
      target: 'amount',
      dependencies: ['quantity'],
      effects: ['onFieldInputValueChange'],
      fulfill: {
        state: {
          value: '{{ $deps[0] !== undefined ? $deps[0] * $self.value : $target.value }}'
        }
      }
    }
  },
  amount: {
    type: 'number',
    required: true,
    title: '总价',
    'x-decorator': 'FormItem',
    'x-component': 'Input',
    'x-reactions': [
      {
        target: 'quantity',
        dependencies: ['price'],
        effects: ['onFieldInputValueChange'],
        fulfill: {
          state: {
            value: '{{ $deps[0] ? $self.value / $deps[0] : $target.value }}'
          }
        }
      },
      {
        target: 'price',
        dependencies: ['quantity'],
        effects: ['onFieldInputValueChange'],
        fulfill: {
          state: {
            value: '{{ $deps[0] ? $self.value / $deps[0] : $target.value }}'
          }
        }
      }
    ]
  },
}

5.4 异步联动(以 schema 方式为主)

相较于生命周期函数里面做异步联动，Schema 里面做注入异步联动逻辑会稍微晦涩难懂，之前版本，我们传入局部作用域可以通过 expressionScope 注入到对应的表单中，在v2使用协议表达式作用域 scope 来替代。

我们需要了解两个工厂函数：

① createForm 创建 form 实例，可以注入表单值、副作用等属性；

② createSchemaField 创建解析 Json Schema 的组件，可以注入作用域函数和组件。

5.4.1 主动方式(基于run的语法方式)

import React, { useState } from 'react'
import { createForm } from '@formily/core'
import { createSchemaField, useField, useForm } from '@formily/react'
import {
  Form,
  FormItem,
  FormLayout,
  Input,
  Select,
  Submit,
  FormButtonGroup,
} from '@formily/antd'
import { Card, Button, Spin } from 'antd'

const form = createForm({
  validateFirst: true,
  effects: () => {}
})

const SchemaField = createSchemaField({
  components: {
    FormItem,
    FormGrid,
    FormLayout,
    Input,
    Select,
  },
  scope: {
    /** 异步联动 */
    asyncVisible: (field, target) => {
      field.loading = true
      setTimeout(() => {
        form.setFieldState(target, state => state.display = field.value ? 'visible' : 'none')
        field.loading = false
      }, 3000)
    }
  },
})

const schema = {
  type: 'object',
  properties: {
    layout: {
      type: 'void',
      'x-component': 'FormLayout',
      'x-component-props': {
        labelCol: 6,
        wrapperCol: 10,
        layout: "vertical",
      },
      properties: {
        control: {
          type: 'number',
          required: true,
          title: '显示/隐藏总价',
          enum: [
            { label: '显示', value: 1 },
            { label: '隐藏', value: 0 },
          ],
          'x-decorator': 'FormItem',
          'x-component': 'Select',
          'x-reactions':{
            target: 'controlled',
            effects: ['onFieldInit', 'onFieldValueChange'],
            fulfill: {
              run: 'asyncVisible($self, $target)',
            },
          }
        },
        controlled: {
          type: 'string',
          required: true,
          title: '受控元素',
          'x-decorator': 'FormItem',
          'x-component': 'Select',
        },
      },
    }
  }
}

export default () => {
  const [loading, setLoading] = useState(true)

  return (
    <div>
      <Card title="编辑用户" style={{ width: 620 }}>
        <Spin spinning={loading}>
          <Form
            form={form}
            labelCol={5}
            wrapperCol={16}
            onAutoSubmit={console.log}
          >
            <SchemaField schema={schema} />
            <FormButtonGroup.FormItem>
              <Submit block size="large">
                提交
              </Submit>
            </FormButtonGroup.FormItem>
          </Form>
        </Spin>
      </Card>
    </div>
  )
}

5.4.2 被动方式(直接调用方式)

这里我们需要提前了解，query 方法会返回一个 Query 对象，Query 对象中可以有批量遍历所有字段的 forEach/map/reduce 方法，也可以有只取查询到的第一个字段的 take 方法，同时还有直接读取字段属性的 get 方法，还有可以深层读取字段属性的 getIn 方法，两个方法的差别就是前者可以有智能提示，后者没有提示，所以更推荐用 get 方法。

import React, { useState } from 'react'
import { createForm } from '@formily/core'
import { createSchemaField, useField, useForm } from '@formily/react'
import {
 Form,
 FormItem,
 FormLayout,
 Input,
 Select,
 Submit,
 FormButtonGroup,
} from '@formily/antd'
import { Card, Button, Spin } from 'antd'

const form = createForm({
 validateFirst: true,
 effects: () => { }
})

const SchemaField = createSchemaField({
 components: {
   FormItem,
   FormLayout,
   Input,
   Select,
 },
 scope: {
   /** 异步联动 */
   asyncVisible: (field) => {
     const controlField = field.query('control').take()
     // const controlField = field.query('control')
     /** 此处 是否使用take的区别在于 take返回的是字段对象，而直接query返回的是query对象，直接操作字段功能有限 */
     const controlValue = controlField.value
     console.log(controlField, 'controlField', controlValue)
     if(typeof controlValue === 'number') {
       controlField.loading = true
       setTimeout(() => {
         field.display = controlValue ? 'visible' : 'none'
         controlField.loading = false
       }, 3000)
     }
   }
 },
})

const schema = {
 type: 'object',
 properties: {
   layout: {
     type: 'void',
     'x-component': 'FormLayout',
     'x-component-props': {
       labelCol: 6,
       wrapperCol: 10,
       layout: "vertical",
     },
     properties: {
       control: {
         type: 'number',
         required: true,
         title: '显示/隐藏总价',
         enum: [
           { label: '显示', value: 1 },
           { label: '隐藏', value: 0 },
         ],
         'x-decorator': 'FormItem',
         'x-component': 'Select',
       },
       controlled: {
         type: 'string',
         required: true,
         title: '受控元素',
         'x-decorator': 'FormItem',
         'x-component': 'Input',
         'x-reactions': '{{asyncVisible}}'
       },
     },
   }
 }
}

export default () => {
 const [loading, setLoading] = useState(true)
 return (
   <div>
     <Card title="编辑用户" style={{ width: 620 }}>
       <Spin spinning={loading}>
         <Form
           form={form}
           labelCol={5}
           wrapperCol={16}
           onAutoSubmit={console.log}
         >
           <SchemaField schema={schema} />
           <FormButtonGroup.FormItem>
             <Submit block size="large">
               提交
             </Submit>
           </FormButtonGroup.FormItem>
         </Form>
       </Spin>
     </Card>
   </div>
 )
}