Web事件接口

September 15, 2024

原理

事件机制为发布订阅模式，属于观察者模式的变种。
观察者模式，简单来说，存在两类：目标（发布者）和观察者（订阅者），目标持有其所有观察者的引用和状态，观察者提供一个接受目标的接口（以消费目标的状态）。
发布订阅模式在目标和观察者之间引入了一个消息代理 (Message Broker)或事件总线 (Event Bus)（事件=消息）。事件总线负责接收和分发事件，发布和订阅者双方都完全不需要知道对方的存在。

库实现

这里展示几个轻量级的库作为演示

nanoevents

源码中包含 d.ts 类型

nanoevents 库只能作为一个实现示例，但我个人不建议在生产中使用它。

//prettier-ignore
export let createNanoEvents = () => ({
  emit(event, ...args) {
    for (
      let i = 0,
        callbacks = this.events[event] || [],
        length = callbacks.length;
      i < length;
      i++
    ) {
      callbacks[i](...args)
    }
  },
  events: {},
  on(event, cb) {
    ;(this.events[event] ||= []).push(cb)
    return () => {
      this.events[event] = this.events[event]?.filter(i => cb !== i)
    }
  }
})

mitt

源码为 ts 实现，为缩短篇幅转换为 js

mitt 库支持通配符，类型支持完善，适用于普通场景。

export default function mitt(all) {
    all = all || new Map();
    return {
        all,
        on(type, handler) {
            const handlers = all.get(type);
            if (handlers) {
                handlers.push(handler);
            } else {
                all.set(type, [handler]);
            }
        },

        off(type, handler) {
            const handlers = all.get(type);
            if (handlers) {
                if (handler) {
                    // n >>> 0 这里的有符号右移 0 位对非负数肯定是无影响的
                    // 对于负数，这里只可能是 -1
                    // -1 >>> 0 = 4294967295
                    handlers.splice(handlers.indexOf(handler) >>> 0, 1);
                } else {
                    all.set(type, []);
                }
            }
        },

        emit(type, evt) {
            let handlers = all.get(type);
            if (handlers) {
                // .slice() 防止直接在原数组上迭代
                // 处理在事件处理过程中修改 handlers 数组情况
                handlers.slice().map((handler) => {
                    handler(evt);
                });
            }
            handlers = all.get("*");
            if (handlers) {
                handlers.slice().map((handler) => {
                    handler(type, evt);
                });
            }
        },
    };
}

Web Events

可以看出，实现基础的发布订阅机制非常简单

核心在于两个基类 EventTarget Event
注意它们曾经只是接口，但现在（在现代浏览器中）可直接通过 new 构造，特别是 Event 的子类
为了区分性，提供一个 CustomEvent，以表示任意应用程序事件

WHATWG Reference
Event EventTarget

class EventTarget {
    /**
     * 为类型属性值为 `type` 的事件添加事件监听器。`callback` 参数设置事件分发时将被调用的回调函数。
     *
     * `options` 参数设置监听器特定的选项。为了兼容性，它可以是一个布尔值，在这种情况下，方法的行为与将值指定为 `options` 的 `capture` 相同。
     *
     * `options` 的 `capture` 为 `true` 表示阻止事件的 `eventPhase` 属性值为 `BUBBLING_PHASE` 时调用 `callback`。
     * 为 `false`（或不存在）时，`callback` 不会在事件的 `eventPhase` 属性值为 `CAPTURING_PHASE` 时被调用。
     * 无论哪种方式，如果事件的 `eventPhase` 属性值为 `AT_TARGET`，`callback` 将被调用。
     *
     * `options` 的 `passive` 为 `true` 表示回调函数不会通过调用 `preventDefault()` 来取消事件。这是用于启用 [§ 2.8 观察事件监听器](https://dom.spec.whatwg.org/#observing-event-listeners)中描述的性能优化。
     *
     * `options` 的 `once` 为 `true` 表示回调函数只会被调用一次，之后事件监听器就会被移除。
     *
     * 如果为 `options` 的 `signal` 传递了 `AbortSignal`，则当 `signal` 被中止时，事件监听器将被移除。
     *
     * 事件监听器被追加到 `target` 的事件监听器列表中，如果它具有相同的类型、回调函数和捕获方式，则不会被追加。
     */
    addEventListener(
        type: string,
        callback: EventListenerOrEventListenerObject | null,
        options?: AddEventListenerOptions | boolean,
    ): void;
    /**
     * 将合成事件 `event` 分发到 `target`，如果事件的 `cancelable` 属性值为 `false` 或其 `preventDefault()` 方法没有被调用，则返回 `true`，否则返回 `false`。
     */
    dispatchEvent(event: Event): boolean;
    /**
     * 从 `target` 的事件监听器列表中移除具有相同类型、回调函数和选项的事件监听器。
     */
    removeEventListener(
        type: string,
        callback: EventListenerOrEventListenerObject | null,
        options?: EventListenerOptions | boolean,
    ): void;
}

type EventListenerOrEventListenerObject = EventListener | EventListenerObject;
interface EventListener {
    (evt: Event): void;
}
interface EventListenerObject {
    handleEvent(object: Event): void;
}
interface EventListenerOptions {
    capture?: boolean;
}

与事件相关的 Web API 基本都使用它们，但最具代表性的还是 DOM Events。

观察 Event 基类，事件具有 eventPhase 属性，可表示事件处于捕获或冒泡阶段（NONE/CAPTURING_PHASE/AT_TARGET/BUBBLING_PHASE）
这是为了实现事件委托机制：DOM 事件大部分都是先捕获阶段，然后才是目标阶段，最后是冒泡阶段。

我们只需考虑反例即可：

