基本用法

本页将带您了解创建模式、解析数据和使用推断类型的基础知识。有关 Zod 模式 API 的完整文档，请参阅定义模式。

定义模式

在做任何其他事情之前，您需要定义一个模式。为了便于本指南的说明，我们将使用一个简单的对象模式。

import * as z from "zod"; 
 
const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});

解析数据

给定任何 Zod 模式，使用 .parse 来验证输入。如果有效，Zod 将返回输入的强类型深层克隆。

Player.parse({ username: "billie", xp: 100 }); 
// => 返回 { username: "billie", xp: 100 }

注意 — 如果您的模式使用某些异步 API，如 async refinements（细化）或 transforms（转换），您需要使用 .parseAsync() 方法。

await Player.parseAsync({ username: "billie", xp: 100 });

处理错误

当验证失败时，.parse() 方法将抛出一个 ZodError 实例，其中包含有关验证问题的详细信息。

try {
  Player.parse({ username: 42, xp: "100" });
} catch(error){
  if(error instanceof z.ZodError){
    error.issues; 
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}

为了避免 try/catch 块，您可以使用 .safeParse() 方法来获取一个包含成功解析的数据或 ZodError 的普通结果对象。结果类型是一个受歧视的联合（discriminated union），因此您可以方便地处理这两种情况。

const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error;   // ZodError 实例
} else {
  result.data;    // { username: string; xp: number }
}

注意 — 如果您的模式使用某些异步 API，如 async refinements（细化）或 transforms（转换），您需要使用 .safeParseAsync() 方法。

await schema.safeParseAsync("hello");

推断类型

Zod 从您的模式定义中推断出静态类型。您可以使用 z.infer<> 实用工具提取此类型，并按您喜欢的方式使用它。

const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});
 
// 提取推断类型
type Player = z.infer<typeof Player>;
 
// 在您的代码中使用它
const player: Player = { username: "billie", xp: 100 };

在某些情况下，模式的输入和输出类型可能会有所不同。例如，.transform() API 可以将输入从一种类型转换为另一种类型。在这些情况下，您可以独立提取输入和输出类型：

const mySchema = z.string().transform((val) => val.length);
 
type MySchemaIn = z.input<typeof mySchema>;
// => string
 
type MySchemaOut = z.output<typeof mySchema>; // 等同于 z.infer<typeof mySchema>
// number

既然我们已经涵盖了基础知识，让我们深入了解 Schema API。

定义模式

解析数据

处理错误

推断类型

On this page