# Arrays

URL: https://caijiao.org/zod/arrays
Source: docs/zod/arrays.md
Description: 数组类型验证和处理方法，包括数组元素的类型检查和约束

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"]
```