统一校验 useValidator

useValidator() 统一校验规则库：手机号 / 座机 / 邮箱 / 网址 / IPv4 / IPv6 / 网段 / 邮编 / 身份证 / 银行卡 / 统一社会信用代码 / 车牌 / 数值 / 金额 / 百分比 / 长度 / 异步唯一性的规则构造器。每个构造器返回 FormItemRule[]，可直接展开进 el-form 的 rules、BizFormDialog / BizStepsForm 字段的 rules——与库内输入组件（BizPhoneInput / BizIdCardInput 等）同一套口径，表单规则与组件校验不再两套正则。

身份证（GB 11643 校验位）、银行卡（Luhn）、统一社会信用代码（GB 32100-2015 校验位）为算法级校验，不是简单正则。

约定：空值放行，必填显式声明

格式类规则默认空值放行（只校格式，不逼必填）——需要必填传 { required: true }，自动叠加「必填 + 格式」两条规则，两种提示语互不干扰：

const v = useValidator()
const rules = {
  phone: v.phone({ required: true, label: '手机号' }), // 空 →「请输入手机号」；格式错 →「手机号格式不正确」
  email: v.email(),                                    // 选填：空放行，填了才校格式
}

所有构造器通用选项：label（生成默认提示）、message（覆盖格式提示）、required / requiredMessage、trigger（默认 blur）。

规则试炼场

✓ 格式正确

切换规则会自动带入一个合法样例（身份证校验位 / 银行卡 Luhn / 信用代码 GB 32100 均为算法级校验，非单纯正则）。

选一种规则即时验证输入值，直观看每个校验器的口径；切换规则自动带入合法样例。

<script setup lang="ts">
/** 场景：规则试炼场——选一种规则即时验证输入值，直观看每个校验器的口径 */
import { computed, ref } from 'vue'
import { isBankCard, isCreditCode, isIdCard, isIp, isPlate, isPhone, isEmail, isUrl, isZipcode, isCidr, isLandline, isIpv6 } from 'vue3-ep-biz-lib'

type Kind = 'phone' | 'email' | 'idCard' | 'bankCard' | 'creditCode' | 'plate' | 'ip' | 'ipv6' | 'cidr' | 'zipcode' | 'landline' | 'url'

const kind = ref<Kind>('phone')
const value = ref('13800138000')

const checks: Record<Kind, (v: string) => boolean> = {
  phone: isPhone,
  email: isEmail,
  idCard: isIdCard,
  bankCard: isBankCard,
  creditCode: isCreditCode,
  plate: isPlate,
  ip: isIp,
  ipv6: isIpv6,
  cidr: isCidr,
  zipcode: isZipcode,
  landline: isLandline,
  url: isUrl,
}

const samples: Record<Kind, string> = {
  phone: '13800138000',
  email: 'owner@example.com',
  idCard: '11010519491231002X',
  bankCard: '4111 1111 1111 1111',
  creditCode: '91350100M000100Y43',
  plate: '京AD12345',
  ip: '192.168.1.10',
  ipv6: '2001:db8::8a2e:370:7334',
  cidr: '192.168.1.0/24',
  zipcode: '100000',
  landline: '0592-1234567',
  url: 'https://example.com/path',
}

const result = computed(() => (value.value.trim() === '' ? null : checks[kind.value](value.value)))

const onKindChange = (): void => {
  value.value = samples[kind.value]
}
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 12px; align-items: center">
    <el-select v-model="kind" style="width: 220px" @change="onKindChange">
      <el-option v-for="(_, k) in checks" :key="k" :value="k" :label="`${k} 校验`" />
    </el-select>
    <el-input v-model="value" style="width: 280px" placeholder="输入待验证的值" clearable />
    <el-tag v-if="result === true" type="success">✓ 格式正确</el-tag>
    <el-tag v-else-if="result === false" type="danger">✗ 格式不正确</el-tag>
    <el-tag v-else type="info">空值放行（必填由 required 控制）</el-tag>
  </div>
  <p style="margin-top: 8px; color: var(--el-text-color-secondary); font-size: 13px">
    切换规则会自动带入一个合法样例（身份证校验位 / 银行卡 Luhn / 信用代码 GB 32100 均为算法级校验，非单纯正则）。
  </p>
</template>

显示代码

基本信息表单

姓名

手机号

邮箱

证件号

必填 + 格式组合（手机 / 邮箱），选填仅校格式（身份证 18 位校验位算法）。

