表单 Form

用于收集信息。

基础使用

Form 用 model 传入表单数据对象，在 rules 中传入校验规则；FormItem 中 field 设置表单项字段，用于表单校验、重置等操作。

FormItem 的 rule 会覆盖 Form 的 rules 中相同 field 的规则定义。

当通过 Form 组件的 validate 方法手动触发表单校验时，组件将忽略 rules 或 rule 上配置的 trigger 条件，对所有存在的 FormItem 执行校验，并在遇到第一条不满足的规则时立即返回校验结果。

此外，需要注意的是，FormItem 的 field 不具有响应式。

Hook 语法

useForm 会返回一个用于操作表单的对象，传入 Form 的 form 中即可。

Form 的 model 和 form 属性必须传入其一。

隐藏源代码

自定义校验

使用 validator 自定义表单校验条件。

隐藏源代码

禁用 & 只读

通过 disabled 设置表单禁用状态，通过 readonly 设置表单只读状态。

表单组件 Form 的 disabled 或 readonly 属性会作用于其内部的所有按钮组件（包括 Button、ButtonGroup）以及各个 FormItem 内部的数据输入组件；而单个 FormItem 的 disabled 或 readonly 属性则仅影响该表单项内部的按钮组件和数据输入组件。

Form、FormItem 和其内部的按钮组和数据输入组件，这两个属性采用"或"逻辑，即任一被设为禁用或只读状态，其子树组件（或其自身）便会相应生效。

隐藏源代码

标签对齐

通过 labelAlign 设置标签对齐方向

隐藏源代码

子元素宽度

通过 labelProps 和 contentProps 修改标签和内容区域的 Col 组件属性。

设置 labelAutoWidth 标签区域宽度会进行自适应，内容区域宽度也会一同变化。

隐藏源代码

表单尺寸

表单有不同的大小。

表单组件 Form 的 size 属性会作用于其内部的所有按钮组件（包括 Button、ButtonGroup）以及各个 FormItem 内部的数据输入组件。

Form、FormItem 内部的按钮组和数据输入组件，size 属性如果没有传入或为 undefined，则设置为与 Form 的 size 属性相同，如果设置，则传入的值优先。

API

useForm

function useForm<T extends Record<string | number, any> = Record<string | number, any>>(options?: {
    initialValues?: T;
}): UseFormReturn<T>

export interface UseFormReturn<
	T extends Record<string | number, any> = Record<string | number, any>
> {
	model: Ref<T>
	validate: (field?: string | string[]) => FormValidateResult
	reset: (field?: string | string[]) => void
	clearValidation: (field?: string | string[]) => void
	register: (registerOptions: UseFormRegisterOptions) => void
}

FormProps

属性	类型	可选	默认值	描述	版本
model	`Record<number \| string, any>`	是		表单数据对象。`form` 和 `model` 必须传入其一。	0.0.3
form	`FormInstance`	是		`useForm` 返回的表单对象，用于以 hook 的形式操作表单。`form` 和 `model` 必须传入其一。	0.0.3
rules	`Record<string, RuleItem \| RuleItem[]>`	是		验证规则。	0.0.3
enterSubmit	`boolean`	是	`false`	是否允许回车提交表单。	0.2.0
disabled	`boolean`	是	`false`	是否禁用。	0.0.3
readonly	`boolean`	是	`false`	是否只读。	0.0.3
size	`'small' \| 'medium' \| 'large'`	是	`'medium'`	表单尺寸。	0.0.3
labelAlign	`'left' \| 'right' \| 'top'`	是	`'right'`	标签的对齐方式。	0.0.3
showAsterisk	`boolean`	是		是否展示星号。	0.0.3
asteriskPlacement	`'left' \| 'right' \| 'end'`	是	`'left'`	星号的位置。	0.0.3
labelAutoWidth	`boolean`	是	`false`	表单项标签宽度自适应。	0.0.3
rowProps	`RowProps & RestAttrs`	是		表单项行容器的属性。	0.0.3
labelProps	`ColProps & RestAttrs`	是		表单项标签列的属性。	0.0.3
contentProps	`ColProps & RestAttrs`	是		表单项内容列的属性。	0.0.3
pollSizeChange	`boolean`	是	`false`	开启轮询组件尺寸变化，会影响子树上组件的按钮组件和数据输入组件的同名属性。	0.1.0

UseFormReturn

属性	类型	可选	描述	版本
model	`Ref<Record<string \| number, any>>`	否	表单数据对象。	0.0.3
validate	`(field?: string \| string[]) => FormValidateResult`	否	手动触发表单验证，无参数时验证所有字段，Form 挂载后方可调用。	0.0.3
reset	`(field?: string \| string[]) => void`	否	手动触发表单重置，无参数时验证所有字段，Form 挂载后方可调用。	0.0.3
clearValidation	`(field?: string \| string[]) => void`	否	清除表单验证状态，无参数时清除所有字段，Form 挂载后方可调用。	0.0.3

FormEvents

事件	参数	描述	版本
submit	`form: Record<number \| string, any>, event: SubmitEvent`	表单触发原生的提交时的回调。	0.0.3
reset	`form: Record<number \| string, any>, event: Event`	表单触发原生的重置时触发的回调。	0.0.3

FormSlots

插槽	参数	描述	版本
default		用于渲染表单项。	0.0.3

