Form

表单(Form)

• 按需重绘，避免不必要的全量渲染，性能更高。
• 简单易用，结构极简，避免不必要的层级嵌套。
• 完善的无障碍支持。
• 在 Form 外部可方便地获取 formState / fieldState，并提供在外部对表单内部进行操作的方法：formApi / fieldApi。
• 支持将自定义组件封装成表单控件（通过带参 snippet 接入你自己的控件）。
• 支持 Form level / Field level 级别的赋值、校验（同步 / 异步）。

表单控件(Field)

本库将所有自带的输入控件（文本输入框、下拉选择、复选框、单选框等）都用 Field 封装了一次，接管了它们的数据流（value & onChange）。使用时需要从 Form 中导出（注意：从 Form 导出的控件才具有数据同步功能）。

目前 Form 提供了如下表单控件：Input、InputNumber、TextArea、Select、Checkbox、CheckboxGroup、Radio、RadioGroup、Switch、DatePicker、TimePicker、Slider、InputGroup、TreeSelect、Cascader、Rating、AutoComplete、Upload、PinCode、Label、ErrorMessage、Section、Slot，都挂载在 Form 下，直接以 <Form.Input>、<Form.Select> 声明即可。

Field 级别组件的 value、onChange 属性都会被 Form 劫持，所以：

代码演示

声明表单的多种写法

本库 Form 同时支持多种写法。

基本写法

从 Form 中导出表单控件，给表单控件添加 field 属性，将其放置于 Form 内部即可
还可以给每个表单控件设置 label 属性，不传入时默认与 field 相同
label 可以直接传入字符串，亦可以以 object 方式声明，配置 extra、required、optional 等属性应对更复杂的场景

支持的其他写法

当你需要在 Form 结构内部直接获取到 formState、formApi、values 等值时，你还可以使用以下的写法。这三种写法在 Semi（React）里是 render props / child render function / props.component 三个不同入口，在本库（Svelte）中统一用带参 snippet 表达，入参均为 { formState, values, formApi }（对齐 Semi FormFCChild）。

通过 render 属性传入

即 render props：把声明控件的带参 snippet 传给 Form 的 render 属性。

通过 child render function

Form 的 children 是一个带参 snippet，return 出所有表单控件。

通过 props.component

通过 component 属性直接将整个内部结构以带参 snippet 传入。

已支持的表单控件

表单控件值的绑定

每个表单控件都需要以 field 属性绑定一个字段名称，用于将表单项的值正确映射到 FormState 的 values / errors / touched 中。
字段可以是简单的字符串，也可以是包含 . 或者 [] 的字符串，支持多级嵌套。
下面是字段名称以及它们在 FormState 中映射路径的示例：

带参 snippet 可实时映射 formState.values。

表单布局

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

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

• labelPosition、labelAlign：可通过设置 labelPosition（top / left / inset）、labelAlign（left / right）控制 label 在 Field 中出现的位置，文本对齐的方向。

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

wrapperCol / labelCol

需要为 Form 内的所有 Field 设置统一的布局时，可以在 Form 上设置 wrapperCol、labelCol 快速生成布局，无需手动使用 Row、Col 摆放。wrapperCol、labelCol 属性配置参考 Col 组件。

表单分组

Form.Section 把字段按语义分区，带分区标题（仅影响布局，不影响数据结构）。

隐藏 Label

当你不需要自动添加 label 时，可将 noLabel 置为 true（保留 ErrorMessage）；
pure 连 wrapper 也不插，样式、DOM 结构与原始控件保持一致。

内嵌 Label

labelPosition='inset' 把 Label 内嵌在控件内部左侧（Input / InputNumber / DatePicker / TimePicker / Select / TreeSelect / Cascader / TagInput 支持）。

导出 Label、ErrorMessage 使用

如果你需要 Form.Label、Form.ErrorMessage 模块自行组合使用，可以从 Form 中导出。
例如：当自带的 Label、ErrorMessage 布局不满足业务需求，需要自行组合位置，但又希望能直接使用它们的默认样式时。

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

当你的自定义组件需要与 Field 组件保持同样的布局样式时，可以通过 Form.Slot 放置你的自定义组件。
在 Form 组件上设置的 labelWidth、labelAlign 会自动作用在 Form.Slot 上。

使用 helpText、extraText 放置提示信息

可以通过 helpText 放置自定义提示信息，与校验信息（error）公用同一区块展示，两者均有值时优先展示校验信息。
可以通过 extraText 放置额外的提示信息，当需要错误信息和提示文案同时出现时可以使用这个配置，常显，位于 helpText / error 后。
当传入 validateStatus 时，优先展示 validateStatus 值对应的 UI 样式；不传入时，以 field 内部校验状态为准。

