项目正在快速迭代中，API 与视觉细节可能随版本调整，请勿用于生产环境。
双端兼容 · 桌面 + 移动

Form 表单 ​

移动端：标签上置 + 主按钮吸底的表单范式，参见 移动端 · 数据录入。

表单容器与表单项：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 让错误信息行内展示。

地址需以 https:// 开头

嵌套字段路径 ​

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，负载为本次变化字段的最小集与全量值。

留空回车提交体验 finish-failed，填写后提交体验 finish

API ​

Form Props

参数说明类型默认值
model表单数据对象，校验与重置的数据源object{}
rules校验规则（async-validator 格式），key 为字段 propobject{}
labelPositionlabel 位置（item 可覆盖）left | right | topright
labelWidthlabel 宽度（item 可覆盖）string | number空
inline行内布局booleanfalse
disabled禁用注入（全部表单控件）booleanfalse
size控件尺寸注入large | default | small空
showMessage显示校验错误信息booleantrue
inlineMessage错误信息行内展示booleanfalse
statusIcon校验状态图标（预留，当前 FormItem 未消费）booleanfalse
scrollToError校验失败自动滚动到第一个错误项（validate 与原生 submit 链路生效）booleanfalse
hideRequiredAsterisk隐藏必填星号booleanfalse
validateOnRuleChangerules 变化时自动重新校验booleantrue
ripple批量关闭表单内所有输入类组件的激活涟漪动效（组件级 ripple prop 可单独关闭；全局见 setRipple）booleantrue

Form Events

参数说明类型默认值
finish原生 submit（回车或 native-type=submit 按钮）校验全部通过后触发，负载为 model 副本(values: object) => void—
finish-failed原生 submit 校验失败后触发({ values, errors }) => void—
values-change任一字段值变化时触发（change 校验链路收口）(changedValues, allValues) => void—

FormItem Props

参数说明类型默认值
propmodel 字段路径（支持 a.b.c，未设置则不参与整体校验）string空
labellabel 文本string空
labelWidth覆盖 form 的 label 宽度string | number继承 form
labelPosition覆盖 form 的 label 位置left | right | top继承 form
required强制显示必填星号（不参与校验）booleanundefined
rules覆盖 form.rules 中该字段的规则object | arrayundefined
error手动错误信息（覆盖校验结果）string空
showMessage是否显示错误信息boolean继承 form
inlineMessage错误信息行内展示boolean继承 form
size表单项尺寸（向下注入控件）string继承 form

Slots

参数说明类型默认值
defaultForm / FormItem 的控件内容——
label自定义标签内容（仅 FormItem）—label 文本

Form Methods

参数说明类型默认值
validate校验全部字段，全通过 resolve(true)，失败 reject({ prop: message })；也支持回调风格 callback(ok, invalidFields)(callback?) => Promise<boolean>—
validateField校验指定字段（单个 prop 或数组），返回值语义同 validate(props, callback?) => Promise<boolean>—
resetFields重置全部字段为初始值并清除校验() => void—
clearValidate清除校验状态，可传 prop 数组，缺省清全部(props?) => void—
scrollToField平滑滚动到指定字段(prop) => void—
fields已注册的 FormItem 实例列表（含 validateState 等内部状态）array[]

FormItem Methods

参数说明类型默认值
validate触发校验，trigger 可为 blur / change 或空（不过滤），成功 resolve(true)，失败 reject({ prop: message })(trigger?) => Promise<boolean>—
resetField重置为初始值并清除校验() => void—
clearValidate仅清除校验状态() => void—
scrollToField滚动到当前项() => void—
validateState / validateMessage当前校验状态与错误信息（响应式）string / string空