模板字面量类型是 TypeScript 4.1 引入的编译期字符串结构约束机制,通过反引号定义固定模式,支持联合类型嵌套与大小写工具类型联动,用于精确约束 API 路由、事件名等结构化字符串,但仅作用于类型检查,不提供运行时校验。

模板字面量类型是 TypeScript 4.1 引入的特性,用于在编译期对字符串结构做精确、可计算的类型约束。它不是运行时校验,而是在类型层面描述“合法字符串长什么样”,让非法字符串在写代码时就被拦截。
基础写法:用反引号定义固定模式
最简单的用法是直接写出带插值的模板字符串类型:
-
单个确定值:
type Greeting = `hello world`—— 只允许字面量"hello world" -
结合字符串字面量联合类型:
type Event = `on${'click' | 'input' | 'submit'}`→ 编译后等价于"onclick" | "oninput" | "onsubmit" -
支持嵌套联合:
type Handler = `handle${'Success' | 'Error'}${'Sync' | 'Async'}`→ 生成 4 种组合:"handleSuccessSync"、"handleSuccessAsync"、"handleErrorSync"、"handleErrorAsync"
进阶约束:配合内置工具类型动态推导
模板字面量类型能与 Uppercase、Lowercase、Capitalize、Uncapitalize 等工具类型联动,实现大小写转换类约束:
基于三引擎设计,从微信文章、新闻和博客网页提取干净内容,支持标题作者日期元数据,多格式和批量处理。
-
type ClickEvent = `on${Capitalize}`→"onClick" | "onChange" -
type ApiPath = `/api/${Lowercase}/:id`→"/api/user/:id" | "/api/post/:id" - 注意:这些工具类型只对 ASCII 字母有效,不处理 Unicode 或数字
实用场景:约束 API 路由、事件名、CSS 类名等结构化字符串
当字符串不是任意文本,而是有固定格式的标识符时,模板字面量类型特别有用:
-
路由路径:
type Route = `/user/${number}` | `/post/${string}`(注意:number在模板中会被转为字符串字面量,但需配合运行时校验) -
事件处理器名:
type EventHandlerKey = `on${Capitalize<string>}`</string>(宽松约束,允许任意驼峰 onXXX 形式) -
带前缀的配置项:
type ConfigKey = `theme-${'dark' | 'light' | 'auto'}` → "theme-dark" 等 - 搭配
as const可让字面量推导更准确,例如:const modes = ['dark', 'light'] as const;→ 类型为readonly ["dark", "light"],可用于构建安全联合
注意事项:它只在类型空间生效,不检查运行时值
模板字面量类型不会自动验证变量内容是否符合模式,它只约束声明时的赋值和函数参数传入:
- ✅ 正确:
const e: Event = 'onclick'; - ❌ 报错:
const e: Event = 'onhover';(因为'onhover'不在联合中) - ⚠️ 注意:
let input = prompt(); const x: Event = input;会报错 —— 因为prompt()返回string,而string不能赋给更窄的模板字面量联合类型 - 若需运行时校验,需额外写判断逻辑或使用库(如
zod),类型系统本身不执行字符串解析

















