Form 表单

01 组件类型

基础表单

在 Stackblitz 中打开

在 Stackblitz 中打开

Form Props

名称	类型	默认值	描述	必传
colon	Boolean	false	是否在表单标签字段右侧显示冒号	N
contentAlign	String	left	表单内容对齐方式：左对齐、右对齐。可选项：left/right	N
data	Object	{}	表单数据。TS 类型：`FormData`	N
disabled	Boolean	undefined	是否禁用整个表单	N
errorMessage	Object	-	表单错误信息配置，示例：`{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }`。TS 类型：`FormErrorMessage`	N
labelAlign	String	right	表单字段标签对齐方式：左对齐、右对齐、顶部对齐。可选项：left/right/top	N
labelWidth	String / Number	'81px'	可以整体设置label标签宽度，默认为81px	N
preventSubmitDefault	Boolean	true	是否阻止表单提交默认事件（表单提交默认事件会刷新页面），设置为 `true` 可以避免刷新	N
requiredMark	Boolean	undefined	是否显示必填符号（*），默认显示	N
resetType	String	empty	重置表单的方式，值为 empty 表示重置表单为空，值为 initial 表示重置表单数据为初始值。可选项：empty/initial	N
rules	Object	-	表单字段校验规则。TS 类型：`FormRules<FormData>` `type FormRules<T extends Data> = { [field in keyof T]?: Array<FormRule> }`。详细类型定义	N
scrollToFirstError	String	-	表单校验不通过时，是否自动滚动到第一个校验不通过的字段，平滑滚动或是瞬间直达。值为空则表示不滚动。可选项：''/smooth/auto	N
showErrorMessage	Boolean	true	校验不通过时，是否显示错误提示信息，统一控制全部表单项。如果希望控制单个表单项，请给 FormItem 设置该属性	N
submitWithWarningMessage	Boolean	false	【讨论中】当校验结果只有告警信息时，是否触发 `submit` 提交事件	N
onReset	Function		TS 类型：`(context: { e?: FormResetEvent }) => void` 表单重置时触发	N
onSubmit	Function		TS 类型：`(context: SubmitContext<FormData>) => void` 表单提交时触发。其中 `context.validateResult` 表示校验结果，`context.firstError` 表示校验不通过的第一个规则提醒。`context.validateResult` 值为 `true` 表示校验通过；如果校验不通过，`context.validateResult` 值为校验结果列表。【注意】⚠️ 默认情况，输入框按下 Enter 键会自动触发提交事件，如果希望禁用这个默认行为，可以给输入框添加 enter 事件，并在事件中设置 `e.preventDefault()`。详细类型定义。 `interface SubmitContext<T extends Data = Data> { e?: FormSubmitEvent; validateResult: FormValidateResult<T>; firstError?: string; fields?: any }` `type FormValidateResult<T> = boolean \\| ValidateResultObj<T>` `type ValidateResultObj<T> = { [key in keyof T]: boolean \\| ValidateResultList }` `type ValidateResultList = Array<AllValidateResult>` `type AllValidateResult = CustomValidateObj \\| ValidateResultType` `interface ValidateResultType extends FormRule { result: boolean }` `type ValidateResult<T> = { [key in keyof T]: boolean \\| ErrorList }` `type ErrorList = Array<FormRule>`	N
onValidate	Function		TS 类型：`(result: ValidateResultContext<FormData>) => void` 校验结束后触发，result 值为 true 表示校验通过；如果校验不通过，result 值为校验结果列表。详细类型定义。 `type ValidateResultContext<T extends Data> = Omit<SubmitContext<T>, 'e'>`	N

Form Events

