TypeScript 模板字面量类型怎么约束事件名

如果事件名直接写成 string，调用方可以把属性名、拼写错误甚至无关字符串传进来，编辑器也无法提醒。TypeScript 的模板字面量类型可以把对象键拼成固定模式，例如把 title 变成 titleChanged，再用泛型把这个事件对应的回调参数绑定到 title 的类型。

核心做法是先用 `${string & keyof Type}Changed` 限制事件名，再把事件键捕获为 Key，通过 Type[Key] 推导回调参数。这样事件名和数据类型来自同一个对象，不需要维护两份字符串联合类型。

先把属性键变成受限事件名

假设一个表单对象有 title、count 两个属性，事件约定为属性名后追加 Changed。最小的类型可以这样写：

type EventName = `${string & keyof T}Changed`;

type FormState = {
  title: string;
  count: number;
};

function listen(name: EventName, handler: (value: unknown) => void) {
  // 示例只演示类型约束，真实项目应在这里保存监听器。
  console.log(name, handler);
}

listen("titleChanged", value => console.log(value));
// 下面两行都会被 TypeScript 拒绝：属性名未追加 Changed，或属性名拼错。
listen("title", value => console.log(value));
listen("titelChanged", value => console.log(value));

keyof T 先得到属性键联合，string & keyof T 确保它能放进字符串模板位置，最后模板字面量把每个键拼成新的字符串联合。这里仍然使用了 unknown，因为事件名和回调参数还没有建立一一对应关系。

用泛型让回调参数跟随事件键

要让 titleChanged 的回调收到 string，让 countChanged 的回调收到 number，不能只把事件名写成一个完整字符串联合，而应让泛型捕获事件对应的键：

type EventSource = {
  on(
    eventName: `${Key}Changed`,
    callback: (value: Type[Key]) => void
  ): void;
};

declare function makeEventSource(state: Type): Type & EventSource;

const form = makeEventSource({ title: "草稿", count: 1 });
form.on("titleChanged", value => {
  // value 被推导为 string，可直接使用字符串方法。
  console.log(value.toUpperCase());
});
form.on("countChanged", value => {
  // value 被推导为 number，避免把数字当成字符串处理。
  console.log(value.toFixed(0));
});

这里的关键不是字符串拼接本身，而是 Key 同时出现在两个位置：一边参与生成事件名，另一边通过索引访问类型 Type[Key]。调用时传入的字面量会被捕获，编辑器就能把事件名与属性值类型配对。

把约束放进真实事件接口

在组件或状态对象中，通常将 EventSource 与原对象交叉组合。这样读者可以访问原属性，也可以调用 on，而不需要手写每个事件：

type Watched = Type & EventSource;

function createWatched(state: Type): Watched {
  // 运行时实现应保存监听器并在属性变更时触发；这里返回类型示意。
  return state as Watched;
}

const settings = createWatched({ enabled: true, retry: 3 });
settings.on("enabledChanged", enabled => {
  // enabled 是 boolean，调用方不必再写类型断言。
  if (enabled) console.log("enabled");
});

类型安全只约束编译阶段，运行时仍需真正实现订阅、触发和取消订阅。如果事件名来自接口响应、输入框或普通 string 变量，TypeScript 无法凭空知道它属于哪个键；这时应先做白名单校验，或者把数据转换成保留字面量的联合类型。

动态字符串和可选属性要单独处理

模板字面量类型最适合事件集合有限且能从对象结构推导的场景。下面几类情况要留意：

• 变量声明为 string 后，事件名的具体字面量已经丢失；可以使用 as const 保存常量字面量，但不要用断言掩盖未经校验的外部输入。
• 可选属性的回调值可能包含 undefined，应在回调里先判断，而不是把它强行断言成必有值。
• 对象键很多时，模板字面量会产生较大的联合类型；可按领域拆成多个事件源，避免一个接口承载所有事件。

因此，事件名约束解决的是“字符串和对象键不一致”的编译期问题，不替代运行时事件总线的权限、生命周期和异常处理。把事件源限制在明确的状态对象上，通常比把所有事件放宽为 string 更容易维护。

常见问题 FAQ

为什么不能只写 `${key}Changed`？

如果 key 的类型是普通 string，结果仍然可以代表任意字符串。必须让它来自 keyof Type，编译器才知道允许哪些属性键。

事件名合法但回调类型还是不准确怎么办？

检查是否把回调参数写成了 any 或 unknown，以及是否让同一个泛型 Key 同时出现在事件名和 Type[Key] 中。只有事件名模式本身，不能完成值类型关联。