Справочник API Zod

Zod — это библиотека для объявления и валидации схем на основе TypeScript. Она позволяет определять схемы, которые можно использовать для валидации и трансформации данных, от простых типов (например, string, number) до сложных структур данных (например, вложенных объектов).

Модуль astro/zod предоставляет повторный экспорт Zod, который дает доступ ко всем функциям Zod v3. Используя этот модуль, вам не нужно устанавливать Zod самостоятельно. Это также гарантирует, что ваш проект использует те же версии API, что и Astro, при использовании таких функций, как Коллекции контента или Actions.

Смотрите сайт Zod v3 для полной документации о том, как работает Zod и какие функции доступны.

Импорт из astro/zod

import { z } from 'astro/zod';

z

Тип: object

Утилита z дает доступ к валидаторам для широкого спектра типов данных, методам и типам для работы с вашими данными.

Узнайте больше об утилите z в документации Zod

Валидаторы общих типов данных

С помощью Zod вы можете валидировать любой тип данных, такой как примитивы, объекты, массивы и многое другое.

Следующий пример показывает шпаргалку многих распространенных типов данных Zod для создания схемы user:

import { z } from 'astro/zod';

const user = z.object({
  username: z.string(),
  name: z.string().min(2),
  email: z.string().email(),
  role: z.enum(["admin", "editor"]),
  language: z.enum(["en", "fr", "es"]).default("en"),
  hobbies: z.array(z.string()),
  age: z.number(),
  isEmailConfirmed: z.boolean(),
  inscriptionDate: z.date(),
  website: z.string().url().optional(),
});

Извлечение типа Typescript

Zod позволяет создать тип Typescript из любой схемы используя вывод типов Zod. Это может быть полезно для описания ожидаемой структуры данных при определении пропсов компонента.

Следующий пример создает тип User на основе предыдущей схемы:

type User = z.infer<typeof user>;

/* Тип `User` будет:
 * type User = {
 *   username: string;
 *   name: string;
 *   email: string;
 *   role: "admin" | "editor";
 *   language: "en" | "fr" | "es";
 *   hobbies: string[];
 *   age: number;
 *   isEmailConfirmed: boolean;
 *   inscriptionDate: Date;
 *   website?: string | undefined;
 * }
 */

Использование методов Zod

Zod предоставляет различные методы схемы для настройки сообщений об ошибках, трансформации данных или создания пользовательской логики валидации.

// Настройка сообщения об ошибке
const nonEmptyStrings = z.string().array().nonempty({
  message: "Не может быть пустым!",
});

// Валидация данных по схеме
nonEmptyStrings.parse([]); // выбросит нашу пользовательскую ошибку

// Создание объекта из URL для декоративного изображения
const decorativeImg = z.string().transform((value) => {
  return { src: value, alt: "" };
});

// Создание пользовательского валидатора и сообщения об ошибке для строки
const constrainedString = z
  .string()
  .refine((val) => val.length > 0 && val.length <= 255, {
    message: "Должно быть от 1 до 255 символов.",
  });

Индивидуальный импорт

В качестве альтернативы вы можете импортировать все валидаторы Zod, методы и типы, доступные в утилите z, непосредственно из модуля.

Следующий пример импортирует coerce для создания объекта Date из строки даты:

import { coerce } from 'astro/zod';

const publishedOn = coerce.date();
const publicationDate = publishedOn.parse("2025-12-03");