mini-yu/uni_modules/tdesign-uniapp/components/form/README.md

title, description, spline, isComponent, toc

title	description	spline	isComponent	toc
Form 表单	用以收集、校验和提交数据，一般由输入框、单选框、复选框、选择器等控件组成。	base	true	false

引入

可在 main.ts 或在需要使用的页面或组件中引入。

import TForm from '@tdesign/uniapp/form/form.vue';
import TFormItem from '@tdesign/uniapp/form-item/form-item.vue';

01 组件类型

基础表单

{{ horizontal }}

{{ vertical }}

API

Form Props

名称	类型	默认值	描述	必传
custom-style	Object	-	自定义样式	N
colon	Boolean	false	是否在表单标签字段右侧显示冒号	N
content-align	String	left	表单内容对齐方式：左对齐、右对齐。可选项：left/right	N
data	Object	{}	表单数据。TS 类型：FormData	N
disabled	Boolean	undefined	是否禁用整个表单	N
error-message	Object	-	表单错误信息配置，示例：{ idcard: '请输入正确的身份证号码', max: '字符长度不能超过 ${max}' }。TS 类型：FormErrorMessage	N
label-align	String	right	表单字段标签对齐方式：左对齐、右对齐、顶部对齐。可选项：left/right/top	N
label-width	String / Number	'81px'	可以整体设置label标签宽度，默认为81px	N
readonly	Boolean	undefined	是否整个表单只读	N
required-mark	Boolean	undefined	是否显示必填符号（*），默认显示	N
required-mark-position	String	-	表单必填符号（*）显示位置。可选项：left/right	N
reset-type	String	empty	重置表单的方式，值为 empty 表示重置表单为空，值为 initial 表示重置表单数据为初始值。可选项：empty/initial	N
rules	Object	-	表单字段校验规则。TS 类型：FormRules<FormData> type FormRules<T extends Data = any> = { [field in keyof T]?: Array<FormRule> }。详细类型定义	N
scroll-to-first-error	String	-	表单校验不通过时，是否自动滚动到第一个校验不通过的字段，平滑滚动或是瞬间直达。值为空则表示不滚动。可选项：''/smooth/auto	N
show-error-message	Boolean	true	校验不通过时，是否显示错误提示信息，统一控制全部表单项。如果希望控制单个表单项，请给 FormItem 设置该属性	N
submit-with-warning-message	Boolean	false	【讨论中】当校验结果只有告警信息时，是否触发 submit 提交事件	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 组件实例方法

名称	参数	返回值	描述
clear-validate	(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> }
set-validate-message	(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' | 'submit' | 'all'

FormItem Props

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

FormItem Slots

名称	描述
help	自定义 help 显示内容
label	自定义 label 显示内容

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 type { IsEmailOptions } from '../common/common'。详细类型定义	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	String / Object	-	内置校验方法，校验值是否符合正则表达式匹配结果，示例：{ pattern: /@qq.com/, message: '请输入 QQ 邮箱' }。TS 类型：RegExp | string	N
required	Boolean	-	内置校验方法，校验值是否已经填写。该值为 true，默认显示必填标记，可通过设置 requiredMark: false 隐藏必填标记	N
telnumber	Boolean	-	内置校验方法，校验值是否为手机号码，校验正则为 /^1[3-9]\d{9}$/，示例：{ telnumber: true, message: '请输入正确的手机号码' }	N
trigger	String	change	校验触发方式。TS 类型：ValidateTriggerType	N
type	String	error	校验未通过时呈现的错误信息类型，有 告警信息提示 和 错误信息提示 等两种。可选项：error/warning	N
url	Boolean / Object	-	内置校验方法，校验值是否为网络链接地址，参数文档，示例：{ url: { protocols: ['http','https','ftp'] }, message: '请输入正确的 Url 地址' }。TS 类型：boolean | IsURLOptions import type { IsURLOptions } from '../common/common'。详细类型定义	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
whitespace	String	-	值为空格校验不通过时表单项显示文案，全局配置默认是：'${name}不能为空	N

CSS Variables

组件提供了下列 CSS 变量，可用于自定义样式。

名称	默认值	描述
--td-form-bg-color	@bg-color-container	-
--td-form-border-radius	0	-
--td-form-padding	0	-
--td-form-readonly-bg-color	@bg-color-secondarycontainer	-
--td-form-item-horizontal-padding	32rpx	-
--td-form-item-justify-content	space-between	-
--td-form-item-label-width	160rpx	-
--td-form-item-vertical-padding	32rpx	-