<script setup lang="ts">
/** 场景：基本信息表单——手机/邮箱必填+格式，身份证选填仅校格式 */
import { reactive, ref } from 'vue'
import { ElMessage, type FormInstance } from 'element-plus'
import { useValidator } from 'vue3-ep-biz-lib'

const v = useValidator()
const formRef = ref<FormInstance>()
const form = reactive({ name: '', phone: '', email: '', idCard: '' })

const rules = {
  name: v.required('姓名'),
  phone: v.phone({ required: true, label: '联系电话' }),
  email: v.email({ required: true, label: '邮箱' }),
  idCard: v.idCard({ label: '证件号' }),
}

const submit = (): void => {
  formRef.value?.validate((valid) => {
    if (valid) ElMessage.success(`校验通过：${JSON.stringify(form)}`)
  })
}
</script>

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="90px" style="max-width: 520px">
    <el-form-item label="姓名" prop="name">
      <el-input v-model="form.name" placeholder="必填" />
    </el-form-item>
    <el-form-item label="手机号" prop="phone">
      <el-input v-model="form.phone" placeholder="必填 + 11 位格式" />
    </el-form-item>
    <el-form-item label="邮箱" prop="email">
      <el-input v-model="form.email" placeholder="必填 + 邮箱格式" />
    </el-form-item>
    <el-form-item label="证件号" prop="idCard">
      <el-input v-model="form.idCard" placeholder="选填，填了才校验（18 位校验位算法）" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submit">提 交</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

企业认证表单

企业名称

统一社会信用代码

公务车牌

注册地邮编

客服电话

统一社会信用代码（GB 32100 校验位）、车牌（燃油 5 位 / 新能源 6 位）、邮编、座机（可带区号 / 分机）。

<script setup lang="ts">
/** 场景：企业认证表单——统一社会信用代码（校验位）、车牌（含新能源）、邮编、座机 */
import { reactive, ref } from 'vue'
import { ElMessage, type FormInstance } from 'element-plus'
import { useValidator } from 'vue3-ep-biz-lib'

const v = useValidator()
const formRef = ref<FormInstance>()
const form = reactive({ company: '', creditCode: '', plate: '', zipcode: '', hotline: '' })

const rules = {
  company: v.required('企业名称'),
  creditCode: v.creditCode({ required: true, label: '统一社会信用代码' }),
  plate: v.plate({ label: '车牌号' }),
  zipcode: v.zipcode({ label: '邮编' }),
  hotline: v.landline({ label: '客服电话' }),
}

const submit = (): void => {
  formRef.value?.validate((valid) => {
    if (valid) ElMessage.success('认证信息校验通过')
  })
}
</script>

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="150px" style="max-width: 560px">
    <el-form-item label="企业名称" prop="company">
      <el-input v-model="form.company" />
    </el-form-item>
    <el-form-item label="统一社会信用代码" prop="creditCode">
      <el-input v-model="form.creditCode" placeholder="18 位，如 91350100M000100Y43" />
    </el-form-item>
    <el-form-item label="公务车牌" prop="plate">
      <el-input v-model="form.plate" placeholder="燃油 5 位 / 新能源 6 位，如 京AD12345" />
    </el-form-item>
    <el-form-item label="注册地邮编" prop="zipcode">
      <el-input v-model="form.zipcode" />
    </el-form-item>
    <el-form-item label="客服电话" prop="hotline">
      <el-input v-model="form.hotline" placeholder="0592-1234567 或 12345678" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submit">提交认证</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

网络参数录入

主机地址

网关地址

IPv6

子网网段

IPv4 严格四段（每段 0-255）、IPv6（支持 :: 缩写）、CIDR 网段（掩码 0-32）。

<script setup lang="ts">
/** 场景：网络参数录入——IPv4 严格四段、IPv6 缩写、CIDR 网段 */
import { reactive, ref } from 'vue'
import { ElMessage, type FormInstance } from 'element-plus'
import { useValidator } from 'vue3-ep-biz-lib'

const v = useValidator()
const formRef = ref<FormInstance>()
const form = reactive({ host: '', gateway: '', ipv6: '', cidr: '' })

const rules = {
  host: v.ip({ required: true, label: '主机地址' }),
  gateway: v.ip({ required: true, label: '网关地址' }),
  ipv6: v.ipv6({ label: 'IPv6 地址' }),
  cidr: v.cidr({ required: true, label: '子网网段' }),
}

