Appearance
validate用法
Hidden Title
基础用法:
validate()基础用法
结合sForm组件
高阶用法
不触发校验
提交时校验
说明
validate 用于生成 Element Plus 表单校验规则,也可以在 pureValid=true 时直接返回布尔校验结果。它内置常见校验类型,适合统一维护表单必填、手机号、邮箱、IP、端口、长度、范围、自定义正则等规则。
调用形式
ts
validate()
validate(type)
validate(type, rules)
validate(type, value, true)
validate('custom', { value, reg }, true)
validate({ type, ...rules })
validateOnSubmit(type, rules)validate()
validate(type)
validate(type, rules)
validate(type, value, true)
validate('custom', { value, reg }, true)
validate({ type, ...rules })
validateOnSubmit(type, rules)参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
type | string | object | 否 | 'required' | 校验类型或规则对象。如果不是内置字符串类型,会把 type 当成错误提示文案,返回必填规则。 |
rules | object | string | number | boolean | null | undefined | 否 | {} | 校验配置。type 是对象时,此参数作为 pureValid 使用;pureValid=true 时,部分类型会把它当成待校验值。 |
pureValid | boolean | 否 | false | 是否直接执行校验并返回布尔值。默认返回 Element Plus 规则对象。 |
rules 常用字段:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
message | string | 内置提示 | 校验失败提示文案。 |
min | number | - | between 的最小值,或 length 的最小长度。 |
max | number | - | between 的最大值,或 length 的最大长度。 |
value | any | - | same 对比值,或 custom 纯校验时的待校验值。 |
reg | RegExp | - | custom 自定义正则。 |
required | boolean | true | 是否必填。 |
trigger | Array<'blur' | 'change'> | ['blur', 'change'] | Element Plus 表单触发时机。 |
内置类型
| 类型 | 作用 |
|---|---|
required | 必填校验。 |
change | 选择类必填校验,默认提示文案为 请选择。 |
password | 只能包含英文、数字、下划线、中划线。 |
number / positive | 正整数。 |
zeroPositive | 非负整数,包含 0。 |
integer | 整数,包含负数和 0。 |
decimal | 非负数字,最多 2 位小数。 |
mobile | 11 位手机号。 |
email | 邮箱格式。 |
ip | IPv4 地址。 |
port | 1-65535 端口号。 |
between | 数值范围校验,配合 min、max。 |
length | 字符长度校验,配合 min、max。 |
same | 和 rules.value 保持一致。 |
custom | 使用 rules.reg 自定义正则。 |
返回值
pureValid=false 时返回 Element Plus 表单规则对象;pureValid=true 时返回 boolean。校验规则对象可直接放入 el-form 或 s-form 的 rules 中。
常用场景
ts
rules: {
name: [validate()],
category: [validate('change')],
phone: [validate('mobile', { message: '请输入手机号' })],
email: [validate({ type: 'email', message: '请输入邮箱' })],
age: [validate('between', { min: 1, max: 120 })],
confirmPwd: [validate('same', { value: form.password })],
submitOnly: [validateOnSubmit()],
}
validate('ip', '192.168.1.1', true)
// true
validate('custom', { value: '22.1', reg: /^\d+\.?\d{0,2}$/ }, true)
// truerules: {
name: [validate()],
category: [validate('change')],
phone: [validate('mobile', { message: '请输入手机号' })],
email: [validate({ type: 'email', message: '请输入邮箱' })],
age: [validate('between', { min: 1, max: 120 })],
confirmPwd: [validate('same', { value: form.password })],
submitOnly: [validateOnSubmit()],
}
validate('ip', '192.168.1.1', true)
// true
validate('custom', { value: '22.1', reg: /^\d+\.?\d{0,2}$/ }, true)
// truevalidateOnSubmit
validateOnSubmit(type, rules, pureValid) 是 validate 的快捷包装,会默认合并 trigger: []。适合只希望提交或手动调用表单校验时触发的场景。
旧的 validateTrigger 仍保留为兼容别名,新代码建议使用 validateOnSubmit。
注意事项
same 依赖传入时的 rules.value,如果对比值来自响应式表单,通常需要用 computed 重新生成规则,确保拿到最新值。pureValid=true 更适合简单正则判断,不会返回 Element Plus 规则对象。
函数源码
validate
来源:packages/utils/src/base.ts
export function validate(
type: ValidateTypeInput = 'required',
rules: ValidateInput | boolean = {},
pureValid = false,
): ValidateRuleResult | boolean {
const normalized = normalizeValidateParams(type, rules, pureValid)
const rulesObject = normalized.rulesObject
const rawRules = normalized.rawRules
const validType = normalized.type
const isPureValid = normalized.pureValid
const trigger = rulesObject.trigger ?? (['blur', 'change'] as ValidateTriggerType[])
// 使用枚举值组成的联合类型来确保类型安全
const typeMaps = Object.values(ValidateType) as string[]
const parseRequired = rulesObject.required ?? true
const defaultRequiredMessage = validType === ValidateType.CHANGE ? '请选择' : '请输入'
const getPureValue = () => (Object.prototype.hasOwnProperty.call(rulesObject, 'value') ? rulesObject.value : rawRules)
// 如果不包含typeMaps中的类型, 直接将第一个参数作为message
if (!typeMaps.includes(validType)) {
return {
required: parseRequired,
message: validType,
trigger,
}
}
if (validType === ValidateType.REQUIRED || validType === ValidateType.CHANGE) {
return {
required: parseRequired,
message: rulesObject.message ?? defaultRequiredMessage,
trigger,
}
}
// validator: this.validateName,
if (validType === ValidateType.PASSWORD) {
const validateName = (rule: any, value: any, callback: (error?: Error) => void) => {
let validFlag = /^[a-zA-Z0-9_-]+$/.test(value)
if (!validFlag) {
callback(new Error(rulesObject.message || '密码只能由英文、数字、下划线、中划线组成'))
} else {
callback()
}
}
return {
validator: validateName,
trigger,
}
}
if (validType === ValidateType.POSITIVE || validType === ValidateType.NUMBER) {
// 正整数
return _validValue(getPureValue(), '请输入正整数', isPureValid, /^[1-9]+\d*$/)
}
if (validType === ValidateType.ZERO_POSITIVE) {
// 正整数且包含0
return _validValue(getPureValue(), '请输入非负整数', isPureValid, /^(0|[1-9]+\d*)$/)
}
// 整数, 包含负数和0
if (validType === ValidateType.INTEGER) {
return _validValue(getPureValue(), '请输入整数', isPureValid, /^(0|[-]?[1-9]\d*)$/)
}
// 非负数, 整数和最多2位小数
if (validType === ValidateType.DECIMAL) {
return _validValue(
getPureValue(),
'请输入非负数字, 包含小数且最多2位',
isPureValid,
/(0|[1-9]\d*)(\.\d{1, 2})?|0\.\d{1,2}/,
)
}
if (validType === ValidateType.MOBILE) {
return _validValue(getPureValue(), '请输入正确的手机号', isPureValid, /^[1][0-9]{10}$/)
}
if (validType === ValidateType.EMAIL) {
return _validValue(getPureValue(), '请输入正确的email', isPureValid, /^[^\s@]+@[^\s@]+\.[^\s@]+$/)
}
if (validType === ValidateType.IP) {
return _validValue(
getPureValue(),
'请输入正确的ip地址',
isPureValid,
/^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/,
)
}
if (validType === ValidateType.PORT) {
return _validValue(
getPureValue(),
'请输入1-65535的端口号',
isPureValid,
/^([1-9]|[1-9][0-9]{1,3}|[1-5][0-9]{4}|6[0-5][0-5][0-3][0-5])$/,
)
}
if (validType === ValidateType.BETWEEN) {
let minValue = rulesObject.min ?? ''
let maxValue = rulesObject.max ?? ''
const validateBetween = (rule: any, value: any, callback: (error?: Error) => void) => {
let validFlag = /^-?[0-9]+$/.test(value)
if (!validFlag) {
callback(new Error('请输入数字'))
}
if (!isEmpty(minValue) && value < minValue) {
callback(new Error(`数字不能小于${minValue}`))
}
if (!isEmpty(maxValue) && value > maxValue && maxValue !== undefined) {
callback(new Error(`数字不能大于${maxValue}`))
}
callback()
}
return {
validator: validateBetween,
trigger,
required: parseRequired,
}
}
if (validType === ValidateType.LENGTH) {
return {
min: rulesObject.min,
max: rulesObject.max,
message: rulesObject.message ?? `请输入${rulesObject.min}到${rulesObject.max}个字符`,
trigger,
required: parseRequired,
}
}
if (validType === ValidateType.SAME) {
const validateSame = (rule: any, value: any, callback: (error?: Error) => void) => {
let isSame = value === rulesObject.value
if (!isSame) {
const errMessage = rulesObject.message || '密码和确认密码要一致'
callback(new Error(errMessage))
}
if (parseRequired && !value) {
callback(new Error(rulesObject.message || '请输入'))
}
callback()
}
let res = {
validator: validateSame,
trigger,
required: parseRequired,
}
return res
}
if (validType === ValidateType.CUSTOM) {
return _validValue(getPureValue(), rulesObject.message, isPureValid, rulesObject.reg!)
}
function _validValue(value: any, msg: string | undefined, pureValid: boolean, reg: RegExp) {
if (pureValid) {
return reg.test(value)
}
const validatePhone = (rule: any, value: any, callback: (error?: Error) => void) => {
let validFlag = reg.test(value)
if (!validFlag) {
callback(new Error(rulesObject.message ?? msg))
} else {
callback()
}
}
return {
validator: validatePhone,
required: rulesObject.required ?? true,
trigger,
}
}
return {}
}validateOnSubmit
来源:packages/utils/src/base.ts
/**
* 为 `validate` 预置空触发时机,只在提交或手动调用表单校验时触发。
*
* @param type 校验类型。
* @param rules 校验规则。
* @param pureValid 是否直接返回布尔值。
* @returns 与 `validate` 一致。
*
* @example
* const rule = validateOnSubmit('required', { message: '请输入名称' })
*/
export function validateOnSubmit(
type: ValidateTypeInput = 'required',
rules: ValidateInput | boolean = {},
pureValid = false,
): ValidateRuleResult | boolean {
const normalized = normalizeValidateParams(type, rules, pureValid)
if (normalized.pureValid) {
return validate(normalized.type, normalized.rawRules, true)
}
return validate(
normalized.type,
{
...normalized.rulesObject,
trigger: normalized.rulesObject.trigger ?? [],
},
normalized.pureValid,
)
}