@ice/form

---

title: IceForm category: Components chinese: 表单组件

表单组件

参数（Props）

参数名	说明	必填	类型	默认值	备注
initialValues	表单初始值	N	object	{}	-
onSubmit	submit函数	Y	function	-	-
onChange	表单变化回调	N	function	-	function(values: object, item: object) => void 参数: values: {object} 表单数据 item: {object} 详细 item.name: {string} 变化的组件名 item.value: {string} 变化的数据
rules	校验规则	N	object	{}	-
effects	联动规则	N	array	[]	-
layout	表单布局	N	object		-
renderField	自定义 Field 布局	N	function	-	function({label, component, error}) => dom 参数: label: {string/element} Field 的 label component: {string/function} 待渲染的控件 error: {string/element} Field 错误提示信息

其他属性比如 style、className 等均会传递到 form 标签上。

layout 是个对象，包含 4 个属性：

{
  labelAlign: 'left',       // label 的位置，'left'、'top'，默认 'left'
  labelTextAlign: 'right',  // label 文字对齐方式，'left'、'right'，默认 'right'
  labelCol: 1,             // label 占的栅格宽度，共 12 等分，默认 2
  wrapperCol: 3,           // 控件占的栅格宽度，共 12 等分，默认 6
}

rules 是一个 Object，key 是 <Field> 的 name 属性值，value 是个数组，数组里面的每一项是一个校验规则，参考 async-validator。

<Form
  onSubmit={this.onSubmit}
  style={{color: '#ee7893'}}
  rules={{
    username: [{
      required: true,
      min: 5,
      message: '姓名至少5个字符'
    }],
    age:  [{
      required: true,
      message: '年龄必填'
    }]
  }}
>
  <Field label="姓名：" name="username" component="input" type="text" />
  <Field label="年龄：" name="age" component='input' type="number" />
</Form>

effects 是个数组，写法如下：

<Form
  onSubmit={this.onSubmit}
  effects={[
    {
      field: 'username',
      handler: formCore => {
        if (formCore.getFieldValue('username') === 'ice') {
          formCore.setFieldValue('age', 2)
        }
      }
    }
  ]}
>
  <div>Hello Form</div>
  <Field label="姓名：" name="username" component="input" type="text" />
  <Field label="年龄：" name="age" component='input' type="number" />
  <button type="submit">Submit</button>
</Form>

监听该 field 的 onChange 事件，然后设置其他表单项的数据，从而达到联动效果。handler 的参数是 formCore 对象，该对象暴露一些 api 可以设置 value、error、show/hide 等。

Field 组件

参数名	说明	必填	类型	默认值	备注
label	表单项的 label	N	string/element	-	-
name	表单项的 name	Y	string	-	-
component	表单类型，原生 html 标签或者三方组件	N	string/function	-	'input' 'textarea' Input Radio
value	表单项的值	N	-	''	-
rules	校验规则	N	object or array	-	-
effects	联动规则	N	object	-	-
visible	显示隐藏当前 Field	N	boolean	true	true/false
setValueFormatter	格式化控件渲染值	N	function		function(savedValue) => renderValue
getValueFormatter	格式化控件提交值	N	function		function(renderValue) => savedValue
layout	设置当前 Field 的布局	N	object	同 Form layout	当前 Field 的 layout 会覆盖 Form 的 layout
tips	提示信息	N	string
valueName	控件值的名称，比如，radio 的 valueName 为 'checked'，value 为 true/false	N	string		比如 Fusion 的 Switch 组件
errorRender	自定义 error 渲染	N	function(error) {}
onChange	自定义 onChange 函数	N	function() {}		默认情况下已处理表单的 onChange(eventOrValue) 事件，如果接入的三方控件 onChange 的第一个参数不是 event 或者 value，可以主动设置对应的值。比如，接入控件的 onChange(xxx, value) 第二个参数才是 value，则可以手动设置 formCore.setValue(fieldname, value)

style、className 属性会传递到 Field 最外层 dom 上，其他属性会传递到 component 上，如果没有 component 但有 children，则属性传递到 children 上。

Field 的 rules 和 effects 不需要 name 作为 key 了，写法如下：

