字段名怎样变成事件名:模板字面量与键重映射

从字段变更事件出发,推导字符串类型的构造、键重命名和反向提取,并保持字段与载荷关联。

本章目录CONTENTS ↓

一个编辑器约定:标题改变时发送 titleChanged,是否启用改变时发送 enabledChanged。标题事件携带字符串,启用事件携带布尔值。字段已经定义过一次,事件名和载荷能否从它派生,并随着字段修改而变化?

把事件名写成 string 会放过拼写错误;手写事件名联合可以限制名称,却仍需手动同步字段。需要的操作分成两步:先用原字段名构造新名字,再让新名字对应原字段的值类型。模板字面量类型完成字符串构造,映射类型中的 as 完成键重命名。

先得到允许的名字

type Fields = { title: string; enabled: boolean };
type FieldKey = keyof Fields; // "title" | "enabled"
type ChangeName = `${FieldKey}Changed`;
// "titleChanged" | "enabledChanged"
const name: ChangeName = "titleChanged";
// @ts-expect-error 原字段名不满足事件命名规则
const missingSuffix: ChangeName = "title";
// @ts-expect-error 不存在这个字段
const unknownName: ChangeName = "countChanged";

模板位置的联合会展开成各个字符串的组合。本例只有一个位置,相当于分别给 title 和 enabled 加上后缀。这里得到的是字符串类型,没有创建事件名数组,更没有发送事件。

若有多个联合位置,例如语言名与页面名,结果会包含它们的交叉组合。需要配对的两组信息不能仅靠分别放进两个模板位置来保持关联。

有名字还不够,载荷也要跟随字段

type ChangeEvents<T> = {
[K in keyof T & string as `${K}Changed`]: T[K]
};
type EditorEvents = ChangeEvents<Fields>;
// { titleChanged: string; enabledChanged: boolean }

按一个键走完这条计算链:

步骤 K 为 title 时 K 为 enabled 时
选择原键 K "title" "enabled"
生成输出键 "titleChanged" "enabledChanged"
用原键读取值 Fields["title"] Fields["enabled"]
输出属性 titleChanged: string enabledChanged: boolean

as 改的是输出键,K 仍然表示原键,所以右侧能继续读取 T[K]。若改用全部字段值的联合,两个事件都会接受 string 或 boolean,配对就丢失了。

keyof T 也可能包含数字和 symbol,本例只对字符串键生成名字,因此用 & string 选出这部分键。这项限制属于这里的命名契约,不表示对象只能有字符串键。键重映射还可以把不需要的键映射为 never,从输出对象中移除该键;这与保留一个值类型为 never 的属性不同。

把生成的表用于调用

declare function onChange<K extends keyof EditorEvents>(
event: K,
callback: (value: EditorEvents[K]) => void
): void;
onChange("titleChanged", value => value.toUpperCase());
onChange("enabledChanged", value => {
const enabled: boolean = value;
// @ts-expect-error 布尔载荷不能使用字符串方法
value.toUpperCase();
});
// @ts-expect-error 事件表没有该名字
onChange("missingChanged", () => {});

现在名称的合法范围和回调参数都来自同一份事件表。这里的 declare 只声明调用契约,没有事件系统实现。若传入的是联合事件名,回调值也可能是联合,仍需处理全部候选,原理见事件参数配对。

已经拿到一个名字,怎样反查字段

有时输入是一种事件名类型,需要求出它携带的值类型。可以先用模板结构匹配取出后缀前的部分,再检查它是不是原对象的键。

type ValueForEvent<T, Name extends string> =
Name extends `${infer K}Changed`
? K extends keyof T ? T[K] : never
: never;
type TitleValue = ValueForEvent<Fields, "titleChanged">; // string
type EnabledValue = ValueForEvent<Fields, "enabledChanged">; // boolean
type Missing = ValueForEvent<Fields, "missingChanged">; // never
type WrongSuffix = ValueForEvent<Fields, "titleSaved">; // never
type Both = ValueForEvent<Fields, "titleChanged" | "enabledChanged">;
// string | boolean

infer K 提取模板中匹配的位置,但匹配后缀只证明名字的形状,不证明字段存在,因此还需要键检查。Name 是条件左侧的裸类型参数,联合名字会分别匹配再合并结果。

这个工具输出载荷类型,输出本身不再包含事件名。如果需要保存一整条消息的关联,应像字段变更联合一样,先按键生成完整成员,再取成员联合,不能把名字联合与 Both 独立拼接。

本章限定必填、有限的字符串字段;开放的字符串索引签名、可选属性及更复杂的命名规则需要按实际输入检查。类型中的字符串匹配不会解析网络传来的真实文本,也不会验证真实载荷。

官方查阅:Template Literal Types、Key Remapping via as。回到类型编程路线。

这一页,先记到这里。