Skip to content
On this page

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)

参数说明

参数类型必填默认值说明
typestring | object'required'校验类型或规则对象。如果不是内置字符串类型,会把 type 当成错误提示文案,返回必填规则。
rulesobject | string | number | boolean | null | undefined{}校验配置。type 是对象时,此参数作为 pureValid 使用;pureValid=true 时,部分类型会把它当成待校验值。
pureValidbooleanfalse是否直接执行校验并返回布尔值。默认返回 Element Plus 规则对象。

rules 常用字段:

字段类型默认值说明
messagestring内置提示校验失败提示文案。
minnumber-between 的最小值,或 length 的最小长度。
maxnumber-between 的最大值,或 length 的最大长度。
valueany-same 对比值,或 custom 纯校验时的待校验值。
regRegExp-custom 自定义正则。
requiredbooleantrue是否必填。
triggerArray<'blur' | 'change'>['blur', 'change']Element Plus 表单触发时机。

内置类型

类型作用
required必填校验。
change选择类必填校验,默认提示文案为 请选择
password只能包含英文、数字、下划线、中划线。
number / positive正整数。
zeroPositive非负整数,包含 0
integer整数,包含负数和 0
decimal非负数字,最多 2 位小数。
mobile11 位手机号。
email邮箱格式。
ipIPv4 地址。
port1-65535 端口号。
between数值范围校验,配合 minmax
length字符长度校验,配合 minmax
samerules.value 保持一致。
custom使用 rules.reg 自定义正则。

返回值

pureValid=false 时返回 Element Plus 表单规则对象;pureValid=true 时返回 boolean。校验规则对象可直接放入 el-forms-formrules 中。

常用场景

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)
// true
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)
// true

validateOnSubmit

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,
  )
}

思云博智私有前端组件库