<Form onSubmit={this.onSubmit}>
  <Field label="姓名：" name="username" component="input" type="text" />
  <Field label="昵称：" name="nickname" component="input" type="text" effects={{
    handler: formCore => {
      if (formCore.getFieldValue('nickname') === 'snow') {
        formCore.setFieldProps('age', {
          visible: true,
        });
      } else {
        formCore.setFieldProps('age', {
          visible: false,
        });
      }
    }
  }} />
  <Field label="年龄：" name="age" component='input' type="number" rules={[{
    required: true,
    message: '年龄必填'
  }]} />
  <button type="submit">Submit</button>
</Form>

FieldArray 组件

FieldArray 表示渲染数组类型的数据，属性同 Field：

<Form
  onSubmit={this.onSubmit}
>
  <FieldArray label="新增顾客：" name="customers">
    <Field name="customer0" component={Input} placeholder="customer name" />
    <Field name="customer1" component={Input} placeholder="customer name" />
    <Field name="customer2" component={Input} placeholder="customer name" />
  </FieldArray>
  <Field label="日期：" name="date" component={DatePicker} />
  <Field label="">
    <Button htmlType="submit">Submit</Button>
  </Field>
</Form>

formCore API

formCore 会暴露一些 API，使用这些 API 可以获取、设置表单的数据、状态等。

• getFieldValue(name)：获取某一 Field 的值
• setFieldValue(name, value)：设置某一 Field 的值
• getValues()：获取表单的 values
• setValues(values, runEffects)：设置表单的 values，runEffects 为 Boolean，表示设置 values 之后是否需要执行表单的 effects，默认 false
• getFieldError(name)：获取某一 Field 的 error 信息
• setFieldError(name, errMsg)：设置某一 Field 的 error 信息
• getErrors()：获取所有 Field 的 error 信息
• setErrors(errors)：设置某些 Field 的 error 信息
• getFieldProps(name)：获取某一 Field 的属性值
• setFieldProps(name, prop)：设置某一 Field 的属性值
• submit()：提交表单
• reset(initialValues)：重置表单值为表单初始化时的默认值，如果表单初始化时没有默认值，则清空表单；如果传了参数 initialValues，则 initialValues 会成为新的表单默认值

也可以通过属性的方式获取到一些数据：

• formCore.values：获取表单的所有值
• formCore.errors：获取表单校验的错误信息
• formCore.pristine：表单当前的 values 是否与 initialValues 相等

延伸阅读

开发 @ice/form 表单背景

对于前端，表单开发是一件特别繁琐的事情，尤其在中后台业务中，大家常常会被各种五花八门的表单折磨，又不得不面对现实地去寻找最佳方案，但最终都会发现过度设计的表单组件性能不好，使用简单的表单组件还是需要写大量的业务代码。经过长期的积累以及在社区的调研，我们开发了一个表单组件帮助大家快速地创建一个高性能表单。

组件特性

• 内部几乎无依赖，体积小
• 内部管理表单状态，提升开发效率
• 使用观察者模式提升表单性能
• 强大的校验以及声明式联动
• 可结合第三方组件库(Next、Antd)
• 可自定义 Field

架构方案

如上图所示，整个表单的数据都放在 FormCore 这一层，同时 FormCore 会暴露一些 API，以便获取、设置、处理数据。Form、Field 组件通过 Sub/Pub 模式与 FormCore 通信，FormCore 通知组件何时重新渲染。表单提供了校验、联动以及结合 Fusion、Antd 三方组件库使用等能力。

竞品对比

NoForm

NoForm 是一个表单操作(比如说校验、提交、联动等)抽象到上层，下层又包装了 Next、Antd 等组件，UI 上的能力较强，也封装了一些常用的布局，但功能能力较弱，用户实现复杂逻辑还是需要写很多代码。

Formik、react-final-form

这两个组件有一些共性，都是通过 render props 的方式实现了复杂的状态管理，在性能上也非常地卓越，在社区得到了大量的好评，但在联动上的能力较弱(目前只能更新 value)，而且如果要集成 Next 或者 Antd 需要将库的表单组件都封装成 Field，成本较高。

相关链接

• formik
• react-final-form
• noform