通过配置 extraTextPosition，你可以控制 extraText 的显示位置，可选值 bottom、middle。例如当你希望将 extraText 提示信息显示在 Label 与 Field 控件中间时。
该属性可在 Form 上统一配置，亦可在每个 Field 上单独配置，同时传入时以 Field 的配置为准。

使用 InputGroup 组合多个 Field

把多个控件组合为一组，仅需一个属于整组的 Label，控件无缝拼接，GroupError 聚合组内错误。

Modal 弹出层中的表单

通过 getFormApi 拿到句柄，在弹窗确认时调用 formApi.validate() 集中校验。

配置初始值与校验规则

initValues 统一设初始值，rules 声明校验规则（基于 async-validator）；
stopValidateWithError 命中首条错误即停。

自定义校验(Form 级别)

你可以给 Form 整体设置自定义校验函数。推荐使用 validator（validateFields 为旧写法，仍保持兼容）。submit 或调用 formApi.validate() 时会进行调用，支持同步与异步。

自定义校验(Field 级别)

你可以指定单个表单控件的自定义校验函数，支持同步、异步校验（通过返回 promise）。

静默校验

当你需要获取校验结果但不想触发 UI 更新时（如不显示错误提示、不设置 touched 状态），可以通过 formApi.validate({ silent: true }) 实现。这在根据校验结果决定是否发起后端请求等场景中非常有用。也可通过 formApi.validate({ fields: ['fieldA'], silent: true }) 对指定字段进行静默校验。

表单联动

你可以通过监听 Field 的 onChange 事件，然后使用 formApi 进行相关修改，来使 Field 之间达到联动。

动态表单

带参 snippet 拿到 formState 后，可按某字段的值条件渲染 / 卸载其他字段，实现动态增删表单项。

默认情况下，当 Field 组件卸载后，其对应的值（value）、校验信息（error）、交互状态（touched）都会被重置。如果你希望 Field 卸载后保留这些状态（例如在条件渲染的场景中），可以使用 keepState 属性。

使用 Form.ArrayField

针对动态增删的数组类表单项，本库提供了 Form.ArrayField 作用域来简化 add / remove 的操作（对齐 Semi ArrayField）。
Form.ArrayField 的 children snippet 暴露 add、remove、addWithInitValue、arrayFields 等 API，用来执行新增行、删除行、新增带初始值的行等操作。

Hooks 的使用

我们提供了 useFormApi、useFormState、useFieldState、getFieldApi、useArrayFieldState，使你在不需要通过 props 传递的情况下，也能在放置于 Form 结构内部的子组件中访问 Form 内部状态数据，以及调用 Form、Field 的相关 api。

{"values":{},"errors":{},"touched":{},"submitting":false,"submitCount":0}

API 参考

Form Props

FormState

FormState 存储了所有 Form 内部的状态值，包括各表单控件的值、错误信息、touched 状态。进行表单提交时，实际提交的就是 formState.values。

如何访问 formState

• 通过 formApi.getFormState()，在 Form 外部也可以获取 formState。
• 通过带参 snippet 声明表单，formState 会作为 snippet 参数注入。
• 通过 useFormState()，在 Form 内部的子组件访问父级 Form 的 formState。

FormApi

FormApi 允许你使用 getter 和 setter 来获取和操作 formState 的值。你在 Form 内部、外部都可以方便地获取到 formApi。

如何获取 formApi

• 通过 Form 的 getFormApi 回调，在回调中保存 formApi 引用。
• 通过外部预建 const form = createForm() 并传入 <Form {form}>（对齐 Semi Form.useForm()，Svelte 中 createForm() 同步返回真 api，父组件立即可调）。
• 通过带参 snippet 声明表单，formApi 会作为 snippet 参数注入。
• 通过 useFormApi()，在 Form 内部的子组件访问父级 Form 的 formApi。

Field Props

Form.ArrayField Props

针对动态增删的数组类表单项，Form.ArrayField 作用域简化 add / remove 操作（对齐 Semi ArrayField）。

children snippet 入参：arrayFields（每行 { key, index, field(sub), remove }，用于 {#each} 渲染，对齐 Semi arrayFields[i].field）、add(index?)（末尾追加 / 指定位置插入空行）、addWithInitValue(rowVal, index?)（追加带初始值的行）、remove(item)、move(from, to)。

无障碍

• 每个 Form.Field 通过 useId 生成 id，Label 用 for={id} 关联；控件 aria-describedby 指向 extraText 和错误文案节点。
• 必填控件加 aria-required="true"；必填星标本身 aria-hidden="true"（避免读屏念”星号”）。
• 校验失败控件加 aria-invalid="true"；错误文案容器使用 role="alert" 或 aria-live="polite"。
• 提交失败后焦点移至首个错误字段（scrollToError + .focus()）；表单不劫持 Tab，保持自然 tab 序。