Form 表单

由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据。

基础用法

包含各种布局、尺寸和基本的必填验证。

LargeDefaultSmall

基础用法

典型表单

包含多种类型的表单域，展示复杂的交互与联动校验。

典型表单

行内表单

设置 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 基本用法

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`	`undefined`

FormSchemaGroup (分组配置)

属性名	说明	类型	默认值
title	分组标题	`string`	—
items	分组内的表单项	`FormSchemaItem[]`	`[]`
props	透传给 fieldset 的属性	`object`	—
collapsible	是否开启折叠功能	`boolean`	`false`
collapsed	默认折叠状态	`boolean`	`false`

主题变量

YhForm 和 YhFormItem 支持 themeOverrides。运行时样式主要消费以下组件变量：

变量名	说明	默认值
`--yh-form-item-height`	表单项与对齐控件的基础高度	`32px`
`--yh-form-item-margin-bottom`	表单项底部间距	`22px`
`--yh-form-label-font-size`	表单标签字体大小	`14px`

YhFormSchema 主要复用表单和全局主题令牌，不额外定义独立组件变量。

类型导出

名称	说明
`YhFormProps`	`YhForm` props 类型
`YhFormItemProps`	`YhFormItem` props 类型
`YhFormSchemaProps`	`YhFormSchema` props 类型
`YhFormSchemaItem`	Schema 表单项类型
`YhFormSchemaGroup`	Schema 表单分组类型
`YhFormRule`	单条校验规则类型
`YhFormRules`	表单规则集合类型
`YhFormInstance`	`YhForm` 实例类型
`YhFormItemInstance`	`YhFormItem` 实例类型
`YhFormSchemaInstance`	`YhFormSchema` 实例类型

Form 表单 ​

基础用法 ​

典型表单 ​

行内表单 ​

栅格布局 ​

校验反馈 ​

嵌套字段 ​

Schema 驱动 (动态表单) ​

基础 Schema ​

高级 Schema (异步/联动/折叠/Tooltip) ​

字段类型扩展 (divider / text / list / render) ​

动态增减列表 (type: 'list') ​

滚动偏移 (scroll-to-error-offset) ​

在 Nuxt 中使用 ​

API ​

Form Props ​

Form Methods ​

FormItem Props ​

FormSchema Props ​

FormSchema Methods ​

FormSchema Slots ​

FormSchemaItem (配置项) ​

FormSchemaGroup (分组配置) ​

主题变量 ​

类型导出 ​

Form 表单

基础用法

典型表单

行内表单

栅格布局

校验反馈

嵌套字段

Schema 驱动 (动态表单)

基础 Schema

高级 Schema (异步/联动/折叠/Tooltip)

字段类型扩展 (divider / text / list / render)

动态增减列表 (type: 'list')

滚动偏移 (scroll-to-error-offset)

在 Nuxt 中使用

API

Form Props

Form Methods

FormItem Props

FormSchema Props

FormSchema Methods

FormSchema Slots

FormSchemaItem (配置项)

FormSchemaGroup (分组配置)

主题变量

类型导出