为Document的click事件添加类型注解时遇TypeScript类型不兼容问题

我在给Document的click事件添加类型注解时遇到了类型不兼容的错误，代码如下：

type PopupClick = MouseEvent & {
        path: Node[];
};

useEffect(() => {
    const handleClickOutside = (event: MouseEvent) => {
        const _event = event as PopupClick;
        console.log(_event);
        if (
            selectorRef.current &&
            !_event.path.includes(selectorRef.current)
        ) {
            setIsVisible(false);
        }
    };

    document.addEventListener("click", handleClickOutside);
    return () => document.removeEventListener("click", handleClickOutside);
}, []);

运行后出现以下类型错误：

const handleClickOutside: (event: MouseEvent) => void
No overload matches this call.
  Overload 1 of 2, '(type: "click", listener: (this: Document, ev: MouseEvent) => any, options?: boolean | AddEventListenerOptions | undefined): void', gave the following error.
    Argument of type '(event: MouseEvent) => void' is not assignable to parameter of type '(this: Document, ev: MouseEvent) => any'.
      Types of parameters 'event' and 'ev' are incompatible.
        Type 'MouseEvent' is not assignable to type 'MouseEvent<Element, MouseEvent>'.
  Overload 2 of 2, '(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void', gave the following error.
    Argument of type '(event: MouseEvent) => void' is not assignable to parameter of type 'EventListenerOrEventListenerObject'.ts(2769)

我尝试过使用MouseEvent、MouseEvent<Element, MouseEvent>、Mouse event这些类型，但都没解决问题。

问题根源 #

TypeScript中，Document的click事件回调要求的MouseEvent是带泛型参数的具体类型（MouseEvent<Element, MouseEvent>），而你声明的MouseEvent是全局基础类型，二者类型不匹配。另外path属于浏览器非标准扩展属性，直接断言容易引发类型冲突。

解决方案 #

方案1：修正类型并兼容非标准path属性

直接给事件参数指定正确的泛型类型，同时安全断言path属性：

useEffect(() => {
    const handleClickOutside = (event: MouseEvent<Element, MouseEvent>) => {
        const eventWithPath = event as MouseEvent & { path: Node[] };
        if (selectorRef.current && !eventWithPath.path.includes(selectorRef.current)) {
            setIsVisible(false);
        }
    };

    document.addEventListener("click", handleClickOutside);
    return () => document.removeEventListener("click", handleClickOutside);
}, []);

方案2：使用标准API替代非标准path属性

推荐用DOM标准方法composedPath()获取事件传播路径，兼容性更好且无需额外类型断言：

useEffect(() => {
    const handleClickOutside = (event: MouseEvent<Element, MouseEvent>) => {
        const eventPath = event.composedPath();
        if (selectorRef.current && !eventPath.includes(selectorRef.current)) {
            setIsVisible(false);
        }
    };

    document.addEventListener("click", handleClickOutside);
    return () => document.removeEventListener("click", handleClickOutside);
}, []);

关键说明 #

• composedPath()是W3C标准方法，返回事件传播经过的节点数组，支持所有现代浏览器，比非标准的path属性更可靠。
• 给事件回调参数指定MouseEvent<Element, MouseEvent>类型，就能完全匹配Document的click事件要求的参数类型，解决类型不兼容报错。

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