教程 zod tutorial

Arrays

Zod 提供了多种方式来验证数组。

基本用法

ts
import { z } from "zod";

// 创建数组模式
const stringArray = z.array(z.string());
const numberArray = z.array(z.number());

// 另一种写法
const stringArray2 = z.string().array();
const numberArray2 = z.number().array();

// 验证
stringArray.parse(["a", "b", "c"]); // 通过
stringArray.parse(["a", 123, "c"]); // 失败

非空数组

使用 .nonempty() 确保数组至少包含一个元素:

ts
const nonEmptyStrings = z.string().array().nonempty();
// 类型为 [string, ...string[]]

nonEmptyStrings.parse([]); // 失败:数组不能为空
nonEmptyStrings.parse(["hello"]); // 通过

长度验证

ts
// 最小长度
z.string().array().min(5); // 至少5个元素

// 最大长度
z.string().array().max(10); // 最多10个元素

// 精确长度
z.string().array().length(3); // 必须正好3个元素

// 组合使用
z.string().array().min(2).max(5); // 2到5个元素

自定义错误消息

ts
z.array(z.string()).nonempty({
  message: "数组必须至少包含一个元素",
});

z.array(z.string()).min(3, {
  message: "数组必须至少包含3个元素",
});

z.array(z.string()).max(5, {
  message: "数组不能超过5个元素",
});

复杂数组

ts
// 对象数组
const User = z.object({
  id: z.string(),
  name: z.string(),
});
const UserArray = z.array(User);

// 联合类型数组
const mixedArray = z.array(z.union([z.string(), z.number()]));
mixedArray.parse(["hello", 42, "world"]); // 通过

// 嵌套数组
const matrix = z.array(z.array(z.number()));
matrix.parse([
  [1, 2, 3],
  [4, 5, 6],
]); // 通过

数组元素转换

ts
// 转换数组中的每个元素
const numberStrings = z
  .array(z.string())
  .transform(arr => arr.map(Number));

numberStrings.parse(["1", "2", "3"]); // => [1, 2, 3]

// 过滤数组元素
const nonEmptyStrings = z
  .array(z.string())
  .transform(arr => arr.filter(str => str.length > 0));

nonEmptyStrings.parse(["", "hello", "", "world"]); // => ["hello", "world"]