Valibot 中的日期时间处理：正确使用 ISO 格式验证

在 JavaScript 生态系统中，日期时间的处理一直是开发者经常遇到的挑战之一。Valibot 作为一个数据验证库，提供了多种方法来验证不同格式的日期和时间字符串。本文将重点介绍 Valibot 中处理 ISO 格式日期时间的正确方式。

ISO 日期与时间戳的区别

Valibot 提供了两个关键验证器来处理 ISO 格式的日期时间：

1. isoDate - 专门用于验证简单的日期格式（yyyy-mm-dd）
2. isoTimestamp - 用于验证完整的日期时间格式（包括时区信息）

许多开发者容易混淆这两者的用途，特别是当面对 API 返回的常见日期时间格式时。例如，API 通常返回类似 "2024-06-29T22:03:56Z" 这样的完整时间戳，其中包含日期、时间和时区信息。

常见错误场景

开发者可能会尝试使用 isoDate 来验证完整的时间戳字符串，这会导致验证失败，因为：

• isoDate 期望的格式是 "0000-01-01"
• 而实际需要验证的是包含时间部分的 "2024-06-29T22:03:56Z"

正确的验证方法

对于包含时间信息的完整 ISO 时间戳，应该使用 isoTimestamp 验证器：

import * as v from 'valibot';

const Schema = v.object({
  date: v.pipe(v.string(), v.isoTimestamp())
});

const result = v.safeParse(Schema, {
  date: '2024-06-29T22:03:56Z'
});

实际应用建议

1. 明确区分只需要日期还是需要完整时间戳的场景
2. 对于 API 交互，大多数情况下应该使用 isoTimestamp
3. 对于仅需要日期的场景（如生日字段），使用 isoDate 更为合适
4. 考虑时区处理需求，完整时间戳通常包含时区信息（如末尾的 Z 表示 UTC）

理解这些区别可以帮助开发者在处理日期时间数据时避免常见的验证错误，确保应用程序能够正确处理来自各种来源的时间数据。