事件名决定数据:关联与参数配对
组合泛型订阅、载荷收窄与元组联合,区分事件 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 }); // 通过,但运行时名称可能是 savedK 为名称联合时,第二个参数只需属于载荷联合。若必须保证整组参数匹配,应先为每个名称构造完整参数元组,再取联合。
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 的后备重载,并展示字面量、联合和宽类型怎样影响回调精度。
这一页,先记到这里。