前端 - 初识zod - 随心所欲的验证库 - 表单验证神器

效果图

目标：限制用户输入框中文字长度为1，且只能是大写字母。

写在前面

zod英文官网：https://zod.dev/api#strings

zod支持自定义的正则匹配，也支持类型判断，也内置了一些常见的验证情景，开箱即用：

核心代码

{
  component: "Input",
  componentProps: {
    placeholder: "请输入大写单字母"
  },
  fieldName: "book_prefix",
  label: "预约号前缀单字母",
  rules: z
    .string()
    .max(1, '最多一位大写字母')
    .regex(/^[A-Z]{1}$/,'请输入大写字母')
}

项目是Vue Vben Admin v5大仓的web-antd应用，
vben官方手册：https://doc.vben.pro/components/common-ui/vben-form.html#zod
zod英文官网：https://zod.dev/api#strings

其中，

1）z代码不包含 .optional() 的话，就代表这个字段必填，空值触发placeholder警告

2）.max代表最大的合法的长度

3）.regex( 正则表达式, 不成立时的警告文字 )

更多实例

import { z } from 'zod';

// 1. 基础数字校验（整数）
const integerSchema = z.number().int();
console.log(integerSchema.safeParse(123)); // 成功
console.log(integerSchema.safeParse(123.45)); // 失败

// 2. 浮点型校验
const floatSchema = z.number().finite(); // 排除 Infinity 和 NaN
console.log(floatSchema.safeParse(123.45)); // 成功
console.log(floatSchema.safeParse(Infinity)); // 失败

// 3. 小数点后两位校验
const twoDecimalSchema = z.number().refine(
  (num) => {
    const str = num.toString();
    const decimalPart = str.split('.')[1] || '';
    return decimalPart.length <= 2;
  },
  { message: '必须是小数点后最多两位的数字' }
);
console.log(twoDecimalSchema.safeParse(123.45)); // 成功
console.log(twoDecimalSchema.safeParse(123.456)); // 失败

// 4. 数字范围校验（例如 1-100 之间）
const rangeSchema = z.number().min(1).max(100);
console.log(rangeSchema.safeParse(50)); // 成功
console.log(rangeSchema.safeParse(0)); // 失败
console.log(rangeSchema.safeParse(101)); // 失败

// 5. 布尔类型校验
const booleanSchema = z.boolean();
console.log(booleanSchema.safeParse(true)); // 成功
console.log(booleanSchema.safeParse(0)); // 失败（0 不是布尔值）

// 6. 手机号码校验（中国大陆）
const phoneSchema = z.string().regex(
  /^1[3-9]\d{9}$/,
  '请输入有效的手机号码'
);
console.log(phoneSchema.safeParse('13800138000')); // 成功
console.log(phoneSchema.safeParse('12345678901')); // 失败

// 7. 身份证号码校验（中国大陆 18位）
const idCardSchema = z.string().regex(
  /^[1-9]\d{5}(18|19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$/,
  '请输入有效的身份证号码'
);
console.log(idCardSchema.safeParse('110101199001011234')); // 成功
console.log(idCardSchema.safeParse('1234567890123456789')); // 失败（长度不对）

// 8. 非负整数校验
const nonNegativeIntSchema = z.number().int().min(0);
console.log(nonNegativeIntSchema.safeParse(0)); // 成功
console.log(nonNegativeIntSchema.safeParse(-5)); // 失败

// 9. 正浮点数校验
const positiveFloatSchema = z.number().positive().finite();
console.log(positiveFloatSchema.safeParse(3.14)); // 成功
console.log(positiveFloatSchema.safeParse(-2.5)); // 失败

// 10. 数组元素范围校验
const numberArraySchema = z.array(z.number().min(0).max(10));
console.log(numberArraySchema.safeParse([1, 5, 10])); // 成功
console.log(numberArraySchema.safeParse([1, 11, 3])); // 失败

// 11. 日期字符串校验（YYYY-MM-DD）
const dateSchema = z.string().regex(
  /^\d{4}-\d{2}-\d{2}$/,
  '日期格式必须为 YYYY-MM-DD'
);
console.log(dateSchema.safeParse('2023-12-31')); // 成功
console.log(dateSchema.safeParse('2023/12/31')); // 失败

// 12. 邮箱格式校验
const emailSchema = z.string().email('请输入有效的邮箱地址');
console.log(emailSchema.safeParse('test@example.com')); // 成功
console.log(emailSchema.safeParse('invalid-email')); // 失败

// 13. 字符串长度校验
const stringLengthSchema = z.string().min(3).max(10);
console.log(stringLengthSchema.safeParse('hello')); // 成功
console.log(stringLengthSchema.safeParse('hi')); // 失败

// 14. 必须为特定值的校验
const specificValueSchema = z.enum(['apple', 'banana', 'orange']);
console.log(specificValueSchema.safeParse('apple')); // 成功
console.log(specificValueSchema.safeParse('grape')); // 失败

// 15. 对象结构及字段校验
const userSchema = z.object({
  name: z.string().min(1),
  age: z.number().int().min(0).max(120),
  isStudent: z.boolean(),
  phone: phoneSchema.optional() // 复用之前定义的手机号码校验
});
console.log(userSchema.safeParse({
  name: '张三',
  age: 20,
  isStudent: true
})); // 成功

z.file().min(1).max(1024 * 1024).mime("image/png");

z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().regex(/^[a-z]+$/);
z.string().startsWith("aaa");
z.string().endsWith("zzz");
z.string().includes("---");
z.string().uppercase();
z.string().lowercase();

z.string().trim(); // trim whitespace
z.string().toLowerCase(); // toLowerCase
z.string().toUpperCase(); // toUpperCase
z.string().normalize(); // normalize unicode characters

z.email();
z.uuid();
z.url();
z.httpUrl();       // http or https URLs only
z.hostname();
z.emoji();         // validates a single emoji character
z.base64();
z.base64url();
z.hex();
z.jwt();
z.nanoid();
z.cuid();
z.cuid2();
z.ulid();
z.ipv4();
z.ipv6();
z.cidrv4();        // ipv4 CIDR block
z.cidrv6();        // ipv6 CIDR block
z.hash("sha256");  // or "sha1", "sha384", "sha512", "md5"
z.iso.date();
z.iso.time();
z.iso.datetime();
z.iso.duration();

相关

zod官网 - 正则匹配
https://zod.dev/api#strings

大前端扫地僧之必备技能Zod
https://www.ifrontend.net/2024/12/zod-guide/

TypeScript 如何使用 zod 检查确认密码
https://deepinout.com/typescript/typescript-questions/664_typescript_how_to_check_confirm_password_with_zod.html

ending...