快速开始

Valibot 模式可以与 TypeScript 中的类型定义进行比较。最大的区别在于 TypeScript 类型是 “不执行的”，更多地是一个开发体验（DX）功能。而模式除了推断的类型定义之外，还可以在运行时执行，以真正保证未知数据的类型安全。

基本概念

与在 TypeScript 中定义类型的方式类似，Valibot 允许你使用各种小型函数来定义模式。这适用于像字符串这样的基本值，也适用于像对象这样更复杂的数据集。

import * as v from 'valibot';

// TypeScript
type LoginData = {
  email: string;
  password: string;
};

// Valibot
const LoginSchema = v.object({
  email: v.string(),
  password: v.string(),
});

管道（Pipelines）

此外，管道功能使你能够使用 pipe 方法执行更详细的验证和转换。例如，可以确保一个字符串是电子邮件，并且以特定域名结尾。

import * as v from 'valibot';

const EmailSchema = v.pipe(v.string(), v.email(), v.endsWith('@example.com'));

管道必须始终以一个模式开始，后面最多跟 19 个验证或转换操作。它们按顺序执行，前一个操作的结果将传递给下一个。有关管道的更多详细信息，请参阅本指南。

错误信息

如果在验证期间检测到问题，该库会发出一个特定的问题(issue)对象，其中包含各种详细信息和错误信息。这个错误信息可以通过模式或验证操作的第一个可选参数来覆盖。

import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(
    v.string('你的电子邮件必须是字符串。'),
    v.nonEmpty('请输入你的电子邮件。'),
    v.email('电子邮件地址格式不正确。')
  ),
  password: v.pipe(
    v.string('你的密码必须是字符串。'),
    v.nonEmpty('请输入你的密码。'),
    v.minLength(8, '你的密码必须至少有 8 个字符。')
  ),
});

自定义错误信息允许你通过提供具体的故障排除信息和以非英语语言返回错误信息来改善软件的可用性。有关更多信息，请参阅 i18n 指南。

用法

最后，你可以使用模式来推断其输入和输出类型，并解析未知数据。这样，你的模式就成为了单一事实来源。这个概念简化了你的开发流程，并从长远来看使你的代码更加健壮。

import * as v from 'valibot';

const LoginSchema = v.object({/*...*/});

type LoginData = v.InferOutput<typeof LoginSchema>;

function getLoginData(data: unknown): LoginData {
  return v.parse(LoginSchema, data);
}

安装

用例