事件名决定数据:关联与参数配对

组合泛型订阅、载荷收窄与元组联合,区分事件 API 两侧的关联要求。

本章目录CONTENTS ↓

订阅 saved 时,回调应拿到带 id 的数据;发送 progress 时,则必须配上 percent。若两个位置分别接受全部名称和全部载荷,拼错配对也会通过。

订阅需要把已知名称的信息传给回调,因此先用泛型和索引连接两处。发送还需要约束同时传入的一整组参数;当名称本身是联合时,单个泛型索引未必够用。下面让这个反例引出元组联合。本章只研究声明,不实现事件系统的订阅存储、生命周期或分发策略。

订阅:让回调跟随事件名

type AppEvents = {
saved: { id: string };
progress: { percent: number };
};
declare function on<K extends keyof AppEvents>(
name: K,
handler: (event: AppEvents[K]) => void
): void;
on("saved", event => {
console.log(event.id.toUpperCase());
// @ts-expect-error saved 的载荷没有 percent
console.log(event.percent);
});

K 记录调用处的名称类型,AppEvents[K] 读取对应载荷;回调参数从期望签名获得上下文类型。约束 keyof AppEvents 定义允许的范围,不强迫每次 K 都取完整联合。

内层 void 表示订阅 API 不依赖回调结果,外层 void 描述 on 自己的结果。返回其他值的回调仍可能满足这个契约;详细规则集中在函数兼容性。本章的 declare 只提供类型签名,没有运行时订阅或分发实现。

名称不确定时,回调需要处理全部候选

const eventName = Math.random() > 0.5 ? "saved" : "progress";
on(eventName, event => {
if ("percent" in event) {
console.log(event.percent.toFixed(0));
} else {
console.log(event.id.toUpperCase());
}
});

此时 K 是名称联合,回调接收载荷联合。检查载荷本身能排除不适用的成员;检查外部名称却不会重新推导这次调用的 K。

on(eventName, event => {
if (eventName === "progress") {
// @ts-expect-error 这个签名没有提供外部名称与 event 的联动收窄
console.log(event.percent);
}
});
if (eventName === "progress") {
on(eventName, event => console.log(event.percent));
}

第二种写法先收窄再调用,调用处已经知道名称是 progress,因此回调只接收进度载荷。区别在于推导时有哪些静态信息,而不是编译器是否知道运行时选中了哪个名字。

发送:把整组合法参数作为联合成员

发送者需要同时提供名称和数据。下面的泛型签名对联合名称允许了不够严格的组合。

declare function emitLoose<K extends keyof AppEvents>(name: K, data: AppEvents[K]): void;
emitLoose(eventName, { percent: 50 }); // 通过,但运行时名称可能是 saved

K 为名称联合时,第二个参数只需属于载荷联合。若必须保证整组参数匹配,应先为每个名称构造完整参数元组,再取联合。

type EventArgs<E> = {
[K in keyof E]: [name: K, data: E[K]]
}[keyof E];
declare function emit(...args: EventArgs<AppEvents>): void;
emit("saved", { id: "a" });
emit("progress", { percent: 50 });
// @ts-expect-error 具体名称和数据不匹配
emit("saved", { percent: 50 });
// @ts-expect-error 联合名称不能保证与这份数据配对
emit(eventName, { percent: 50 });
const pair: EventArgs<AppEvents> = Math.random() > 0.5
? ["saved", { id: "a" }]
: ["progress", { percent: 50 }];
emit(...pair);

中间映射的每个值都是一套合法调用参数。索引只把这些完整值组成联合,最终得到 ["saved", { id: string }] | ["progress", { percent: number }]。需要传递不确定的事件时,应传递一份已经保持关联的 pair。

实现中继续使用同一份关联

function inspectEvent(...args: EventArgs<AppEvents>): string {
const [name, data] = args;
if (name === "progress") return data.percent.toFixed(0);
return data.id.toUpperCase();
}

名称和值来自同一可辨识元组联合,const 解构保留了这里的关联。两个独立联合参数没有这项保证;let 解构也不具备本例这种关联收窄。单独重新赋值一个变量不会同步改变另一个变量或原元组。

参数处同样可以写 ...[name, data]: EventArgs<AppEvents>,在解构参数不被重新赋值的前提下保留相关参数收窄。带 ... 的 rest 形式接收多个实参;不带它的 [name, data]: EventArgs<AppEvents> 接收一个元组实参。需要时查 TypeScript 4.6 的相关参数与解构收窄。const 不代表对象深度不可变。

已有事件联合时,复用现有模型

type AppEvent =
| { kind: "saved"; id: string }
| { kind: "failed"; error: string }
| { kind: "progress"; percent: number };
type EventOf<K extends AppEvent["kind"]> = Extract<AppEvent, { kind: K }>;
type Handlers<E extends { kind: string }> = {
[K in E["kind"]]: (event: Extract<E, { kind: K }>) => void
};
const handlers: Handlers<AppEvent> = {
saved: event => console.log(event.id),
failed: event => console.log(event.error),
progress: event => console.log(event.percent),
};

Extract 保留匹配的完整成员。E["kind"] 取得名称的值联合,keyof E 取得对象键,二者不同。处理器表需要最终结果仍是对象,因此不追加取值索引。

按需订阅时 on 更合适;需要每种事件都提供逻辑时,完整处理器表能检查遗漏。动态分发的实现仍需单独处理,声明正确不代表任意索引调用都自动安全。

本章事件表使用必填属性和具体名称。可选事件、开放字符串索引等场景需重新检查生成结果。核心设计过程是:识别必须共同变化的信息 → 在一个成员中配对 → 再允许成员之间选择。

把这套机制用于真实库声明,见 DOM 事件声明:addEventListener 组合已知事件名的泛型重载与一般 string 的后备重载,并展示字面量、联合和宽类型怎样影响回调精度。

官方入口:Generics、Mapped Types、Extract。类型操作可回查映射与分配,阅读路线见全景。

这一页,先记到这里。