如何通过TypeScript声明合并重写Event接口的type属性类型？

内置类型声明 #

TypeScript的lib.dom.d.ts中，Event和GlobalEventHandlersEventMap的基础声明如下：

interface Event {
    /**
     * 返回事件类型，例如"click"、"hashchange"或"submit"。
     */
    readonly type: string;   // 注意此处类型为string
}

interface GlobalEventHandlersEventMap {
    click: MouseEvent;
    //... 其他各类内置事件...
}

自定义类与问题场景 #

我定义了EventTriggered类，要求构造函数参数必须是GlobalEventHandlersEventMap的属性名：

class EventTriggered {
    constructor(
        readonly eventName: keyof GlobalEventHandlersEventMap
    ) {}
}

直接传入合法事件名（比如new EventTriggered('click')）可以正常运行，传入随机字符串会报错，符合预期。但在事件监听器中使用时，因为event.type的类型是string，导致代码报错：

function onClick(event: Event): void {
    new EventTriggered(event.type); // 类型错误：string不能赋值给keyof GlobalEventHandlersEventMap
}

尝试的解决方法及问题 #

我尝试通过声明合并修改Event的type属性类型：

// global.d.ts
interface Event {
    readonly type: keyof GlobalEventHandlersEventMap;
}

但原错误依然存在，且IDE显示type有两个冲突的声明——这是因为TypeScript的声明合并中，相同属性的不同类型会被合并为联合类型（string | keyof GlobalEventHandlersEventMap），依然无法直接匹配EventTriggered的参数要求。

正确解决思路 #

方案1：类型收窄（推荐） #

通过类型守卫或条件判断，将event.type的类型收窄为keyof GlobalEventHandlersEventMap，既保留类型安全，又避免断言的滥用：

// 定义类型守卫函数
function isGlobalEventKey(type: string): type is keyof GlobalEventHandlersEventMap {
    return type in GlobalEventHandlersEventMap;
}

function onClick(event: Event): void {
    if (isGlobalEventKey(event.type)) {
        // 此时event.type已被收窄为目标类型
        new EventTriggered(event.type);
    } else {
        // 处理未知事件类型的边界情况
        console.warn(`未识别的事件类型：${event.type}`);
    }
}

方案2：全局类型扩充（谨慎使用） #

如果确定业务中不会用到自定义事件，可以通过全局模块扩充的方式覆盖Event.type的类型，注意必须将文件标记为模块（添加export {}）：

// global.d.ts
declare global {
    interface Event {
        readonly type: keyof GlobalEventHandlersEventMap;
    }
}

export {}; // 必须添加，使文件成为模块

⚠️ 注意：这种方法会全局修改Event的类型，若后续使用自定义事件（比如new Event('custom-event')），会出现类型错误，需谨慎评估场景。

方案3：构造函数重载（不推荐） #

给EventTriggered添加兼容string的构造函数重载，但会丢失非法字符串的类型检查：

class EventTriggered {
    constructor(readonly eventName: keyof GlobalEventHandlersEventMap);
    constructor(readonly eventName: string);
    constructor(readonly eventName: string) {}
}

此方法虽能解决当前报错，但new EventTriggered('some-random-string')也会通过编译，失去了原本的类型校验意义。

内容的提问来源于stack exchange，提问作者Christian