optional

使值变为选填。如果值缺失（undefined）或为空字符串（''），则跳过校验并使用默认值。

签名

function optional<T>(schema: Schema<T>): Schema<T | undefined>
function optional<T>(schema: Schema<T>, default: T | (() => T)): Schema<T>

参数

参数	类型	说明
schema	Schema<T>	值存在时使用的 Schema
default	T | (() => T)	默认值或返回默认值的函数

注意事项

• null 不被视为缺失 —— 请使用 nullable。两者都允许：optional(nullable(string()))。
• 没有 default 时，object 中的字段在类型上变为可选（name?: string），缺失时不会出现在 data 中。
• 对于数组和对象请传入函数：optional(array(string()), () => [])。否则所有结果会共享同一个数组。
• 在 pipe 外层使用：optional(pipe(string(), email()))。反过来 —— pipe(optional(...), email()) —— TypeScript 会报错，因为 email 无法处理 undefined。

示例

选填字段

const Profile = object({
  name: string(),
  website: optional(pipe(string(), pattern(/^https?:\/\//))),
  lang: optional(oneOf(['zh', 'en']), 'zh'),
});

validate(Profile, { name: 'Li', website: '' }).data; // { name: 'Li', lang: 'zh' }

另请参阅

• nullable
• 空值