TypeScript字面量联合类型非合规值的默认值设置方案

核心思路 #

你的库需要兼容无类型校验的JavaScript项目，因此必须在运行时对传入的size值做合法性检查，同时在TypeScript层面保证类型安全，避免重复手动校验。

具体实现步骤 #

1. 定义合法尺寸集合（用于运行时快速校验）

const VALID_SIZES = new Set(["small", "medium", "large"]);

2. 编写尺寸归一化工具函数
   这个函数负责接收任意字符串（或undefined），返回合法的尺寸类型，非法值自动 fallback 到medium：

function normalizeSize(size?: string): "small" | "medium" | "large" {
  if (size && VALID_SIZES.has(size)) {
    return size as "small" | "medium" | "large";
  }
  return "medium";
}

3. 在库的对外API中使用该工具函数
   不管是暴露的函数、组件还是类，都通过这个工具函数处理size参数，后续逻辑直接使用归一化后的值：

// 示例：对外暴露的组件初始化函数
export function initComponent(options?: { size?: string }) {
  const finalSize = normalizeSize(options?.size);
  // 后续业务逻辑直接用finalSize，类型完全符合预期
  mountComponent({ size: finalSize });
}

方案优势 #

• 运行时安全：JS用户传入任意非法字符串（比如"super_small"）都会被自动修正为medium，不会导致后续逻辑出错
• 类型安全：归一化函数的返回值是严格的联合类型，TS用户使用时能获得完整的类型提示，库内部代码无需再做类型检查
• 易维护：后续新增合法尺寸，只需修改VALID_SIZES集合和函数返回类型，无需改动多处校验逻辑

内容的提问来源于stack exchange，提问作者Kceen HD