数组和元组 Schema

相关源文件

• README.md
• README_ZH.md
• deno/lib/README.md
• deno/lib/__tests__/array.test.ts
• deno/lib/__tests__/string.test.ts
• deno/lib/__tests__/tuple.test.ts
• deno/lib/__tests__/void.test.ts
• deno/lib/types.ts
• src/__tests__/array.test.ts
• src/__tests__/complex.test.ts
• src/__tests__/string.test.ts
• src/__tests__/tuple.test.ts
• src/types.ts

本页面描述了如何在 Zod 中定义、验证和使用数组和元组 schema。数组 schema 验证元素类型相同的动态长度数组，而元组 schema 验证每个位置类型可能不同的固定长度数组。有关记录、映射和集合等其他集合类型的信息，请参阅记录、映射和集合页面。

数组 Schema

在 Zod 中，数组 schema 允许您验证包含特定类型元素的数组。它们提供了检查长度、确保非空以及应用其他数组特定验证的方法。

来源： src/types.ts491-495 src/__tests__/array.test.ts7-11 README.md113-116

创建数组 Schema

在 Zod 中创建数组 schema 有两种方式

1. 使用 z.array() 函数

2. 在现有 schema 上使用 .array() 方法

这两种方法都会创建相同的结果——一个验证字符串数组的 schema。

来源： README.md113-116 src/__tests__/array.test.ts7-11

验证方法

Zod 提供了几种验证数组长度的方法

方法	描述	示例
.min(n)	确保数组至少有 n 个元素	z.string().array().min(2)
.max(n)	确保数组最多有 n 个元素	z.string().array().max(5)
.length(n)	确保数组恰好有 n 个元素	z.string().array().length(3)
.nonempty()	确保数组至少有一个元素	z.string().array().nonempty()

这些方法接受一个可选的第二个参数用于自定义错误消息

来源： src/__tests__/array.test.ts7-11 README.md116

元素 Schema 访问

您可以使用 .element 属性访问数组元素的 schema

当您需要独立于数组验证单个元素时，这会很有用。

来源： src/__tests__/array.test.ts48-51

类型推断

Zod 会自动从您的数组 schema 推断 TypeScript 类型

请注意，.nonempty() 提供了一个更具体的类型，它使用 TypeScript 的元组（带有 rest 元素）表示法确保至少存在一个元素。

来源： src/__tests__/array.test.ts13-17

元组 Schema

数组 schema 验证相同类型元素的集合，而元组 schema 验证固定长度数组，其中每个位置可以有不同的类型。

来源： src/__tests__/tuple.test.ts8-12 README.md117

创建元组 Schema

使用 z.tuple([...]) 函数创建元组 schema，传入一个定义每个位置类型的 schema 数组

来源： src/__tests__/tuple.test.ts8-12 README.md117

剩余元素

元组可以使用 .rest() 方法拥有剩余元素（末尾的可变数量元素）

带有剩余元素的元组的类型推断正确地反映了 TypeScript 元组类型

来源： src/__tests__/tuple.test.ts74-90 README.md117

元组的转换

元组 schema 支持转换，其中每个元素 schema 都可以有自己的转换

类型推断会自动跟踪这些转换

来源： src/__tests__/tuple.test.ts62-71

比较：数组 vs 元组

理解何时使用数组 schema 和元组 schema 对于有效的验证非常重要。

下面是详细的比较

功能	数组 Schema	元组 Schema
长度	可变	固定长度（除非使用 .rest()）
元素类型	所有元素类型相同	每个位置可以有不同类型
类型推断	T[]	[T1, T2, T3, ...]
创建	z.array(schema) 或 schema.array()	z.tuple([schema1, schema2, ...])
常见用例	集合，列表	坐标，固定结构数据
访问元素 Schema	.element 属性	不适用（在原始数组中访问 schema）

来源： README.md113-117 src/__tests__/array.test.ts src/__tests__/tuple.test.ts

常见用例

数组 Schema 用例

1. 验证统一数据列表:

2. 确保集合非空:

3. 验证包含复杂元素类型的列表:

元组 Schema 用例

1. 坐标或对:

2. 固定格式数据结构:

3. 带有元组剩余参数的函数参数:

来源： src/__tests__/tuple.test.ts8-12 src/__tests__/array.test.ts7-11 README.md113-117

错误处理

当验证失败时，Zod 会提供详细的错误信息

对于数组验证，与元素验证相关的错误会在错误路径中包含索引。

来源： src/__tests__/array.test.ts54-65 src/__tests__/tuple.test.ts34-45

内部实现

ZodArray 和 ZodTuple 类扩展了基础的 ZodType 类，并为各自的验证实现了自定义解析逻辑。

数组的验证过程包括以下步骤

1. 检查输入是否为数组
2. 根据元素 schema 验证每个元素
3. 应用额外的验证（最小/最大/长度）

元组的验证过程

1. 检查输入是否为数组
2. 根据预期长度验证长度
3. 根据其对应的 schema 验证每个元素
4. 如果提供了剩余 schema，则根据它验证任何额外的元素

来源： src/types.ts