const submit = (): void => {
  formRef.value?.validate((valid) => {
    if (valid) ElMessage.success('网络参数校验通过')
  })
}
</script>

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="100px" style="max-width: 520px">
    <el-form-item label="主机地址" prop="host">
      <el-input v-model="form.host" placeholder="192.168.1.10（每段 0-255）" />
    </el-form-item>
    <el-form-item label="网关地址" prop="gateway">
      <el-input v-model="form.gateway" placeholder="192.168.1.1" />
    </el-form-item>
    <el-form-item label="IPv6" prop="ipv6">
      <el-input v-model="form.ipv6" placeholder="2001:db8::1（支持 :: 缩写）" />
    </el-form-item>
    <el-form-item label="子网网段" prop="cidr">
      <el-input v-model="form.cidr" placeholder="192.168.1.0/24（掩码 0-32）" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submit">保存网络配置</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

异步唯一性校验

用户名

昵称

v.unique(check) 生成 asyncValidator 规则：check 返回 Promise，resolve true 可用 / false 已占用；接口异常降级为「校验服务异常」提示。

<script setup lang="ts">
/** 场景：异步唯一性校验——注册用户名查重（模拟接口延迟，admin/root/test 已被占用） */
import { reactive, ref } from 'vue'
import { ElMessage, type FormInstance } from 'element-plus'
import { useValidator } from 'vue3-ep-biz-lib'

const TAKEN = ['admin', 'root', 'test']
const checkUsername = (value: string): Promise<boolean> =>
  new Promise((resolve) => setTimeout(() => resolve(!TAKEN.includes(value.toLowerCase())), 800))

const v = useValidator()
const formRef = ref<FormInstance>()
const form = reactive({ username: '', nickname: '' })

const rules = {
  username: v.unique(checkUsername, { required: true, label: '用户名', message: '用户名已被注册' }),
  nickname: v.required('昵称'),
}

const submit = (): void => {
  formRef.value?.validate((valid) => {
    if (valid) ElMessage.success(`用户名 ${form.username} 可用，注册成功`)
  })
}
</script>

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="80px" style="max-width: 460px">
    <el-form-item label="用户名" prop="username">
      <el-input v-model="form.username" placeholder="输入 admin / root / test 体验占用提示" />
    </el-form-item>
    <el-form-item label="昵称" prop="nickname">
      <el-input v-model="form.nickname" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submit">注 册</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

数值类规则

排序号

售价

折扣

商品标题

number（整数 / 范围）、amount（范围 + 小数位上限）、percentage（0-100）、length（字符区间）。

<script setup lang="ts">
/** 场景：数值类规则——整数/范围、金额（小数位）、百分比、字符长度 */
import { reactive, ref } from 'vue'
import { ElMessage, type FormInstance } from 'element-plus'
import { useValidator } from 'vue3-ep-biz-lib'

const v = useValidator()
const formRef = ref<FormInstance>()
const form = reactive({ sort: '', price: '', discount: '', title: '' })

const rules = {
  sort: v.number({ required: true, label: '排序号', integer: true, min: 1, max: 999 }),
  price: v.amount({ required: true, label: '售价', min: 0.01, max: 99999, precision: 2 }),
  discount: v.percentage({ label: '折扣' }),
  title: v.length({ required: true, label: '商品标题', min: 2, max: 20 }),
}

const submit = (): void => {
  formRef.value?.validate((valid) => {
    if (valid) ElMessage.success('商品参数校验通过')
  })
}
</script>

<template>
  <el-form ref="formRef" :model="form" :rules="rules" label-width="90px" style="max-width: 520px">
    <el-form-item label="排序号" prop="sort">
      <el-input v-model="form.sort" placeholder="1 ~ 999 的整数" />
    </el-form-item>
    <el-form-item label="售价" prop="price">
      <el-input v-model="form.price" placeholder="0.01 ~ 99999，最多 2 位小数" />
    </el-form-item>
    <el-form-item label="折扣" prop="discount">
      <el-input v-model="form.discount" placeholder="0 ~ 100，选填" />
    </el-form-item>
    <el-form-item label="商品标题" prop="title">
      <el-input v-model="form.title" placeholder="2 ~ 20 个字符" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="submit">保 存</el-button>
    </el-form-item>
  </el-form>
</template>

显示代码

与 BizFormDialog 集成

字段 rules 直接传构造器返回的数组（required: true 选项与字段自带 required 叠加不冲突）。