名称	参数	描述
reset	`(context: { e?: FormResetEvent })`	表单重置时触发
submit	`(context: SubmitContext<FormData>)`	表单提交时触发。其中 `context.validateResult` 表示校验结果，`context.firstError` 表示校验不通过的第一个规则提醒。`context.validateResult` 值为 `true` 表示校验通过；如果校验不通过，`context.validateResult` 值为校验结果列表。【注意】⚠️ 默认情况，输入框按下 Enter 键会自动触发提交事件，如果希望禁用这个默认行为，可以给输入框添加 enter 事件，并在事件中设置 `e.preventDefault()`。详细类型定义。 `interface SubmitContext<T extends Data = Data> { e?: FormSubmitEvent; validateResult: FormValidateResult<T>; firstError?: string; fields?: any }` `type FormValidateResult<T> = boolean \\| ValidateResultObj<T>` `type ValidateResultObj<T> = { [key in keyof T]: boolean \\| ValidateResultList }` `type ValidateResultList = Array<AllValidateResult>` `type AllValidateResult = CustomValidateObj \\| ValidateResultType` `interface ValidateResultType extends FormRule { result: boolean }` `type ValidateResult<T> = { [key in keyof T]: boolean \\| ErrorList }` `type ErrorList = Array<FormRule>`
validate	`(result: ValidateResultContext<FormData>)`	校验结束后触发，result 值为 true 表示校验通过；如果校验不通过，result 值为校验结果列表。详细类型定义。 `type ValidateResultContext<T extends Data> = Omit<SubmitContext<T>, 'e'>`

FormInstanceFunctions 组件实例方法

名称	参数	返回值	描述
clearValidate	`(fields?: Array<keyof FormData>)`	-	必需。清空校验结果。可使用 fields 指定清除部分字段的校验结果，fields 值为空则表示清除所有字段校验结果。清除邮箱校验结果示例：`clearValidate(['email'])`
reset	`(params?: FormResetParams<FormData>)`	-	必需。重置表单，表单里面没有重置按钮`<button type=\"reset\" />`时可以使用该方法，默认重置全部字段为空，该方法会触发 `reset` 事件。如果表单属性 `resetType='empty'` 或者 `reset.type='empty'` 会重置为空；如果表单属性 `resetType='initial'` 或者 `reset.type='initial'` 会重置为表单初始值。 `reset.fields` 用于设置具体重置哪些字段，示例：`reset({ type: 'initial', fields: ['name', 'age'] })`。详细类型定义。 `interface FormResetParams<FormData> { type?: 'initial' \\| 'empty'; fields?: Array<keyof FormData> }`
setValidateMessage	`(message: FormValidateMessage<FormData>)`	-	必需。设置自定义校验结果，如远程校验信息直接呈现。注意需要在组件挂载结束后使用该方法。`FormData` 指表单数据泛型。详细类型定义。 `type FormValidateMessage<FormData> = { [field in keyof FormData]: FormItemValidateMessage[] }` `interface FormItemValidateMessage { type: 'warning' \\| 'error'; message: string }`
submit	`(params?: { showErrorMessage?: boolean })`	-	必需。提交表单，表单里面没有提交按钮`<button type=\"submit\" />`时可以使用该方法。`showErrorMessage` 表示是否在提交校验不通过时显示校验不通过的原因，默认显示。该方法会触发 `submit` 事件
validate	`(params?: FormValidateParams)`	`Promise<FormValidateResult<FormData>>`	必需。校验函数，包含错误文本提示等功能。泛型 `FormData` 表示表单数据 TS 类型。【关于参数】`params.fields` 表示校验字段，如果设置了 `fields`，本次校验将仅对这些字段进行校验。`params.trigger` 表示本次触发校验的范围，'params.trigger = blur' 表示只触发校验规则设定为 trigger='blur' 的字段，'params.trigger = change' 表示只触发校验规则设定为 trigger='change' 的字段，默认触发全范围校验。`params.showErrorMessage` 表示校验结束后是否显示错误文本提示，默认显示。【关于返回值】返回值为 true 表示校验通过；如果校验不通过，返回值为校验结果列表。详细类型定义。 `interface FormValidateParams { fields?: Array<string>; showErrorMessage?: boolean; trigger?: ValidateTriggerType }` `type ValidateTriggerType = 'blur' \\| 'change' \\| 'all'`
validateOnly	`(params?: Pick<FormValidateParams, 'fields' \\| 'trigger'>)`	`Promise<FormValidateResult<FormData>>`	必需。纯净的校验函数，仅返回校验结果，不对组件进行任何操作。泛型 `FormData` 表示表单数据 TS 类型。参数和返回值含义同 `validate` 方法

