---
url: /components/form.md
---
# Form 表单

> 移动端：标签上置 + 主按钮吸底的表单范式，参见 [移动端 · 数据录入](/mobile/data-entry)。

表单容器与表单项：`model` + `rules`（async-validator 格式）声明式校验，blur / change 时机自动触发，错误信息内联展示，支持 label 位置与宽度、行内布局、尺寸与禁用注入。FormItem 挂载时向 Form 注册（携带 prop），校验与重置按字段管理；`prop` 对应 `model` 中的字段路径，支持 a.b.c 嵌套。

## 基础用法

`prop` 对应 `model` 中的字段路径；规则通过 `trigger: 'blur' | 'change'` 声明校验时机，控件失焦或值变化时自动校验并在字段下方内联展示错误。

## 典型场景：登录表单

中后台表单页的推荐布局：`label-position="right"`（默认）配合固定 `label-width`，标签尾端与输入框对齐、间距一致，视线往返最短；校验时机按控件类型分开声明，文本类字段用 `blur`（输完即验，输入过程不打断）、选择类字段用 `change`（选中即反馈），同一字段的多条规则可各自声明 trigger；错误由 FormItem 在字段下方内联渲染（is-error 红字），占位稳定不引起布局跳动，提交时用 `validate` 统一拦截。

## 综合示例：注册表单

覆盖两种字段类型（输入框 + 下拉选择）；确认密码用自定义 `validator`，async-validator 协议：失败 `callback(new Error('文案'))`，通过 `callback()`，也可返回 `Promise.reject(new Error('文案'))`；提交按钮 `loading` 防重复提交，`validate` 全通过后再发请求，成功后 `resetFields` 还原初始值并清除校验；密码变化时用 `validateField('confirm')` 联动复检确认密码（返回 Promise 失败会 reject，需 catch 静默）。

## 行内表单

`inline` 让表单项横向排列，适合筛选栏：字段少且标签短时可用 `label-position="left"` 让标签左对齐，字段过多换行后布局依旧稳定；`label-width` 与 `label-position` 均可在 FormItem 上单独覆盖。

## 标签位置

`label-position` 三态选型：`right`（默认）是表单页首选，标签与输入框起始位置固定、逐行扫读最快；`left` 适合筛选栏与标签长短不一的工具条，视觉重心平稳；`top` 适合标签文案较长或容器较窄的场景（抽屉、弹窗、移动端），以纵向空间换横向空间。非 top 位置需配合 `label-width` 固定标签宽度。

## 尺寸与禁用

`size` 统一注入表单内全部控件的尺寸，`disabled` 注入禁用态，FormItem 上的同名属性可单独覆盖。

## 手动错误信息与必填星号

FormItem `error` 直接指定错误文案并覆盖校验结果；`required` 只控制必填星号展示，不参与校验；Form `hide-required-asterisk` 全局隐藏星号，`inline-message` 让错误信息行内展示。

## 嵌套字段路径

`prop` 支持 a.b.c 路径，rules 的 key 使用同样的路径字符串，深层对象字段无需拍平；`#label` 插槽可自定义标签内容。

## 表单校验

完整校验流程示例：`rules` 声明 required / type / min / max 等规则（async-validator 格式），blur、change 时机自动触发内联报错；提交前 `validate` 统一校验（回调可拿到失败字段集合），`clearValidate` 只清除报错不动数据，`resetFields` 还原初始值并清报错。

## 提交事件

Form 根元素收口原生 submit：回车或 `native-type="submit"` 按钮触发时自动先跑 `validate`，全部通过触发 `finish`（负载为 model 副本），存在失败触发 `finish-failed`（负载 `values` 与 `errors`），页面不会真实提交；配合 `scroll-to-error` 在失败时自动滚到第一个错误项。任一字段值变化还会触发 `values-change`，负载为本次变化字段的最小集与全量值。

## API