<script setup lang="ts">
/** 场景：与 BizFormDialog 集成——字段 rules 直接用构造器返回的数组 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizButton, BizFormDialog, useValidator, type BizFormField } from 'vue3-ep-biz-lib'

const v = useValidator()
const visible = ref(false)

const fields: BizFormField[] = [
  { prop: 'contact', label: '联系人', required: true },
  { prop: 'phone', label: '手机号', rules: v.phone({ required: true, label: '手机号' }) },
  { prop: 'email', label: '邮箱', rules: v.email({ label: '邮箱' }) },
  { prop: 'taxCode', label: '税号', rules: v.creditCode({ label: '税号' }), span: 24 },
]

const onSubmit = (model: Record<string, unknown>, done: () => void): void => {
  setTimeout(() => {
    ElMessage.success(`保存成功：${String(model.contact ?? '')}`)
    done()
  }, 600)
}
</script>

<template>
  <BizButton type="primary" @click="visible = true">新增客户</BizButton>
  <BizFormDialog
    v-model="visible"
    title="新增客户"
    :fields="fields"
    label-width="90px"
    @submit="onSubmit"
  />
</template>

显示代码

与 BizStepsForm 集成

0

账号信息

登录凭据

0

企业信息

开票资质

用户名

手机号

分步表单每步只校当步字段，规则写法与单表单完全一致。

<script setup lang="ts">
/** 场景：与 BizStepsForm 集成——分步校验，每步只校当步字段 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizStepsForm, useValidator, type BizStepsItem } from 'vue3-ep-biz-lib'

const v = useValidator()

const steps: BizStepsItem[] = [
  {
    title: '账号信息',
    description: '登录凭据',
    fields: [
      { prop: 'username', label: '用户名', rules: v.length({ required: true, label: '用户名', min: 4, max: 16 }) },
      { prop: 'phone', label: '手机号', rules: v.phone({ required: true, label: '手机号' }) },
    ],
  },
  {
    title: '企业信息',
    description: '开票资质',
    fields: [
      { prop: 'company', label: '企业名称', required: true },
      { prop: 'creditCode', label: '信用代码', rules: v.creditCode({ required: true, label: '信用代码' }) },
      { prop: 'email', label: '邮箱', rules: v.email({ label: '邮箱' }) },
    ],
  },
]

const model = ref<Record<string, unknown>>({})

const onFinish = (data: Record<string, unknown>): void => {
  ElMessage.success(`开通完成：${String(data.username)} @ ${String(data.company)}`)
}
</script>

<template>
  <BizStepsForm v-model="model" :steps="steps" label-width="90px" @finish="onFinish" />
</template>

显示代码

API

useValidator(): BizValidator

构造器	口径	默认提示
required(label?)	必填	请输入
phone()	1[3-9] 开头 11 位	手机号格式不正确
landline()	可带区号 0592-1234567、分机 -123	座机号格式不正确
email() / url()	常规格式，url 限 http/https	邮箱 / 网址格式不正确
ip() / ipv6() / cidr()	IPv4 四段 0-255；IPv6 含 :: 缩写；网段 192.168.1.0/24	IP 地址 / IPv6 地址 / 网段格式不正确
zipcode()	6 位数字	邮政编码格式不正确
idCard()	18 位校验位算法（权重模 11），兼容 15 位旧证，校验省份码与月日	身份证号格式不正确
bankCard()	12-19 位（忽略空格）+ Luhn	银行卡号格式不正确
creditCode()	18 位 GB 32100-2015 校验位（31 字符集 + 指定权重）	统一社会信用代码格式不正确
plate()	省份汉字 + 字母 + 5 位，新能源 6 位（D/F 结尾）	车牌号格式不正确
number({integer,min,max})	数字 / 整数 / 范围	数值必须是数字 / 整数 / 不能小于 x…
amount({min,max,precision})	数值范围 + 小数位上限（默认 2 位）	金额最多保留 n 位小数…
percentage()	0 ~ 100	百分比不能小于 0 / 大于 100
length({min,max})	字符数区间	不能少于 / 超过 n 个字符
unique(check)	异步查重：check(value) => Promise<boolean>	{label}已被占用

纯函数与正则（表单外即时判断）

isPhone / isLandline / isEmail / isUrl / isIp / isIpv6 / isCidr / isZipcode / isIdCard / isBankCard / isCreditCode / isPlate 与规则构造器同一套口径；BIZ_PATTERNS 暴露简单格式的原始正则（phone / landline / email / url / zipcode）。

行为要点

• 空值放行：格式规则遇空值直接通过，必填交由 required 选项追加的规则——空值不会同时弹两条错误；
• 自动 trim：所有校验对输入值做 trim 后判定（银行卡额外忽略空格）；
• trigger 默认 blur：选择类字段可传 { trigger: 'change' }；
• 异步规则容错：unique 的 check 抛异常时提示「校验服务异常，请稍后重试」，不白屏不卡 loading。