表单(Form)

• 按需重绘，避免了不必要的全量渲染, 性能更高
• 简单易用，结构极简，避免了不必要的层级嵌套
• 在 Form 外部可方便地获取 formState / fieldState
  提供在外部对表单内部进行操作的方法：formApi / fieldApi
• 支持将自定义组件封装成表单控件，你可以通过 Form 提供的扩展机制（withField HOC）快捷接入自己团队的组件
• 支持 Form level/Field level 级别的赋值、校验（同步/异步）

表单控件(Field)

目前 Form 提供了如下表单控件

• Input、InputNumber、TextArea、Select、Checkbox、Radio、RadioGroup、Switch、DatePicker、TimePicker、Slider、InputGroup、TreeSelect、Cascader、Rating、AutoComplete、Upload、Label、ErrorMessage、Section、TagInput 都挂载在 Form 下，使用时直接以<Form.Input> 、<Form.Select>声明即可

代码演示

声明表单的多种写法

基本写法

支持的其他写法

通过 render 属性传入

通过 child render function

通过 props.component

已支持的表单控件

Form.TreeSelect、Form.Cascader、Form.Rating 在 v0.22.0 及之后的版本开始提供；
Form.AutoComplete 在 v0.28.0 及之后的版本开始提供
Form.Upload 在 v1.0.0 及之后的版本开始提供
Form.TagInput 在 v1.21.0 及之后的版本开始提供

表单控件值的绑定

表单布局

• 垂直布局：表单控件之间上下垂直排列（默认）
  Semi Design 更推荐表单采用垂直布局

• 水平布局：表单控件之间水平排列 你可以通过设置 layout='horizontal'来使用水平布局

• labelPosition、labelAlign
  你可以通过设置 labelPosition、labelAlign 控制 label 在 Field 中出现的位置，文本对齐的方向

• 更复杂的布局 你还可以结合 Grid 提供的 Row、Col，来对表单进行你想要的排列

表单分组

wrapperCol / labelCol

隐藏Label

导出 Label、ErrorMessage 使用

• Label 的 API 详见Label
• ErrorMessage 的 API 详见ErrorMessage

使用 Form.Slot 放置自定义组件

内嵌 Label

使用 helpText、extraText 放置提示信息

使用 InputGroup 组合多个 Field

Modal 弹出层中的表单

配置初始值与校验规则

• 你可以通过rules为每个 Field 表单控件配置校验规则
  Form 内部的校验库基于 async-validator，更多配置规则可查阅其官方文档
• 你可以通过 form 的initValues为整个表单统一设置初始值，也可以在每个 field 中通过initValue设置初始值（后者优先级更高）

自定义校验(Form 级别)

同步校验

异步校验

自定义校验(Field 级别)

表单联动

动态表单

动态删减表单项

数组类动态增删表单项-使用 ArrayField

Hooks 的使用

useFormApi

useFormState

useFieldApi

useFieldState

HOC 的使用

HOC-withFormApi

HOC-withFormState

withField 封装自定义表单控件

• 负责接管组件的 value（或者 valueKey 指定的其他属性）、onChange（或 onKeyChangeFnName 指定的其他回调函数）
• 负责在表单控件上方插入 Field 的<Form.Label>
• 负责在表单控件下方插入 Field 的<ErrorMessage>
• 负责在表单控件下方插入 Field 的 extraText

API 参考

Form Props

FormState

如何访问 formState

• 通过调用 formApi.getFormState()
• 通过child render function 方式声明表单，formState 会作为参数注入
• 通过render props 方式声明表单，formState 会作为参数注入
• 通过useFormState hook
• 通过withFormState HOC

FormApi

如何获取 formApi

• Form 组件在 ComponentDidMount 阶段，会执行 props 传入的 getFormApi 回调，你可以在回调函数中保存 formApi 的引用，以便后续进行调用(示例如下代码)
  除此之外，我们还提供了其他方式获取 formApi，你可以根据喜好选择不同的调用方式
