TypeScript如何定义强制要求使用as const的字面量类型及泛型约束

一、强制变量声明必须加as const的实现 #

有两种常用方案，按需选择：

方案1：工具函数实现（推荐，使用更便捷） #

利用const泛型封装校验函数，调用时自动校验是否添加了const断言：

function defineLiteral<const T>(value: T) {
  return value
}

// 测试效果
const num0 = defineLiteral(123) // 报错，推导类型为宽泛的number，不符合字面量要求
const num = defineLiteral(123 as const) // 正常，推导类型为字面量123
const str = defineLiteral('str' as const) // 正常
const arr = defineLiteral([1,2,3] as const) // 正常
const obj0 = defineLiteral({name:'lili'}) // 报错
const obj1 = defineLiteral({name:'lili'} as const) // 正常

方案2：自定义类型实现 #

如果需要用类型注解的方式约束，先定义IsLiteral工具类型判断值是否为const断言后的字面量：

type IsLiteral<T> = 
  T extends string ? string extends T ? false : true :
  T extends number ? number extends T ? false : true :
  T extends boolean ? boolean extends T ? false : true :
  T extends readonly unknown[] ? unknown[] extends T ? false : true :
  T extends object ? { -readonly [K in keyof T]: T[K] } extends T ? false : true :
  false

// 约束类型
type Literal<T> = IsLiteral<T> extends true ? T : never

// 测试效果
const num0: Literal<typeof num0> = 123 // 报错
const num: Literal<typeof num> = 123 as const // 正常
const str: Literal<typeof str> = 'str' as const // 正常

二、泛型入参强制为字面量的实现 #

TS 5.0及以上版本可以直接使用const泛型修饰符，无需额外写复杂的类型判断，完全符合你的预期效果：

// 直接在泛型T前加const修饰符
function foo<const T>(obj: { literal: T }) {}

// 测试效果
foo({ literal: 123 as const }) // ok
foo({ literal: [1,2,3] }) // 报错，推导类型为number[]而非只读字面量数组
foo({ literal: [1,2,3] as const }) // ok
foo({ literal: {name:'li'} as const }) // ok
foo({ literal: {name:'li'} }) // 报错

如果使用低于TS5.0的版本，可以配合上文的IsLiteral工具类型实现约束：

function foo<T>(obj: { literal: IsLiteral<T> extends true ? T : never }) {}

三、组件文档默认值显示字面量类型的方案 #

组件文档的类型显示依赖TS的类型推导结果，只需做到两点即可：

1. 声明默认值时添加as const，避免默认值被推导为宽泛的通用类型：

// 错误写法：默认值推导为string类型，文档会显示size默认值为string
type BadProps = {
  size?: 'small' | 'middle' | 'large'
}
const BadComponent = (props: BadProps) => {
  const { size = 'middle' } = props 
  // ...
}

// 正确写法：默认值加as const，推导为字面量'middle'，文档会显示字面量类型
type GoodProps = {
  size?: 'small' | 'middle' | 'large'
}
const GoodComponent = (props: GoodProps) => {
  const { size = 'middle' as const } = props 
  // ...
}

2. 自动生成文档的工具（比如TypeDoc、Storybook）会直接读取TS推导的字面量类型，无需额外配置。

注意事项 #

• 建议升级到TS5.0及以上版本使用const泛型，写法更简洁无额外心智负担
• 如果业务需要允许对象/数组部分层级可变，调整IsLiteral的判断逻辑适配即可

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