Node.js v18.7.0 文档

将参数和 this 传给监听器#

中英对照

eventEmitter.emit() 方法允许将任意一组参数传给监听器函数。 记住，当调用普通的监听器函数时，标准的 this 关键字会被有意地设置为引用监听器绑定到的 EventEmitter 实例。

异步 VS 同步#

中英对照

EventEmitter 按照注册的顺序同步地调用所有监听器。 这确保了事件的正确排序，并有助于避免竞争条件和逻辑错误。 在适当的时候，监听器函数可以使用 setImmediate() 或 process.nextTick() 方法切换到异步的操作模式：

仅处理事件一次#

中英对照

当使用 eventEmitter.on() 方法注册监听器时，每次触发命名事件时都会调用该监听器。

错误事件#

中英对照

当 EventEmitter 实例中发生错误时，典型的操作是触发 'error' 事件。 这些在 Node.js 中被视为特殊情况。

捕捉 Promise 拒绝#

中英对照

将 async 函数与事件句柄一起使用是有问题的，因为它会在抛出异常的情况下导致未处理的拒绝：

EventEmitter 类#

中英对照

EventEmitter 类由 node:events 模块定义和暴露：

'newListener' 事件#

中英对照

在将监听器添加到其内部监听器数组之前，EventEmitter 实例将触发自身的 'newListener' 事件。

'removeListener' 事件#

中英对照

在移除 listener 后触发 'removeListener' 事件。

emitter.addListener(eventName, listener)#

中英对照

emitter.on(eventName, listener) 的别名。

emitter.emit(eventName[, ...args])#

中英对照

按注册顺序同步地调用为名为 eventName 的事件注册的每个监听器，并将提供的参数传给每个监听器。

emitter.eventNames()#

中英对照

返回列出触发器已为其注册监听器的事件的数组。 数组中的值是字符串或 Symbol。

emitter.getMaxListeners()#

中英对照

返回 EventEmitter 的当前最大监听器数的值，该值由 emitter.setMaxListeners(n) 设置或默认为 events.defaultMaxListeners。

emitter.listenerCount(eventName)#

中英对照

返回监听名为 eventName 的事件的监听器数量。

emitter.listeners(eventName)#

中英对照

返回名为 eventName 的事件的监听器数组的副本。

emitter.off(eventName, listener)#

中英对照

emitter.removeListener() 的别名。

emitter.on(eventName, listener)#

中英对照

将 listener 函数添加到名为 eventName 的事件的监听器数组的末尾。 不检查是否已添加 listener。 多次调用传入相同的 eventName 和 listener 组合将导致多次添加和调用 listener。

emitter.once(eventName, listener)#

中英对照

为名为 eventName 的事件添加单次的 listener 函数。 下次触发 eventName 时，将移除此监听器，然后再调用。

emitter.prependListener(eventName, listener)#

中英对照

将 listener 函数添加到名为 eventName 的事件的监听器数组的开头。 不检查是否已添加 listener。 多次调用传入相同的 eventName 和 listener 组合将导致多次添加和调用 listener。

emitter.prependOnceListener(eventName, listener)#

中英对照

将名为 eventName 的事件的单次 listener 函数添加到监听器数组的开头。 下次触发 eventName 时，将移除此监听器，然后再调用。

emitter.removeAllListeners([eventName])#

中英对照

删除所有监听器，或指定 eventName 的监听器。

emitter.removeListener(eventName, listener)#

中英对照

从名为 eventName 的事件的监听器数组中移除指定的 listener。

emitter.setMaxListeners(n)#

中英对照

默认情况下，如果为特定事件添加了 10 个以上的监听器，则 EventEmitter 将打印警告。 这是一个有用的默认值，有助于查找内存泄漏。 emitter.setMaxListeners() 方法允许修改此特定 EventEmitter 实例的限制。 该值可以设置为 Infinity（或 0）以指示无限数量的监听器。

emitter.rawListeners(eventName)#

中英对照

返回名为 eventName 的事件的监听器数组的副本，包括任何封装器（例如由 .once() 创建的封装器）。

emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])#

中英对照

Symbol.for('nodejs.rejection') 方法被调用，以防在触发事件时发生 promise 拒绝，并且在触发器上启用了 captureRejections。 可以使用 events.captureRejectionSymbol 代替 Symbol.for('nodejs.rejection')。

events.defaultMaxListeners#

中英对照

默认情况下，最多可为任何单个事件注册 10 个监听器。 可以使用 emitter.setMaxListeners(n) 方法为单个 EventEmitter 实例更改此限制。 要更改所有 EventEmitter 实例的默认值，则可以使用 events.defaultMaxListeners 属性。 如果该值不是正数，则抛出 RangeError。

events.errorMonitor#

中英对照

此符号应用于安装仅监视 'error' 事件的监听器。 在调用常规 'error' 监听器之前调用使用此符号安装的监听器。

events.getEventListeners(emitterOrTarget, eventName)#

中英对照

返回名为 eventName 的事件的监听器数组的副本。

events.once(emitter, name[, options])#

中英对照

创建 Promise，其在 EventEmitter 触发给定事件时被履行，或者如果 EventEmitter 在等待时触发 'error' 则被拒绝。 Promise 将使用触发给定事件的所有参数的数组解决。

等待 process.nextTick() 上触发的多个事件#

中英对照

当使用 events.once() 函数等待在同一批 process.nextTick() 操作中触发的多个事件时，或者同步触发多个事件时，有一个边缘情况值得注意。 具体来说，因为 process.nextTick() 队列在 Promise 微任务队列之前被排空，并且因为 EventEmitter 同步触发所有事件，所以 events.once() 有可能错过事件。

events.captureRejections#

中英对照

值: <boolean>

events.captureRejectionSymbol#

中英对照

值: Symbol.for('nodejs.rejection')

events.listenerCount(emitter, eventName)#

中英对照

返回在给定 emitter 上注册的给定 eventName 的监听器数量的类方法。

events.on(emitter, eventName[, options])#

中英对照

返回迭代 eventName 事件的 AsyncIterator。 如果 EventEmitter 触发 'error'，则将抛出错误。 它在退出循环时删除所有监听器。 每次迭代返回的 value 是由触发的事件参数组成的数组。

events.setMaxListeners(n[, ...eventTargets])#

中英对照

events.EventEmitterAsyncResource 类继承 EventEmitter 类#

中英对照

为需要手动异步跟踪的 EventEmitter 集成 EventEmitter 和 <AsyncResource>。 具体来说，events.EventEmitterAsyncResource 实例触发的所有事件都将在其异步上下文中运行。

new events.EventEmitterAsyncResource(options)#

中英对照

eventemitterasyncresource.asyncId#

中英对照

eventemitterasyncresource.asyncResource#

中英对照

返回的 AsyncResource 对象具有额外的 eventEmitter 属性，提供对此 EventEmitterAsyncResource 的引用。

eventemitterasyncresource.emitDestroy()#

中英对照

调用所有的 destroy 钩子。 这应该只被调用一次。 如果多次调用，则会报错。 这个必须手动调用。 如果资源留给 GC 收集，则永远不会调用 destroy 钩子。

eventemitterasyncresource.triggerAsyncId#

中英对照

EventTarget 与 Event API#

中英对照

EventTarget 和 Event 对象是一些 Node.js 核心 API 暴露的 EventTarget Web API 的特定于 Node.js 的实现。

Node.js EventTarget 对比 DOM EventTarge#

中英对照

Node.js EventTarget 和 EventTarget Web API 之间有两个主要区别：

NodeEventTarget 对比 EventEmitter#

中英对照

NodeEventTarget 对象实现了 EventEmitter API 的修改子集，允许它在某些情况下接近地模拟 EventEmitter。 NodeEventTarget 不是 EventEmitter 的实例，在大多数情况下不能代替 EventEmitter。

事件监听器#

中英对照

为事件 type 注册的事件监听器可以是 JavaScript 函数，也可以是具有值为函数的 handleEvent 属性的对象。