FormExpose

属性	类型	可选	描述	版本
validate	`(field?: string \| string[]) => FormValidateResult`	否	手动触发表单验证，无参数时验证所有字段。	0.0.3
reset	`(field?: string \| string[]) => void`	否	手动触发表单重置，无参数时重置所有字段。	0.0.3
clearValidation	`(field?: string \| string[]) => void`	否	清除表单验证状态，无参数时清除所有字段。	0.0.3

RuleItem

属性	类型	可选	默认值	描述	版本
required	`boolean`	是	`false`	是否为必填字段。	0.0.3
message	`string`	是		验证失败时的提示信息，为空字符串时不会触发错误。	0.0.3
trigger	`RuleTrigger \| RuleTrigger[]`	是	`['change', 'blur']`	触发验证的事件。	0.0.3
type	`FieldType \| FieldType[]`	是		字段类型校验。	0.0.3
max	`number`	是		最大值限制，仅对数字值有效。	0.0.3
min	`number`	是		最小值限制，仅对数字值有效。	0.0.3
maxLength	`number`	是		最大长度限制，仅当值为字符串或数组时有效。	0.0.3
minLength	`number`	是		最小长度限制，仅当值为字符串或数组时有效。	0.0.3
email	`boolean`	是	`false`	是否为邮箱地址，仅当值为字符串时有效。	0.0.3
url	`boolean`	是	`false`	是否为 URL，仅当值为字符串时有效。	0.0.3
numberString	`boolean`	是	`false`	是否为数字字符串，仅当值为字符串时有效。	0.0.3
level	`RuleLevel`	是	`'error'`	验证失败的级别，只有 `'error'` 等级才会使表单校验失败。	0.0.3
validator	`(value: any, model: Record<number \| string, any>) => string \| void \| Promise<void \| string>`	是		自定义验证函数，返回错误提示字符串，返回空值则为校验成功。	0.0.3

FormItemProps

属性	类型	可选	默认值	描述	版本
field	`string`	是		关联的表单字段名，支持字段路径的形式，例如 `'user[0].info.name'`。该属性不具有响应式。	0.0.3
label	`string`	是		标签文本。	0.0.3
rule	`RuleItem \| RuleItem[]`	是		验证规则。	0.0.3
disabled	`boolean`	是		是否禁用，和 Form 中的 `disabled` 取或运算决定最终是否禁用。	0.0.3
readonly	`boolean`	是		是否只读，和 Form 中的 `readonly` 取或运算决定最终是否只读。	0.0.3
labelAlign	`'left' \| 'right' \| 'top'`	是		标签的对齐方式。	0.0.3
showAsterisk	`boolean`	是		是否展示星号。	0.0.3
asteriskPlacement	`'left' \| 'right' \| 'end'`	是		星号的位置。	0.0.3
rowProps	`RowProps & RestAttrs`	是		表单项行容器的属性。	0.0.3
labelProps	`ColProps & RestAttrs`	是		表单项标签列的属性。	0.0.3
contentProps	`ColProps & RestAttrs`	是		表单项内容列的属性。	0.0.3
pollSizeChange	`boolean`	是	`false`	开启轮询组件尺寸变化，会影响子树上组件的按钮组件和数据输入组件的同名属性。	0.1.0

FormItemSlots

插槽	参数	描述	版本
tip	`message: string, level: RuleLevel`	验证提示。	0.0.3
extra		额外内容插槽，位于内容区域下方。	0.0.3
label		自定义标签。	0.0.3
default		表单项内容插槽。	0.0.3

RuleLevel, FieldType, RuleTrigger, FormValidateResult

export type RuleLevel = 'error' | 'warning' | 'success' | 'normal'
export type FieldType = 'number' | 'string' | 'boolean' | 'array' | 'dict' | 'function' | 'date'
export type RuleTrigger = 'blur' | 'change' | 'input'

export type FormValidateResult = Promise<{
	isValid: boolean
	results: Record<
		string,
		PromiseSettledResult<{
			message: string
			level: RuleLevel
		}>
	>
}>

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}

表单 Form

基础使用

Hook 语法

自定义校验

禁用 & 只读

Disabled

Readonly

标签对齐

子元素宽度

表单尺寸

API

useForm

FormProps

UseFormReturn

FormEvents

FormSlots

FormExpose

RuleItem

FormItemProps

FormItemSlots

RuleLevel, FieldType, RuleTrigger, FormValidateResult

RestAttrs

表单 Form ​

基础使用 ​

Hook 语法 ​

自定义校验 ​

禁用 & 只读 ​

Disabled

Readonly

标签对齐 ​

子元素宽度 ​

表单尺寸 ​

API ​

useForm ​

FormProps ​

UseFormReturn ​

FormEvents ​

FormSlots ​

FormExpose ​

RuleItem ​

FormItemProps ​

FormItemSlots ​

RuleLevel, FieldType, RuleTrigger, FormValidateResult ​

RestAttrs ​

表单 Form

基础使用

Hook 语法

自定义校验

禁用 & 只读

标签对齐

子元素宽度

表单尺寸

API

useForm

FormProps

UseFormReturn

FormEvents

FormSlots

FormExpose

RuleItem

FormItemProps

FormItemSlots

RuleLevel, FieldType, RuleTrigger, FormValidateResult

RestAttrs