Form 表单
由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据。
基础用法
包含各种布局、尺寸和基本的必填验证。
基础用法
典型表单
包含多种类型的表单域，展示复杂的交互与联动校验。
典型表单
行内表单
设置 layout="inline" 可以让表单项在一行内水平排列。Label 与 Input 已通过 Flex 布局实现了精准的垂直居中对齐。
行内表单
栅格布局
利用内置的 24 栅格系统，可以轻松实现复杂的表单自适应布局。
栅格布局
校验反馈
设置 status-icon 后，在输入框、选择器等组件上会显示校验结果图标。
校验图标
嵌套字段
支持嵌套对象路径配置，如 user.info.name。
嵌套属性
Schema 驱动 (动态表单)
通过 schema 配置驱动表单渲染，支持分组、栅格、异步数据、联动显隐、自定义插槽等完整特性。
校验说明
required: true会自动在校验规则中补充必填约束。对于 Switch (布尔值) 等组件，建议直接在rules中配置validator以实现精准逻辑，避免简写属性导致的提示冲突。rules数组可精细配置正则、长度、自定义函数等校验逻辑。formRef.validate()会触发所有已注册字段的完整校验。
基础 Schema
配置 schema 数组即可生成表单，支持 required 简写和 footer 插槽绑定 formRef.validate() 进行表单校验。
Schema 基本用法
高级 Schema (异步/联动/折叠/Tooltip)
asyncOptions 异步加载选项（自动注入 loading），props 函数联动字段状态，collapsible 可折叠分组，tooltip 字段提示文案。
高级特性
字段类型扩展 (divider / text / list / render)
type: 'divider'：插入分隔线，可配置标题type: 'text'：只读展示字段值，支持emptyValue自定义空态占位符（默认'-'）type: 'list'：动态增减列表，通过listSchema定义子字段结构，listProps控制增删行为render：函数式自定义渲染，返回 VNode
字段类型扩展（divider / text / emptyValue / render）
动态增减列表 (type: 'list')
配置 type: 'list' 实现"联系人"等动态增减场景。listProps.max/min 约束可增删项数上下限，超限时按钮自动禁用。列表行内子字段完整支持所有 FormSchemaItem 配置（分列栅格、联动 props、校验 rules 等），校验路径会自动拼接为 contacts.0.name。
动态增减列表
滚动偏移 (scroll-to-error-offset)
在带有固定顶部导航栏的页面中，校验失败后滚动到第一个错误项时，可能会被 sticky 头部遮挡。配置 scroll-to-error-offset 即可设置顶部偏移量（单位 px）：
以下为一个超长表单。当您滚动到底部点击提交时，由于部分必填项未填，页面会平滑回滚至第一个报错字段。得益于
scroll-to-error-offset="64" 配置，该报错字段不会被浏览器顶部遮挡。 滚动偏移
在 Nuxt 中使用
Form 组件及其子组件（FormItem, FormSchema）完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，所有表单组件均会自动导入。
Nuxt 中使用
SSR 注意事项：
- ✅ 表单布局（水平、垂直、行内）在 SSR 中完全保持一致
- ✅ 校验错误状态（is-error）及错误信息支持服务端渲染
- ✅ 静态验证规则在服务器端即可生效（首屏即有错误样式）
- ⚠️ 提交验证（validate 方法）及动态异步验证仅在客户端激活后可用
- 💡 建议在 Nuxt 页面中使用
reactive定义表单模型以保持响应式连贯
SSR 安全性
Form 组件生成的内部 ID 和 ARIA 属性均基于 useId，确保了在高度嵌套的表单结构中，服务端和客户端的 HTML 关联完全一致，不会触发水合警告。
API
Form Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model | 表单数据对象 | object | — |
| rules | 表单验证规则 | object | — |
| label-width | 标签宽度 | string | number | — |
| label-position | 标签位置 | 'left' | 'right' | 'top' | 'right' |
| layout | 布局模式 | 'horizontal' | 'vertical' | 'inline' | 'horizontal' |
| disabled | 是否禁用表单全部组件 | boolean | false |
| size | 统一尺寸 | 'large' | 'default' | 'small' | 'default' |
| status-icon | 是否在输入框中显示校验结果反馈图标 | boolean | false |
| scroll-to-error | 校验失败时是否滚动到第一个错误项 | boolean | false |
| scroll-into-view-options | 滚动配置项 | object | boolean | { behavior: 'smooth', block: 'center' } |
| scroll-to-error-offset | 滚动到错误项的顶部偏移 (px)，防止被固定头遮挡 | number | 0 |
Form Methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| validate | 验证表单，支持只校验部分规则 | (props?: string | string[], callback?: Function) |
| resetFields | 重置表单，支持只重置部分字段 | (props?: string | string[]) |
| clearValidate | 移除表单项的校验结果 | (props?: string | string[]) |
| scrollToField | 滚动到指定字段 | (prop: string) |
FormItem Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| prop | 表单域 model 字段，支持嵌套路径 (a.b.c) | string | — |
| label | 标签文本 | string | — |
| label-width | 标签宽度 | string | number | — |
| required | 是否必填 | boolean | false |
| rules | 验证规则 | object | array | — |
| size | 给表单项配置尺寸（覆盖 Form 的设置） | 'large' | 'default' | 'small' | — |
| error-position | 错误信息对齐方式 | 'left' | 'center' | 'right' | 'left' |
| show-message | 是否显示校验错误信息 | boolean | true |
| disabled | 禁用当前项（覆盖 Form 的设置） | boolean | false |
FormSchema Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 绑定值（v-model） | object | — |
| schema | 表单配置项，支持普通项和分组 | array | [] |
| formProps | 透传给 YhForm 的属性（同 Form Props） | object | {} |
| gutter | 栅格列间距（px） | number | 20 |
FormSchema Methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| validate | 触发表单校验，支持指定字段 | (fields?: string | string[], callback?: Function) |
| resetFields | 重置字段值和校验状态，支持指定字段 | (fields?: string | string[]) |
| clearValidate | 清除校验结果，支持指定字段 | (fields?: string | string[]) |
| scrollToField | 滚动到指定字段 | (field: string) |
| getModel | 获取当前表单数据快照 | () => Record<string, unknown> |
| setFieldValue | 动态更新单个字段值 | (field: string, value: unknown) |
FormSchema Slots
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
field-{fieldName} | 自定义某字段的完整渲染 | { model, item, handleUpdate } |
label-{fieldName} | 自定义某字段的标签渲染 | { model, item } |
footer | 表单底部操作区 | { model, formRef } |
field-{listField}-{subField} | list 类型行内自定义子字段渲染 | { row, index, item } |
list-footer-{listField} | list 类型列表底部（添加按钮后方） | { model, item } |
FormSchemaItem (配置项)
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| field | 字段名，支持嵌套路径 (a.b.c) | string | — |
| label | 标签名 | string | — |
| type | 字段类型：'default' 普通，'divider' 分隔线，'text' 只读展示，'list' 动态列表 | 'default' | 'divider' | 'text' | 'list' | 'default' |
| component | 组件名 (input, radio, select, switch 等) 或 Vue 组件对象 | string | Component | — |
| col | 栅格占位 (1-24) | number | 24 |
| props | 透传给内部组件的属性，支持函数式联动 | object | (model) => object | — |
| formItemProps | 透传给 form-item 的属性 | object | — |
| required | 是否必填（自动添加必填规则，无需手动写 rules） | boolean | false |
| rules | 校验规则（与 required 合并生效） | FormRule | FormRule[] | — |
| disabled | 是否禁用（支持函数式联动） | boolean | (model) => boolean | — |
| hidden | 是否隐藏（支持函数式联动） | boolean | (model) => boolean | false |
| defaultValue | 字段默认值（在该字段值为 undefined 时自动填入） | unknown | — |
| tooltip | 字段 Label 旁显示的提示文案 | string | — |
| slots | 组件内部插槽配置（key 为插槽名，value 为组件对象） | object | — |
| render | 自定义渲染函数（优先级低于 field-{name} 具名插槽） | (model) => VNode | Component | — |
| asyncOptions | 异步选项加载函数（自动注入 loading 状态） | () => Promise<object[]> | — |
| optionProp | 接收异步选项数据的 prop 名 | string | 'options' |
| emptyValue | type: 'text' 时值为空时的占位文本 | string | '-' |
| listSchema | type: 'list' 时的子字段 schema 配置 | FormSchemaItem[] | — |
| listProps | type: 'list' 时的操作控制，含 max/min/addButtonText/allowAdd/allowDelete | object | — |
FormSchemaGroup (分组配置)
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 分组标题 | string | — |
| items | 分组内的表单项 | FormSchemaItem[] | [] |
| props | 透传给 fieldset 的属性 | object | — |
| collapsible | 是否开启折叠功能 | boolean | false |
| collapsed | 默认折叠状态 | boolean | false |