Skip to content

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):

滚动偏移

在 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是否禁用表单全部组件booleanfalse
size统一尺寸'large' | 'default' | 'small''default'
status-icon是否在输入框中显示校验结果反馈图标booleanfalse
scroll-to-error校验失败时是否滚动到第一个错误项booleanfalse
scroll-into-view-options滚动配置项object | boolean{ behavior: 'smooth', block: 'center' }
scroll-to-error-offset滚动到错误项的顶部偏移 (px),防止被固定头遮挡number0

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是否必填booleanfalse
rules验证规则object | array—
size给表单项配置尺寸(覆盖 Form 的设置)'large' | 'default' | 'small'—
error-position错误信息对齐方式'left' | 'center' | 'right''left'
show-message是否显示校验错误信息booleantrue
disabled禁用当前项(覆盖 Form 的设置)booleanfalse

FormSchema Props ​

属性名说明类型默认值
modelValue绑定值(v-model)object—
schema表单配置项,支持普通项和分组array[]
formProps透传给 YhForm 的属性(同 Form Props)object{}
gutter栅格列间距(px)number20

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)number24
props透传给内部组件的属性,支持函数式联动object | (model) => object—
formItemProps透传给 form-item 的属性object—
required是否必填(自动添加必填规则,无需手动写 rules)booleanfalse
rules校验规则(与 required 合并生效)FormRule | FormRule[]—
disabled是否禁用(支持函数式联动)boolean | (model) => boolean—
hidden是否隐藏(支持函数式联动)boolean | (model) => booleanfalse
defaultValue字段默认值(在该字段值为 undefined 时自动填入)unknown—
tooltip字段 Label 旁显示的提示文案string—
slots组件内部插槽配置(key 为插槽名,value 为组件对象)object—
render自定义渲染函数(优先级低于 field-{name} 具名插槽)(model) => VNode | Component—
asyncOptions异步选项加载函数(自动注入 loading 状态)() => Promise<object[]>—
optionProp接收异步选项数据的 prop 名string'options'
emptyValuetype: 'text' 时值为空时的占位文本string'-'
listSchematype: 'list' 时的子字段 schema 配置FormSchemaItem[]—
listPropstype: 'list' 时的操作控制,含 max/min/addButtonText/allowAdd/allowDeleteobjectundefined

FormSchemaGroup (分组配置) ​

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

主题变量 ​

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

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

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

类型导出 ​

名称说明
YhFormPropsYhForm props 类型
YhFormItemPropsYhFormItem props 类型
YhFormSchemaPropsYhFormSchema props 类型
YhFormSchemaItemSchema 表单项类型
YhFormSchemaGroupSchema 表单分组类型
YhFormRule单条校验规则类型
YhFormRules表单规则集合类型
YhFormInstanceYhForm 实例类型
YhFormItemInstanceYhFormItem 实例类型
YhFormSchemaInstanceYhFormSchema 实例类型

Released under the MIT License.