FormItem Props

名称	类型	默认值	描述	必传
arrow	Boolean	false	是否显示右侧箭头	N
contentAlign	String	left	表单内容对齐方式：左对齐、右对齐。可选项：left/right	N
for	String	-	label 原生属性	N
help	String / Slot / Function	-	表单项说明内容。TS 类型：`string \\| TNode`。通用类型定义	N
label	String / Slot / Function	''	字段标签名称。TS 类型：`string \\| TNode`。通用类型定义	N
labelAlign	String	-	表单字段标签对齐方式：左对齐、右对齐、顶部对齐。默认使用 Form 的对齐方式，优先级高于 Form.labelAlign。可选项：left/right/top	N
labelWidth	String / Number	-	可以整体设置标签宽度，优先级高于 Form.labelWidth	N
name	String / Number	-	表单字段名称。TS 类型：`string \\| number`	N
requiredMark	Boolean	undefined	是否显示必填符号（*），优先级高于 Form.requiredMark	N
rules	Array	-	表单字段校验规则。TS 类型：`Array<FormRule>`	N
showErrorMessage	Boolean	undefined	校验不通过时，是否显示错误提示信息，优先级高于 `Form.showErrorMessage`	N

FormRule

名称	类型	默认值	描述	必传
boolean	Boolean	-	内置校验方法，校验值类型是否为布尔类型，示例：`{ boolean: true, message: '数据类型必须是布尔类型' }`	N
date	Boolean / Object	-	内置校验方法，校验值是否为日期格式，参数文档，示例：`{ date: { delimiters: '-' }, message: '日期分隔线必须是短横线（-）' }`。TS 类型：`boolean \\| IsDateOptions` `interface IsDateOptions { format: string; strictMode: boolean; delimiters: string[] }`。详细类型定义	N
email	Boolean / Object	-	内置校验方法，校验值是否为邮件格式，参数文档，示例：`{ email: { ignore_max_length: true }, message: '请输入正确的邮箱地址' }`。TS 类型：`boolean \\| IsEmailOptions` `import { IsEmailOptions } from 'validator/es/lib/isEmail'`。详细类型定义	N
enum	Array	-	内置校验方法，校验值是否属于枚举值中的值。示例：`{ enum: ['primary', 'info', 'warning'], message: '值只能是 primary/info/warning 中的一种' }`。TS 类型：`Array<string>`	N
idcard	Boolean	-	内置校验方法，校验值是否为身份证号码，组件校验正则为 `/^(\\d{18,18}\\|\\d{15,15}\\|\\d{17,17}x)$/i`，示例：`{ idcard: true, message: '请输入正确的身份证号码' }`	N
len	Number / Boolean	-	内置校验方法，校验值固定长度，如：len: 10 表示值的字符长度只能等于 10 ，中文表示 2 个字符，英文为 1 个字符。示例：`{ len: 10, message: '内容长度不对' }`。如果希望字母和中文都是同样的长度，示例：`{ validator: (val) => val.length === 10, message: '内容文本长度只能是 10 个字' }`	N
max	Number / Boolean	-	内置校验方法，校验值最大长度，如：max: 100 表示值最多不能超过 100 个字符，中文表示 2 个字符，英文为 1 个字符。示例：`{ max: 10, message: '内容超出' }`。如果希望字母和中文都是同样的长度，示例：`{ validator: (val) => val.length <= 10, message: '内容文本长度不能超过 10 个字' }` 如果数据类型数字（Number），则自动变为数字大小的比对	N
message	String	-	校验未通过时呈现的错误信息，值为空则不显示	N
min	Number / Boolean	-	内置校验方法，校验值最小长度，如：min: 10 表示值最多不能少于 10 个字符，中文表示 2 个字符，英文为 1 个字符。示例：`{ min: 10, message: '内容长度不够' }`。如果希望字母和中文都是同样的长度，示例：`{ validator: (val) => val.length >= 10, message: '内容文本长度至少为 10 个字' }`。如果数据类型数字（Number），则自动变为数字大小的比对	N
number	Boolean	-	内置校验方法，校验值是否为数字（1.2 、 1e5 都算数字），示例：`{ number: true, message: '请输入数字' }`	N
pattern	Object	-	内置校验方法，校验值是否符合正则表达式匹配结果，示例：`{ pattern: /@qq.com/, message: '请输入 QQ 邮箱' }`。TS 类型：`RegExp`	N
required	Boolean	-	内置校验方法，校验值是否已经填写。该值为 true，默认显示必填标记，可通过设置 `requiredMark: false` 隐藏必填标记	N
telnumber	Boolean	-	内置校验方法，校验值是否为手机号码，校验正则为 `/^1[3-9]\d{9}$/`，示例：`{ telnumber: true, message: '请输入正确的手机号码' }`	N
trigger	String	change	校验触发方式。可选项：change/blur	N
type	String	error	校验未通过时呈现的错误信息类型，有告警信息提示和错误信息提示等两种。可选项：error/warning	N
url	Boolean / Object	-	内置校验方法，校验值是否为网络链接地址，参数文档，示例：`{ url: { protocols: ['http','https','ftp'] }, message: '请输入正确的 Url 地址' }`。TS 类型：`boolean \\| IsURLOptions` `import { IsURLOptions } from 'validator/es/lib/isURL'`。详细类型定义	N
validator	Function	-	自定义校验规则，示例：`{ validator: (val) => val.length > 0, message: '请输入内容'}`。TS 类型：`CustomValidator` `type CustomValidator = (val: ValueType) => CustomValidateResolveType \\| Promise<CustomValidateResolveType>` `type CustomValidateResolveType = boolean \\| CustomValidateObj` `interface CustomValidateObj { result: boolean; message: string; type?: 'error' \\| 'warning' \\| 'success' }` `type ValueType = any`。详细类型定义	N
whitespace	Boolean	-	内置校验方法，校验值是否为空格。示例：`{ whitespace: true, message: '值不能为空' }`	N