• 通过ref的方式获取Form组件实例，直接访问实例上的formApi
• 通过child render function 方式声明表单，formApi 会作为参数注入
• 通过render props 方式声明表单，formApi 会作为参数注入
• 通过useFormApi hook
• 通过withFormApi HOC

Field Props

Form.Section

Form.Label

Form.Slot

Form.Slot 在 v0.27.0 开始提供

Form.ErrorMessage

Form.ErrorMessage 在 v0.27.0 开始提供

• 当 error 为 ReactNode、String、boolean 时，直接渲染
• 当 error 为数组时，会自动执行 join 操作聚合数组内的错误信息

withFieldOption

Accessibility

ARIA

• aria-labelledby、for
  • Field 组件，会自动添加 label DOM。label 的 for 属性与 props.id 或 props.name 或 props.field 相同 ；label 的id 属性由 props.id 或 props.name 或 props.field 决定，值格式为 ${props.field}-label;
  • 当 Form 或者 Field 的 props.labelPosition 设置为 inset时，此时不存在 label 标签，而是 div 标签。insetLabel 对应的 div 标签会被自动追加 id，值与上述 label 的 id 相同，对应 Field 组件的 aria-labelledby
  • Field 组件会被自动追加 aria-labelledby，值与上述 label 的id 相同
• aria-required
  • 当 Field 配置了必填时（即 props.rules中包含 require: true 或 props.label配置了required: true），Field 组件会被自动追加 aria-required = true（Form.Switch、Form.CheckboxGroup 除外）
• aria-invalid 、aria-errormessage
  • 当 Field 校验未通过时，Field 组件会被自动添加 aria-invalid = true 属性，Form.CheckboxGroup 除外。
  • 当 Field 校验未通过时，Field 组件会被自动追加 aria-errormessage 属性，值为 errorMessage 所对应DOM元素的 id （格式: ${props.field}-errormessage），Form.CheckboxGroup 除外。
• aria-describedby
  • 当 Field 配置了 helpText 或 extraText 时，Field 组件会被自动添加 aria-describedby 属性，值为 helpText、extraText 所对应DOM元素的 id （格式：${props.field}-helpText 、${props.field}-extraText）

设计变量

FAQ

• 为什么我声明了表单，对值进行了修改，数据没有自动映射到 formState.values 中？
  请检查是否正确传入了 field，Field 上的field属性是必填项！！！
• 为什么传入了 defaultValue、defaultChecked 不生效？
  请参考文档开头表单控件，Form.Field 组件对默认值做了统一处理，你应该使用initValue或者initValues来传入默认值
• 为什么异步更新了 initValue、initValues 后，组件没有发生变化，值没有生效？
  initValue、initValues只在 Field、Form mounted 时进行消费，后续做的异步更新并不会起效。
  如果你的初始值需要从远程取，那么你可以在获取到值之后，使用formApi.setValue/setValues进行更新。
  或者直接给 Form、Field 传入一个新的key强制它重新挂载
• 为什么调用了 formApi.setValues 更新 fields 的值，但是实际渲染并没有更新？
  setValues 默认情况下对尚未存在的 field 进行赋值不会生效。如果你的 fields 是动态加载的话，请检查在 setValues 时，该 field 是否已 mounted。
  如有需要，可以使用 override 模式 formApi.setValues(newValue, { isOverride: true })
• 为什么 rules 中的 validator 校验失败，但是对应的错误信息没有被展示？
  async-validator 的自定义 validator 返回值必须是 boolean 类型，否则它不执行任何回调，semi 后续的钩子也不会被调用。建议通过加 !! 或者 Boolean() 强制转换返回类型
• 为什么 getValues 拿不到某个 field？
  field 没有初始值的话，getValues 获取不到这一项。可以设置 initValues/initValue 或者给 form 设置 allowEmpty 属性。
• 🔍 🧾 更多Form FAQ补充 & 问题自查手册