一些较老的，非标准化的事件： 例如 focus, blur, change 等，这些事件在某些浏览器中可能不支持捕获阶段，或者行为不一致。

一些特定类型的事件：

load: 该事件在页面加载完成后触发，只会在目标阶段触发一次，没有捕获和冒泡阶段。

unload: 该事件在页面卸载时触发，类似于 load 事件，也只会在目标阶段触发一次。

scroll: 该事件在滚动条滚动时触发，通常只在目标阶段触发。

resize: 该事件在窗口或元素大小发生改变时触发，通常只在目标阶段触发。

直接在元素上触发的鼠标事件： 例如使用 element.click() 触发的 click 事件，只会执行目标阶段和冒泡阶段，没有捕获阶段。

自定义事件： 默认情况下，使用 dispatchEvent 触发的自定义事件只可能有冒泡阶段。
可以通过设置 Event 构造函数的 bubbles 参数为 true 来启用冒泡，但是无法启用捕获阶段。

根据 DOM 规范，每个 EventTarget 对象都关联一个 get the parent 算法，接受一个 Event 并返回 EventTarget。
显然，DOM 节点（Node）等接口覆写了该算法。
而手动构造 EventTarget 的 get the parent 算法返回 null，并且不关联 activation 行为。
DOM 是树形结构，因此事件会参与这种树形结构。目前手动构造的 EventTarget 不参与树形结构，但规范也提到未来可能会允许自定义 get the parent 算法。

interface EventInit {
    bubbles?: boolean;
    cancelable?: boolean;
    composed?: boolean;
}

class Event {
    constructor(type: string, eventInitDict?: EventInit);
    /**
     * 返回 true 或 false，具体取决于事件的初始化方式。如果事件按照逆向树序遍历其目标的祖先，则为 true，否则为 false。
     */
    readonly bubbles: boolean;
    /**
     * @deprecated
     */
    cancelBubble: boolean;
    /**
     * 返回 true 或 false，具体取决于事件的初始化方式。其返回值并不总是具有意义，但 true 可能表明事件分发过程中的一部分操作可以通过调用 preventDefault() 方法取消。
     */
    readonly cancelable: boolean;
    /**
     * 返回 true 或 false，具体取决于事件的初始化方式。如果事件调用其目标根节点的 ShadowRoot 节点以外的监听器，则为 true，否则为 false。
     */
    readonly composed: boolean;
    /**
     * 返回当前正在调用其事件监听器回调的函数的对象。
     */
    readonly currentTarget: EventTarget | null;
    /**
     * 如果成功调用 preventDefault() 以指示取消，则返回 true，否则返回 false。
     */
    readonly defaultPrevented: boolean;
    /**
     * 返回事件的阶段，可以是 NONE、CAPTURING_PHASE、AT_TARGET 和 BUBBLING_PHASE 之一。
     */
    readonly eventPhase: number;
    /**
     * 如果事件是由用户代理分发的，则返回 true，否则返回 false。
     */
    readonly isTrusted: boolean;
    /**
     * @deprecated
     */
    returnValue: boolean;
    /**
     * @deprecated
     */
    readonly srcElement: EventTarget | null;
    /**
     * 返回事件分发到的对象（其目标）。
     */
    readonly target: EventTarget | null;
    /**
     * 返回事件的时间戳，以相对于时间原点的毫秒数表示。
     */
    readonly timeStamp: DOMHighResTimeStamp;
    /**
     * 返回事件的类型，例如 "click"、"hashchange" 或 "submit"。
     */
    readonly type: string;
    /**
     * 返回事件路径的调用目标对象（将调用监听器的对象），除了 shadow 树中 shadow 根节点模式为 "closed" 的任何节点，这些节点无法从事件的 currentTarget 访问。
     */
    composedPath(): EventTarget[];
    /**
     * @deprecated
     */
    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
    /**
     * 如果在 cancelable 属性值为 true 时调用，并且在执行事件的监听器时 passive 设置为 false，则向导致事件分发操作发出信号，表明需要取消该操作。
     */
    preventDefault(): void;
    /**
     * 调用此方法可阻止事件到达当前事件运行完成后注册的任何事件监听器，并且当在树中分发时，还可阻止事件到达任何其他对象。
     */
    stopImmediatePropagation(): void;
    /**
     * 当在树中分发时，调用此方法可阻止事件到达除当前对象以外的任何对象。
     */
    stopPropagation(): void;
    readonly NONE: 0;
    readonly CAPTURING_PHASE: 1;
    readonly AT_TARGET: 2;
    readonly BUBBLING_PHASE: 3;
}

当通过编程方式触发 DOM 事件时，事件处理器是同步被调用的：

const et = new EventTarget();
et.addEventListener("test", console.log);
et.dispatchEvent(new Event("test"));
et.dispatchEvent(new CustomEvent("test", { detail: "detail" }));
console.log("main_thread");
// Event -> CustomEvent -> main_thread

const el = document.createElement("a");
el.addEventListener("click", console.log);
el.click();
el.dispatchEvent(new PointerEvent("click"));
console.log("main_thread");
// PointerEvent -> PointerEvent -> main_thread

el.addEventListener("test", console.log);
el.dispatchEvent(new Event("test"));
// 可以监听和派发任意事件

Node.js events

Event Web API

Node.js 也实现了 Web EventTarget 和 Event API，毕竟存在 Node.js 实现的其它 Web API 依赖于此。

关于 Node.js EventTarget 与 DOM EventTarget 的区别，参见官方文档即可。

EventEmitter

本文的主题是 Web Events，因此会省略 Node.js 的事件机制。

Node.js 的 events 模块提供 EventEmitters 类对应于 EventTarget，但没有 Event 对应类。

←Back to home

This work is licensed under CC BY-NC-SA 4.0