FormErrorMessage

名称	类型	默认值	描述	必传
boolean	String	-	布尔类型校验不通过时的表单项显示文案，全局配置默认是：`'${name}数据类型必须是布尔类型'`	N
date	String	-	日期校验规则不通过时的表单项显示文案，全局配置默认是：`'请输入正确的${name}'`	N
enum	String	-	枚举值校验规则不通过时的表单项显示文案，全局配置默认是：`${name}只能是${validate}等`	N
idcard	String	-	身份证号码校验不通过时的表单项显示文案，全局配置默认是：`'请输入正确的${name}'`	N
len	String	-	值长度校验不通过时的表单项显示文案，全局配置默认是：`'${name}字符长度必须是 ${validate}'`	N
max	String	-	值的长度太长或值本身太大时，校验不通过的表单项显示文案，全局配置默认是：`'${name}字符长度不能超过 ${validate} 个字符，一个中文等于两个字符'`	N
min	String	-	值的长度太短或值本身太小时，校验不通过的表单项显示文案，全局配置默认是：`'${name}字符长度不能少于 ${validate} 个字符，一个中文等于两个字符'`	N
number	String	-	数字类型校验不通过时的表单项显示文案，全局配置默认是：`'${name}必须是数字'`	N
pattern	String	-	正则表达式校验不通过时的表单项显示文案，全局配置默认是：`'请输入正确的${name}'`	N
required	String	-	没有填写必填项时的表单项显示文案，全局配置默认是：`'${name}必填'`	N
telnumber	String	-	手机号号码校验不通过时的表单项显示文案，全局配置默认是：`'请输入正确的${name}'`	N
url	String	-	链接校验规则不通过时的表单项显示文案，全局配置默认是：`'请输入正确的${name}'`	N
validator	String	-	自定义校验规则校验不通过时的表单项显示文案，全局配置默认是：'${name}不符合要求'	N

Web 桌面端

Vue Stable Version：undefined

Vue Next Stable Version：undefined

React Stable Version：undefined

Mobile 移动端

Vue Next Stable Version：alpha

React Alpha Version：alpha

Flutter Alpha Version：alpha

微信小程序 Stable Version：alpha

QQ 小程序 Alpha Version：alpha