EventTarget 的错误处理#

中英对照

当注册的事件监听器抛出错误（或返回拒绝的 Promise）时，默认情况下，错误将被视为 process.nextTick() 上的未捕获异常。 这意味着 EventTarget 中未捕获的异常将默认终止 Node.js 进程。

Event 类#

中英对照

Event 对象是对 Event Web API 的改写。 实例由 Node.js 在内部创建。

event.bubbles#

中英对照

这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.cancelBubble()#

中英对照

event.stopPropagation() 的别名。 这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.cancelable#

中英对照

event.composed#

中英对照

这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.composedPath()#

中英对照

返回包含当前 EventTarget 作为唯一条目的数组，如果未调度事件则返回空数组。 这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.currentTarget#

中英对照

event.target 的别名。

event.defaultPrevented#

中英对照

如果 cancelable 为 true 且 event.preventDefault() 已被调用，则为 true。

event.eventPhase#

中英对照

这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.isTrusted#

中英对照

<AbortSignal> "abort" 事件是在 isTrusted 设置为 true 的情况下触发的。 在所有其他情况下，该值为 false。

event.preventDefault()#

中英对照

如果 cancelable 是 true，则将 defaultPrevented 属性设置为 true。

event.returnValue#

中英对照

这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.srcElement#

中英对照

event.target 的别名。

event.stopImmediatePropagation()#

中英对照

当前事件监听器完成后停止调用。

event.stopPropagation()#

中英对照

这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.target#

中英对照

event.timeStamp#

中英对照

创建 Event 对象时的毫秒时间戳。

event.type#

中英对照

事件类型标识符。

EventTarget 类#

中英对照

eventTarget.addEventListener(type, listener[, options])#

中英对照

为 type 事件添加新的句柄。 对于每个 type 和每个 capture 选项值，任何给定的 listener 仅添加一次。

eventTarget.dispatchEvent(event)#

中英对照

将 event 调度到 event.type 的句柄列表。

eventTarget.removeEventListener(type, listener)#

中英对照

从事件 type 的句柄列表中删除 listener。

CustomEvent 类#

中英对照

CustomEvent 对象是对 CustomEvent Web API 的改写。 实例由 Node.js 在内部创建。

event.detail#

中英对照

只读。

NodeEventTarget 类#

中英对照

NodeEventTarget 是 EventTarget 的 Node.js 特定扩展，它模拟了 EventEmitter API 的子集。

nodeEventTarget.addListener(type, listener[, options])#

中英对照

EventTarget 类的 Node.js 特定扩展，可模拟等效的 EventEmitter API。 addListener() 和 addEventListener() 之间的唯一区别是 addListener() 将返回对 EventTarget 的引用。

nodeEventTarget.eventNames()#

中英对照

Node.js 特定于 EventTarget 类的扩展，它返回事件 type 名称的数组，事件监听器注册了这些名称。

nodeEventTarget.listenerCount(type)#

中英对照

EventTarget 类的 Node.js 特定扩展，返回为 type 注册的事件监听器的数量。

nodeEventTarget.off(type, listener)#

中英对照

eventTarget.removeListener() 的 Node.js 特定别名。

nodeEventTarget.on(type, listener[, options])#

中英对照

eventTarget.addListener() 的 Node.js 特定别名。

nodeEventTarget.once(type, listener[, options])#

中英对照

EventTarget 类的 Node.js 特定扩展，它为给定的事件 type 添加了 once 监听器。 这相当于调用 on 并将 once 选项设置为 true。

nodeEventTarget.removeAllListeners([type])#

中英对照

EventTarget 类的 Node.js 特定扩展。 如果指定了 type，则删除 type 的所有注册监听器，否则删除所有注册的监听器。

nodeEventTarget.removeListener(type, listener)#

中英对照

Node.js 特定于 EventTarget 类的扩展，用于删除给定 type 的 listener。 removeListener() 和 removeEventListener() 之间的唯一区别是 removeListener() 将返回对 EventTarget 的引用。