事件

[Stable: 2 - 稳定]

Node.js 核心 API 的很大一部分是围绕着一种惯用的异步事件驱动架构构建的，在这种架构中，某些类型的对象（称为“发射器”）会发出命名事件，这些事件会导致 Function 对象（“监听器”）被调用。

例如：每当有对等方连接到 net.Server 对象时，该对象都会发出一个事件；当文件被打开时，fs.ReadStream 会发出一个事件；当有数据可供读取时，stream 会发出一个事件。

所有发出事件的对象都是 EventEmitter 类的实例。这些对象公开了一个 eventEmitter.on() 函数，该函数允许将一个或多个函数附加到对象发出的命名事件。通常，事件名称是驼峰式字符串，但可以使用任何有效的 JavaScript 属性键。

当 EventEmitter 对象发出事件时，所有附加到该特定事件的函数都会被同步调用。被调用的监听器返回的任何值都将被忽略和丢弃。

以下示例显示了一个带有单个监听器的简单 EventEmitter 实例。 eventEmitter.on() 方法用于注册监听器，而 eventEmitter.emit() 方法用于触发事件。

ESMCJS

import { EventEmitter } from 'node:events';

class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
myEmitter.on('event', () => {
  console.log('an event occurred!');
});
myEmitter.emit('event');

const EventEmitter = require('node:events');

class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
myEmitter.on('event', () => {
  console.log('an event occurred!');
});
myEmitter.emit('event');

将参数和 `this` 传递给监听器

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

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', function(a, b) {
  console.log(a, b, this, this === myEmitter);
  // Prints:
  //   a b MyEmitter {
  //     _events: [Object: null prototype] { event: [Function (anonymous)] },
  //     _eventsCount: 1,
  //     _maxListeners: undefined,
  //     [Symbol(shapeMode)]: false,
  //     [Symbol(kCapture)]: false
  //   } true
});
myEmitter.emit('event', 'a', 'b');

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', function(a, b) {
  console.log(a, b, this, this === myEmitter);
  // Prints:
  //   a b MyEmitter {
  //     _events: [Object: null prototype] { event: [Function (anonymous)] },
  //     _eventsCount: 1,
  //     _maxListeners: undefined,
  //     [Symbol(shapeMode)]: false,
  //     [Symbol(kCapture)]: false
  //   } true
});
myEmitter.emit('event', 'a', 'b');

可以使用 ES6 箭头函数作为监听器，但是，这样做时，this 关键字将不再引用 EventEmitter 实例：

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  console.log(a, b, this);
  // Prints: a b undefined
});
myEmitter.emit('event', 'a', 'b');

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  console.log(a, b, this);
  // Prints: a b {}
});
myEmitter.emit('event', 'a', 'b');

异步 vs. 同步

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

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  setImmediate(() => {
    console.log('this happens asynchronously');
  });
});
myEmitter.emit('event', 'a', 'b');

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  setImmediate(() => {
    console.log('this happens asynchronously');
  });
});
myEmitter.emit('event', 'a', 'b');

仅处理一次事件

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

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
let m = 0;
myEmitter.on('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// Prints: 1
myEmitter.emit('event');
// Prints: 2

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
let m = 0;
myEmitter.on('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// Prints: 1
myEmitter.emit('event');
// Prints: 2

使用 eventEmitter.once() 方法，可以注册一个监听器，该监听器对于特定事件最多被调用一次。一旦发出该事件，监听器将被注销，然后被调用。

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
let m = 0;
myEmitter.once('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// Prints: 1
myEmitter.emit('event');
// Ignored

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
let m = 0;
myEmitter.once('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// Prints: 1
myEmitter.emit('event');
// Ignored

错误事件

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

如果 EventEmitter 没有至少一个为 'error' 事件注册的监听器，并且触发了 'error' 事件，则会抛出错误，打印堆栈跟踪，并且 Node.js 进程退出。

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// 抛出异常并导致 Node.js 崩溃

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// 抛出异常并导致 Node.js 崩溃

为了防止 Node.js 进程崩溃，可以使用 domain 模块。（但请注意，node:domain 模块已弃用。）

作为最佳实践，应该始终为 'error' 事件添加监听器。

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('error', (err) => {
  console.error('whoops! there was an error');
});
myEmitter.emit('error', new Error('whoops!'));
// 打印: whoops! there was an error

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.on('error', (err) => {
  console.error('whoops! there was an error');
});
myEmitter.emit('error', new Error('whoops!'));
// 打印: whoops! there was an error

可以通过使用符号 events.errorMonitor 安装监听器来监控 'error' 事件，而无需消耗发出的错误。

ESMCJS

import { EventEmitter, errorMonitor } from 'node:events';

const myEmitter = new EventEmitter();
myEmitter.on(errorMonitor, (err) => {
  MyMonitoringTool.log(err);
});
myEmitter.emit('error', new Error('whoops!'));
// 仍然抛出异常并导致 Node.js 崩溃

const { EventEmitter, errorMonitor } = require('node:events');

const myEmitter = new EventEmitter();
myEmitter.on(errorMonitor, (err) => {
  MyMonitoringTool.log(err);
});
myEmitter.emit('error', new Error('whoops!'));
// 仍然抛出异常并导致 Node.js 崩溃

捕获 Promise 的拒绝

将 async 函数与事件处理程序一起使用是有问题的，因为它可能导致在抛出异常时出现未处理的拒绝：

ESMCJS

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();
ee.on('something', async (value) => {
  throw new Error('kaboom');
});

const EventEmitter = require('node:events');
const ee = new EventEmitter();
ee.on('something', async (value) => {
  throw new Error('kaboom');
});

EventEmitter 构造函数中的 captureRejections 选项或全局设置会更改此行为，在 Promise 上安装一个 .then(undefined, handler) 处理程序。此处理程序将异常异步路由到 Symbol.for('nodejs.rejection') 方法（如果存在），或者路由到 'error' 事件处理程序（如果不存在）。

ESMCJS

import { EventEmitter } from 'node:events';
const ee1 = new EventEmitter({ captureRejections: true });
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});

ee1.on('error', console.log);

const ee2 = new EventEmitter({ captureRejections: true });
ee2.on('something', async (value) => {
  throw new Error('kaboom');
});

ee2[Symbol.for('nodejs.rejection')] = console.log;

const EventEmitter = require('node:events');
const ee1 = new EventEmitter({ captureRejections: true });
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});

ee1.on('error', console.log);

const ee2 = new EventEmitter({ captureRejections: true });
ee2.on('something', async (value) => {
  throw new Error('kaboom');
});

ee2[Symbol.for('nodejs.rejection')] = console.log;

设置 events.captureRejections = true 将更改所有新的 EventEmitter 实例的默认值。

ESMCJS

import { EventEmitter } from 'node:events';

EventEmitter.captureRejections = true;
const ee1 = new EventEmitter();
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});

ee1.on('error', console.log);

const events = require('node:events');
events.captureRejections = true;
const ee1 = new events.EventEmitter();
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});

ee1.on('error', console.log);

由 captureRejections 行为生成的 'error' 事件没有 catch 处理程序以避免无限错误循环：建议不要使用 async 函数作为 'error' 事件处理程序。

类: `EventEmitter`

[历史]

版本	变更
v13.4.0, v12.16.0	添加了 captureRejections 选项。
v0.1.26	添加于: v0.1.26

EventEmitter 类由 node:events 模块定义和公开：

ESMCJS

import { EventEmitter } from 'node:events';

const EventEmitter = require('node:events');

当添加新的监听器时，所有的 EventEmitter 都会触发 'newListener' 事件；当移除已存在的监听器时，则触发 'removeListener' 事件。

它支持以下选项：

captureRejections <boolean> 启用自动捕获 Promise 拒绝。 默认: false。

事件: `'newListener'`

添加于: v0.1.26

eventName <string> | <symbol> 正在监听的事件的名称
listener <Function> 事件处理函数

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

为 'newListener' 事件注册的监听器会被传递事件名称和对正在添加的监听器的引用。

事件在添加监听器之前触发这一事实有一个微妙但重要的副作用：任何在 'newListener' 回调函数内部注册到相同 name 的附加监听器都会被插入到正在被添加的监听器之前。

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
// 只执行一次，这样我们不会永远循环
myEmitter.once('newListener', (event, listener) => {
  if (event === 'event') {
    // 在前面插入一个新的监听器
    myEmitter.on('event', () => {
      console.log('B');
    });
  }
});
myEmitter.on('event', () => {
  console.log('A');
});
myEmitter.emit('event');
// 打印:
//   B
//   A

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
// 只执行一次，这样我们不会永远循环
myEmitter.once('newListener', (event, listener) => {
  if (event === 'event') {
    // 在前面插入一个新的监听器
    myEmitter.on('event', () => {
      console.log('B');
    });
  }
});
myEmitter.on('event', () => {
  console.log('A');
});
myEmitter.emit('event');
// 打印:
//   B
//   A

事件: `'removeListener'`

[历史]

版本	变更
v6.1.0, v4.7.0	对于使用 `.once()` 附加的监听器，`listener` 参数现在产生原始的监听器函数。
v0.9.3	添加于: v0.9.3

eventName <string> | <symbol> 事件名称
listener <Function> 事件处理函数

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

`emitter.addListener(eventName, listener)`

添加于: v0.1.26

eventName <string> | <symbol>
listener <Function>

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

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

添加于: v0.1.26

eventName <string> | <symbol>
...args <any>
返回: <boolean>

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

如果事件有监听器，则返回 true，否则返回 false。

ESMCJS

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// 第一个监听器
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// 第二个监听器
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// 第三个监听器
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// 打印:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

const EventEmitter = require('node:events');
const myEmitter = new EventEmitter();

// 第一个监听器
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// 第二个监听器
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// 第三个监听器
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// 打印:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

`emitter.eventNames()`

新增于: v6.0.0

返回: <Array>

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

ESMCJS

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// 打印: [ 'foo', 'bar', Symbol(symbol) ]

const EventEmitter = require('node:events');

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// 打印: [ 'foo', 'bar', Symbol(symbol) ]

`emitter.getMaxListeners()`

新增于: v1.0.0

返回: <integer>

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

`emitter.listenerCount(eventName[, listener])`

[历史]

版本	变更
v19.8.0, v18.16.0	添加了 `listener` 参数。
v3.2.0	新增于: v3.2.0

eventName <string> | <symbol> 正在监听的事件的名称
listener <Function> 事件处理函数
返回: <integer>

返回正在监听名为 eventName 的事件的监听器的数量。如果提供了 listener，它将返回在事件监听器列表中找到监听器的次数。

`emitter.listeners(eventName)`

[历史记录]

版本	变更
v7.0.0	对于使用 `.once()` 附加的监听器，现在返回的是原始监听器，而不是包装函数。
v0.1.26	添加于: v0.1.26

eventName <string> | <symbol>
返回: <Function[]>

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

server.on('connection', (stream) => {
  console.log('有人连接了！');
});
console.log(util.inspect(server.listeners('connection')));
// 打印: [ [Function] ]

`emitter.off(eventName, listener)`

添加于: v10.0.0

eventName <string> | <symbol>
listener <Function>
返回: <EventEmitter>

emitter.removeListener() 的别名。

`emitter.on(eventName, listener)`

添加于: v0.1.101

eventName <string> | <symbol> 事件的名称。
listener <Function> 回调函数
返回: <EventEmitter>

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

server.on('connection', (stream) => {
  console.log('有人连接了！');
});

返回对 EventEmitter 的引用，以便可以链式调用。

默认情况下，事件监听器按照添加的顺序调用。 emitter.prependListener() 方法可以作为替代方法，将事件监听器添加到监听器数组的开头。

ESMCJS

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// 打印:
//   b
//   a

const EventEmitter = require('node:events');
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// 打印:
//   b
//   a

`emitter.once(eventName, listener)`

加入于: v0.3.0

eventName <string> | <symbol> 事件的名称。
listener <Function> 回调函数
返回: <EventEmitter>

为名为 eventName 的事件添加一个一次性 listener 函数。下一次触发 eventName 时，此监听器将被删除，然后被调用。

server.once('connection', (stream) => {
  console.log('啊，我们有第一个用户了!');
});

返回一个对 EventEmitter 的引用，以便可以链式调用。

默认情况下，事件监听器按照它们被添加的顺序调用。 emitter.prependOnceListener() 方法可以作为替代方法，将事件监听器添加到监听器数组的开头。

ESMCJS

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

const EventEmitter = require('node:events');
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

`emitter.prependListener(eventName, listener)`

加入于: v6.0.0

eventName <string> | <symbol> 事件的名称。
listener <Function> 回调函数
返回: <EventEmitter>

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

server.prependListener('connection', (stream) => {
  console.log('有人连接了！');
});

返回一个对 EventEmitter 的引用，以便可以链式调用。

`emitter.prependOnceListener(eventName, listener)`

新增于: v6.0.0

eventName <string> | <symbol> 事件的名称。
listener <Function> 回调函数
返回: <EventEmitter>

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

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回 EventEmitter 的引用，以便可以链式调用。

`emitter.removeAllListeners([eventName])`

新增于: v0.1.26

eventName <string> | <symbol>
返回: <EventEmitter>

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

移除代码中其他地方添加的监听器是一种不好的做法，特别是当 EventEmitter 实例是由其他组件或模块创建时（例如套接字或文件流）。

返回 EventEmitter 的引用，以便可以链式调用。

`emitter.removeListener(eventName, listener)`

新增于: v0.1.26

eventName <string> | <symbol>
listener <Function>
返回: <EventEmitter>

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

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() 最多会从监听器数组中移除一个监听器实例。如果任何单个监听器已多次添加到指定 eventName 的监听器数组中，则必须多次调用 removeListener() 才能移除每个实例。

一旦发出事件，所有在发出时附加到它的监听器都将按顺序调用。这意味着在发出之后且在最后一个监听器完成执行之前的任何 removeListener() 或 removeAllListeners() 调用都不会将它们从正在进行的 emit() 中移除。后续事件的行为符合预期。

ESMCJS

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA 移除监听器 callbackB，但它仍然会被调用。
// 发出时的内部监听器数组 [callbackA, callbackB]
myEmitter.emit('event');
// 打印:
//   A
//   B

// callbackB 现在已被移除。
// 内部监听器数组 [callbackA]
myEmitter.emit('event');
// 打印:
//   A

const EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA 移除监听器 callbackB，但它仍然会被调用。
// 发出时的内部监听器数组 [callbackA, callbackB]
myEmitter.emit('event');
// 打印:
//   A
//   B

// callbackB 现在已被移除。
// 内部监听器数组 [callbackA]
myEmitter.emit('event');
// 打印:
//   A

由于监听器是使用内部数组管理的，因此调用此方法将更改在被移除的监听器之后注册的任何监听器的位置索引。这不会影响调用监听器的顺序，但这意味着需要重新创建由 emitter.listeners() 方法返回的监听器数组的任何副本。

当一个函数已被多次添加为单个事件的处理程序时（如下面的示例所示），removeListener() 将移除最近添加的实例。在该示例中，移除了 once('ping') 监听器：

ESMCJS

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

const EventEmitter = require('node:events');
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

返回 EventEmitter 的引用，以便可以链式调用。

`emitter.setMaxListeners(n)`

加入版本: v0.3.5

n <integer>
返回: <EventEmitter>

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

返回对 EventEmitter 的引用，以便可以链式调用。

`emitter.rawListeners(eventName)`

加入版本: v9.4.0

eventName <string> | <symbol>
返回: <Function[]>

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

ESMCJS

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// 返回一个新数组，其中包含一个函数 `onceWrapper`，它具有一个属性
// `listener`，其中包含上面绑定的原始监听器
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// 将 "log once" 记录到控制台，并且不取消绑定 `once` 事件
logFnWrapper.listener();

// 将 "log once" 记录到控制台并删除监听器
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// 将返回一个新数组，其中包含上面由 `.on()` 绑定的单个函数
const newListeners = emitter.rawListeners('log');

// 将 "log persistently" 记录两次
newListeners[0]();
emitter.emit('log');

const EventEmitter = require('node:events');
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// 返回一个新数组，其中包含一个函数 `onceWrapper`，它具有一个属性
// `listener`，其中包含上面绑定的原始监听器
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// 将 "log once" 记录到控制台，并且不取消绑定 `once` 事件
logFnWrapper.listener();

// 将 "log once" 记录到控制台并删除监听器
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// 将返回一个新数组，其中包含上面由 `.on()` 绑定的单个函数
const newListeners = emitter.rawListeners('log');

// 将 "log persistently" 记录两次
newListeners[0]();
emitter.emit('log');

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

[历史]

版本	变更
v17.4.0, v16.14.0	不再是实验性的。
v13.4.0, v12.16.0	添加于：v13.4.0, v12.16.0

err Error
eventName <string> | <symbol>
...args <any>

如果在发出事件时发生 promise 拒绝，并且在 emitter 上启用了 captureRejections，则会调用 Symbol.for('nodejs.rejection') 方法。可以使用 events.captureRejectionSymbol 代替 Symbol.for('nodejs.rejection')。

ESMCJS

import { EventEmitter, captureRejectionSymbol } from 'node:events';

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}

const { EventEmitter, captureRejectionSymbol } = require('node:events');

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}

`events.defaultMaxListeners`

添加于: v0.11.2

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

设置 events.defaultMaxListeners 时要小心，因为更改会影响所有 EventEmitter 实例，包括在进行更改之前创建的实例。但是，调用 emitter.setMaxListeners(n) 仍然优先于 events.defaultMaxListeners。

这不是一个硬性限制。 EventEmitter 实例将允许添加更多监听器，但会输出一个跟踪警告到 stderr，指示检测到“可能的 EventEmitter 内存泄漏”。对于任何单个 EventEmitter，可以使用 emitter.getMaxListeners() 和 emitter.setMaxListeners() 方法来暂时避免此警告：

defaultMaxListeners 对 AbortSignal 实例没有影响。虽然仍然可以使用 emitter.setMaxListeners(n) 为单个 AbortSignal 实例设置警告限制，但默认情况下 AbortSignal 实例不会发出警告。

ESMCJS

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

const EventEmitter = require('node:events');
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

可以使用 --trace-warnings 命令行标志来显示此类警告的堆栈跟踪。

可以使用 process.on('warning') 检查发出的警告，并且它将具有额外的 emitter、type 和 count 属性，分别引用事件 emitter 实例、事件的名称和附加的监听器的数量。它的 name 属性设置为 'MaxListenersExceededWarning'。

`events.errorMonitor`

加入于: v13.6.0, v12.17.0

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

使用此符号安装监听器不会改变发出 'error' 事件后的行为。因此，如果没有安装常规 'error' 监听器，进程仍然会崩溃。

`events.getEventListeners(emitterOrTarget, eventName)`

加入于: v15.2.0, v14.17.0

emitterOrTarget <EventEmitter> | <EventTarget>
eventName <string> | <symbol>
返回: <Function[]>

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

对于 EventEmitter，此行为与在发射器上调用 .listeners 完全相同。

对于 EventTarget，这是获取事件目标的事件监听器的唯一方法。这对于调试和诊断目的很有用。

ESMCJS

import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}

const { getEventListeners, EventEmitter } = require('node:events');

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}

`events.getMaxListeners(emitterOrTarget)`

新增于: v19.9.0, v18.17.0

emitterOrTarget <EventEmitter> | <EventTarget>
返回: <number>

返回当前设置的最大监听器数量。

对于 EventEmitter，此行为与在 emitter 上调用 .getMaxListeners 完全相同。

对于 EventTarget，这是获取事件目标的最大事件监听器的唯一方法。如果单个 EventTarget 上的事件处理程序的数量超过了设置的最大值，则 EventTarget 将打印警告。

ESMCJS

import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}

const { getMaxListeners, setMaxListeners, EventEmitter } = require('node:events');

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}

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

[历史]

版本	变更
v15.0.0	现在支持 `signal` 选项。
v11.13.0, v10.16.0	添加于: v11.13.0, v10.16.0

emitter <EventEmitter>
name <string> | <symbol>
options <Object>
- signal <AbortSignal> 可用于取消等待事件。
返回: <Promise>

创建一个 Promise，当 EventEmitter 发出给定的事件时，该 Promise 会被实现，或者如果在等待时 EventEmitter 发出 'error'，则该 Promise 会被拒绝。该 Promise 将使用发出到给定事件的所有参数的数组来解析。

此方法是有意通用的，并且适用于 Web 平台 EventTarget 接口，该接口没有特殊的 'error' 事件语义，并且不监听 'error' 事件。

ESMCJS

import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

const { once, EventEmitter } = require('node:events');

async function run() {
  const ee = new EventEmitter();

  process.nextTick(() => {
    ee.emit('myevent', 42);
  });

  const [value] = await once(ee, 'myevent');
  console.log(value);

  const err = new Error('kaboom');
  process.nextTick(() => {
    ee.emit('error', err);
  });

  try {
    await once(ee, 'myevent');
  } catch (err) {
    console.error('error happened', err);
  }
}

run();

只有当 events.once() 用于等待另一个事件时，才会使用 'error' 事件的特殊处理。如果 events.once() 用于等待 'error' 事件本身，那么它将被视为任何其他类型的事件，而没有特殊处理：

ESMCJS

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

const { EventEmitter, once } = require('node:events');

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

<AbortSignal> 可用于取消等待事件：

ESMCJS

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Prints: Waiting for the event was canceled!

const { EventEmitter, once } = require('node:events');

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Prints: Waiting for the event was canceled!

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

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

ESMCJS

import { EventEmitter, once } from 'node:events';
import process from 'node:process';

const myEE = new EventEmitter();

async function foo() {
  await once(myEE, 'bar');
  console.log('bar');

  // 这个 Promise 永远不会 resolve，因为 'foo' 事件在 Promise 创建之前就已经触发了。
  await once(myEE, 'foo');
  console.log('foo');
}

process.nextTick(() => {
  myEE.emit('bar');
  myEE.emit('foo');
});

foo().then(() => console.log('done'));

const { EventEmitter, once } = require('node:events');

const myEE = new EventEmitter();

async function foo() {
  await once(myEE, 'bar');
  console.log('bar');

  // 这个 Promise 永远不会 resolve，因为 'foo' 事件在 Promise 创建之前就已经触发了。
  await once(myEE, 'foo');
  console.log('foo');
}

process.nextTick(() => {
  myEE.emit('bar');
  myEE.emit('foo');
});

foo().then(() => console.log('done'));

要捕获这两个事件，请在等待任何一个事件之前创建每个 Promise，然后就可以使用 Promise.all()、Promise.race() 或 Promise.allSettled()：

ESMCJS

import { EventEmitter, once } from 'node:events';
import process from 'node:process';

const myEE = new EventEmitter();

async function foo() {
  await Promise.all([once(myEE, 'bar'), once(myEE, 'foo')]);
  console.log('foo', 'bar');
}

process.nextTick(() => {
  myEE.emit('bar');
  myEE.emit('foo');
});

foo().then(() => console.log('done'));

const { EventEmitter, once } = require('node:events');

const myEE = new EventEmitter();

async function foo() {
  await Promise.all([once(myEE, 'bar'), once(myEE, 'foo')]);
  console.log('foo', 'bar');
}

process.nextTick(() => {
  myEE.emit('bar');
  myEE.emit('foo');
});

foo().then(() => console.log('done'));

`events.captureRejections`

[历史记录]

版本	变更
v17.4.0, v16.14.0	不再是实验性的。
v13.4.0, v12.16.0	添加于: v13.4.0, v12.16.0

值: <boolean>

更改所有新 EventEmitter 对象上的默认 captureRejections 选项。

`events.captureRejectionSymbol`

[历史记录]

版本	变更
v17.4.0, v16.14.0	不再是实验性的。
v13.4.0, v12.16.0	添加于: v13.4.0, v12.16.0

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

参见如何编写自定义的 rejection handler。

`events.listenerCount(emitter, eventName)`

添加于: v0.9.12

自: v3.2.0 起已弃用

[稳定度: 0 - 已弃用]

稳定度: 0 稳定性: 0 - 已弃用: 请使用 emitter.listenerCount() 代替。

emitter <EventEmitter> 要查询的 emitter
eventName <string> | <symbol> 事件名

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

ESMCJS

import { EventEmitter, listenerCount } from 'node:events';

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// 打印: 2

const { EventEmitter, listenerCount } = require('node:events');

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// 打印: 2

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

[历史]

版本	变更
v22.0.0, v20.13.0	支持 `highWaterMark` 和 `lowWaterMark` 选项，为了保持一致性。旧选项仍然受支持。
v20.0.0	现在支持 `close`、`highWatermark` 和 `lowWatermark` 选项。
v13.6.0, v12.16.0	添加于: v13.6.0, v12.16.0

emitter <EventEmitter>
eventName <string> | <symbol> 正在监听的事件的名称
options <Object>
- signal <AbortSignal> 可用于取消等待事件。
- close - <string[]> 将结束迭代的事件的名称。
- highWaterMark - <integer> 默认值: Number.MAX_SAFE_INTEGER 高水位线。每次缓冲事件的大小高于它时，发射器都会暂停。仅在实现 pause() 和 resume() 方法的发射器上受支持。
- lowWaterMark - <integer> 默认值: 1 低水位线。每次缓冲事件的大小低于它时，发射器都会恢复。仅在实现 pause() 和 resume() 方法的发射器上受支持。
返回: <AsyncIterator> 迭代 emitter 发出的 eventName 事件的异步迭代器。

ESMCJS

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// 稍后发出
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // 此内部块的执行是同步的，并且一次处理一个事件（即使使用 await）。
  // 如果需要并发执行，请勿使用。
  console.log(event); // 输出 ['bar'] [42]
}
// 此处无法访问

const { on, EventEmitter } = require('node:events');

(async () => {
  const ee = new EventEmitter();

  // 稍后发出
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo')) {
    // 此内部块的执行是同步的，并且一次处理一个事件（即使使用 await）。
    // 如果需要并发执行，请勿使用。
    console.log(event); // 输出 ['bar'] [42]
  }
  // 此处无法访问
})();

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

<AbortSignal> 可用于取消等待事件：

ESMCJS

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // 稍后发出
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // 此内部块的执行是同步的，并且一次处理一个事件（即使使用 await）。
    // 如果需要并发执行，请勿使用。
    console.log(event); // 输出 ['bar'] [42]
  }
  // 此处无法访问
})();

process.nextTick(() => ac.abort());

const { on, EventEmitter } = require('node:events');

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // 稍后发出
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // 此内部块的执行是同步的，并且一次处理一个事件（即使使用 await）。
    // 如果需要并发执行，请勿使用。
    console.log(event); // 输出 ['bar'] [42]
  }
  // 此处无法访问
})();

process.nextTick(() => ac.abort());

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

添加于: v15.4.0

n <number> 一个非负数。每个 EventTarget 事件的最大监听器数量。
...eventsTargets <EventTarget[]> | <EventEmitter[]> 零个或多个 <EventTarget> 或 <EventEmitter> 实例。如果未指定，则将 n 设置为所有新创建的 <EventTarget> 和 <EventEmitter> 对象的默认最大值。

ESMCJS

import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);

const {
  setMaxListeners,
  EventEmitter,
} = require('node:events');

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);

`events.addAbortListener(signal, listener)`

添加于: v20.5.0, v18.18.0

[稳定度: 1 - 实验性]

稳定度: 1 稳定度: 1 - 实验性

signal <AbortSignal>
listener <Function> | <EventListener>
返回: <Disposable> 一个移除 abort 监听器的 Disposable 对象。

监听提供的 signal 上的 abort 事件一次。

监听中止信号上的 abort 事件是不安全的，并且可能导致资源泄漏，因为拥有该信号的另一方可以调用 e.stopImmediatePropagation()。不幸的是，Node.js 无法更改此行为，因为它会违反 Web 标准。此外，原始 API 很容易忘记移除监听器。

此 API 通过监听事件的方式解决了这两个问题，即 stopImmediatePropagation 不会阻止监听器运行，从而允许在 Node.js API 中安全地使用 AbortSignal。

返回一个 disposable 对象，以便更容易地取消订阅。

CJSESM

const { addAbortListener } = require('node:events');

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}

import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}

类: `events.EventEmitterAsyncResource extends EventEmitter`

已加入: v17.4.0, v16.14.0

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

ESMCJS

import { EventEmitterAsyncResource, EventEmitter } from 'node:events';
import { notStrictEqual, strictEqual } from 'node:assert';
import { executionAsyncId, triggerAsyncId } from 'node:async_hooks';

// 异步跟踪工具将将其标识为“Q”。
const ee1 = new EventEmitterAsyncResource({ name: 'Q' });

// “foo”监听器将在 EventEmitters 异步上下文中运行。
ee1.on('foo', () => {
  strictEqual(executionAsyncId(), ee1.asyncId);
  strictEqual(triggerAsyncId(), ee1.triggerAsyncId);
});

const ee2 = new EventEmitter();

// 但是，普通的 EventEmitter 上未跟踪异步上下文的“foo”监听器，与 emit() 运行在相同的异步上下文中。
ee2.on('foo', () => {
  notStrictEqual(executionAsyncId(), ee2.asyncId);
  notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);
});

Promise.resolve().then(() => {
  ee1.emit('foo');
  ee2.emit('foo');
});

const { EventEmitterAsyncResource, EventEmitter } = require('node:events');
const { notStrictEqual, strictEqual } = require('node:assert');
const { executionAsyncId, triggerAsyncId } = require('node:async_hooks');

// 异步跟踪工具将将其标识为“Q”。
const ee1 = new EventEmitterAsyncResource({ name: 'Q' });

// “foo”监听器将在 EventEmitters 异步上下文中运行。
ee1.on('foo', () => {
  strictEqual(executionAsyncId(), ee1.asyncId);
  strictEqual(triggerAsyncId(), ee1.triggerAsyncId);
});

const ee2 = new EventEmitter();

// 但是，普通的 EventEmitter 上未跟踪异步上下文的“foo”监听器，与 emit() 运行在相同的异步上下文中。
ee2.on('foo', () => {
  notStrictEqual(executionAsyncId(), ee2.asyncId);
  notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);
});

Promise.resolve().then(() => {
  ee1.emit('foo');
  ee2.emit('foo');
});

EventEmitterAsyncResource 类具有与 EventEmitter 和 AsyncResource 自身相同的方法并采用相同的选项。

`new events.EventEmitterAsyncResource([options])`

options <Object>
- captureRejections <boolean> 它启用了自动捕获 Promise 拒绝。默认值: false。
- name <string> 异步事件的类型。默认值: new.target.name。
- triggerAsyncId <number> 创建此异步事件的执行上下文的 ID。默认值: executionAsyncId()。
- requireManualDestroy <boolean> 如果设置为 true，则在对象被垃圾回收时禁用 emitDestroy。通常不需要设置此选项（即使手动调用 emitDestroy），除非检索了资源的 asyncId 并且使用了敏感 API 的 emitDestroy 调用它。当设置为 false 时，只有在至少有一个活动的 destroy 钩子时，才会进行垃圾回收时的 emitDestroy 调用。默认值: false。

`eventemitterasyncresource.asyncId`

类型: <number> 分配给资源的唯一 asyncId。

`eventemitterasyncresource.asyncResource`

类型: 底层的 <AsyncResource>。

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

`eventemitterasyncresource.emitDestroy()`

调用所有 destroy 钩子。这应该只调用一次。如果多次调用，将会抛出一个错误。这必须手动调用。如果资源被垃圾回收器收集，那么 destroy 钩子将永远不会被调用。

`eventemitterasyncresource.triggerAsyncId`

类型: <number> 与传递给 AsyncResource 构造函数的 triggerAsyncId 相同。

`EventTarget` 和 `Event` API

[历史记录]

版本	更改
v16.0.0	更改了 EventTarget 错误处理。
v15.4.0	不再是实验性的。
v15.0.0	`EventTarget` 和 `Event` 类现在作为全局变量可用。
v14.5.0	添加于: v14.5.0

EventTarget 和 Event 对象是 Node.js 特定的 EventTarget Web API 实现，由一些 Node.js 核心 API 公开。

const target = new EventTarget();

target.addEventListener('foo', (event) => {
  console.log('foo event happened!');
});

Node.js `EventTarget` 与 DOM `EventTarget`

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

`NodeEventTarget` 与 `EventEmitter`

NodeEventTarget 对象实现 EventEmitter API 的一个修改过的子集，这使其能够在某些情况下密切地模拟 EventEmitter。 NodeEventTarget 不是 EventEmitter 的实例，在大多数情况下不能代替 EventEmitter 使用。

事件监听器

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

在这两种情况下，都会使用传递给 eventTarget.dispatchEvent() 函数的 event 参数调用处理程序函数。

异步函数可以用作事件监听器。如果异步处理函数拒绝，则拒绝将被捕获并按照 EventTarget 错误处理中所述的方式进行处理。

一个处理程序函数抛出的错误不会阻止调用其他处理程序。

处理程序函数的返回值将被忽略。

处理程序始终按照添加的顺序调用。

处理程序函数可以改变 event 对象。

function handler1(event) {
  console.log(event.type);  // 打印 'foo'
  event.a = 1;
}

async function handler2(event) {
  console.log(event.type);  // 打印 'foo'
  console.log(event.a);  // 打印 1
}

const handler3 = {
  handleEvent(event) {
    console.log(event.type);  // 打印 'foo'
  },
};

const handler4 = {
  async handleEvent(event) {
    console.log(event.type);  // 打印 'foo'
  },
};

const target = new EventTarget();

target.addEventListener('foo', handler1);
target.addEventListener('foo', handler2);
target.addEventListener('foo', handler3);
target.addEventListener('foo', handler4, { once: true });

`EventTarget` 错误处理

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

在事件监听器中抛出错误不会阻止其他已注册的处理程序被调用。

EventTarget 没有像 EventEmitter 那样为 'error' 类型事件实现任何特殊的默认处理。

目前，错误首先转发到 process.on('error') 事件，然后再到达 process.on('uncaughtException')。此行为已被弃用，并将在未来版本中更改，以使 EventTarget 与其他 Node.js API 对齐。任何依赖 process.on('error') 事件的代码都应与新行为保持一致。

类: `Event`

[历史记录]

版本	变更
v15.0.0	`Event` 类现在可以通过全局对象访问。
v14.5.0	添加于: v14.5.0

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

`event.bubbles`

添加于: v14.5.0

类型: <boolean> 始终返回 false。

这在 Node.js 中未使用，仅为了完整性而提供。

`event.cancelBubble`

添加于: v14.5.0

[稳定度: 3 - 遗留]

稳定度: 3 稳定性: 3 - 遗留: 请改用 event.stopPropagation()。

类型: <boolean>

如果设置为 true，则为 event.stopPropagation() 的别名。这在 Node.js 中未使用，仅为了完整性而提供。

`event.cancelable`

添加于: v14.5.0

类型: <boolean> 如果事件是使用 cancelable 选项创建的，则为 True。

`event.composed`

新增于: v14.5.0

类型: <boolean> 始终返回 false。

这在 Node.js 中未使用，仅为完整性而提供。

`event.composedPath()`

新增于: v14.5.0

返回一个数组，其中包含当前 EventTarget 作为唯一条目，如果事件未被分派，则返回空数组。这在 Node.js 中未使用，仅为完整性而提供。

`event.currentTarget`

新增于: v14.5.0

类型: <EventTarget> 分派事件的 EventTarget。

event.target 的别名。

`event.defaultPrevented`

新增于: v14.5.0

类型: <boolean>

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

`event.eventPhase`

新增于: v14.5.0

类型: <number> 事件未被分派时返回 0，正在被分派时返回 2。

这在 Node.js 中未使用，仅为完整性而提供。

`event.initEvent(type[, bubbles[, cancelable]])`

新增于: v19.5.0

[稳定度: 3 - 遗留]

稳定度: 3 稳定性: 3 - 遗留: WHATWG 规范认为它已弃用，用户不应再使用它。

type <string>
bubbles <boolean>
cancelable <boolean>

与事件构造函数冗余，并且无法设置 composed。这在 Node.js 中未使用，仅为完整性而提供。

`event.isTrusted`

新增于: v14.5.0

类型: <boolean>

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

`event.preventDefault()`

Added in: v14.5.0

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

`event.returnValue`

Added in: v14.5.0

[Stable: 3 - Legacy]

Stable: 3 Stability: 3 - Legacy：请改用 event.defaultPrevented。

类型: <boolean> 如果事件未被取消，则为 True。

event.returnValue 的值始终与 event.defaultPrevented 相反。这在 Node.js 中不使用，仅为完整性而提供。

`event.srcElement`

Added in: v14.5.0

[Stable: 3 - Legacy]

Stable: 3 Stability: 3 - Legacy：请改用 event.target。

类型: <EventTarget> 分发事件的 EventTarget。

event.target 的别名。

`event.stopImmediatePropagation()`

Added in: v14.5.0

在当前事件监听器完成后，停止调用其他事件监听器。

`event.stopPropagation()`

Added in: v14.5.0

这在 Node.js 中不使用，仅为完整性而提供。

`event.target`

Added in: v14.5.0

类型: <EventTarget> 分发事件的 EventTarget。

`event.timeStamp`

Added in: v14.5.0

类型: <number>

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

`event.type`

Added in: v14.5.0

类型: <string>

事件类型标识符。

类: `EventTarget`

[History]

Version	Changes
v15.0.0	The `EventTarget` class is now available through the global object.
v14.5.0	Added in: v14.5.0

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

[历史]

版本	变更
v15.4.0	添加了对 `signal` 选项的支持。
v14.5.0	添加于：v14.5.0

type <string>
listener <Function> | <EventListener>
options <Object>
- once <boolean> 当 true 时，侦听器会在首次调用时自动移除。 默认: false。
- passive <boolean> 当 true 时，作为提示，表示侦听器不会调用 Event 对象的 preventDefault() 方法。 默认: false。
- capture <boolean> 不直接被 Node.js 使用。为了 API 的完整性而添加。默认: false。
- signal <AbortSignal> 当给定的 AbortSignal 对象的 abort() 方法被调用时，侦听器将被移除。

为 type 事件添加一个新的处理器。任何给定的 listener 仅针对每个 type 和每个 capture 选项值添加一次。

如果 once 选项为 true，则在下一次分派 type 事件后，将移除 listener。

Node.js 不以任何功能方式使用 capture 选项，除了根据 EventTarget 规范跟踪注册的事件侦听器之外。具体来说，capture 选项在注册 listener 时用作键的一部分。任何单个 listener 可以添加一次，capture = false，一次 capture = true。

function handler(event) {}

const target = new EventTarget();
target.addEventListener('foo', handler, { capture: true });  // first
target.addEventListener('foo', handler, { capture: false }); // second

// 移除 handler 的第二个实例
target.removeEventListener('foo', handler);

// 移除 handler 的第一个实例
target.removeEventListener('foo', handler, { capture: true });

`eventTarget.dispatchEvent(event)`

加入于: v14.5.0

event <Event>
返回: <boolean> 如果事件的 cancelable 属性值为 false 或者其 preventDefault() 方法未被调用，则返回 true，否则返回 false。

将 event 分派到 event.type 的处理程序列表。

注册的事件监听器会按照它们注册的顺序同步调用。

`eventTarget.removeEventListener(type, listener[, options])`

加入于: v14.5.0

type <string>
listener <Function> | <EventListener>
options <Object>
- capture <boolean>

从事件 type 的处理程序列表中移除 listener。

类: `CustomEvent`

[历史]

版本	变更
v23.0.0	不再是实验性的。
v22.1.0, v20.13.0	CustomEvent 现在是稳定的。
v19.0.0	不再需要 `--experimental-global-customevent` 命令行标志。
v18.7.0, v16.17.0	加入于: v18.7.0, v16.17.0

[稳定度: 2 - 稳定]

稳定度: 2 稳定度: 2 - 稳定

继承自: <Event>

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

`event.detail`

[历史]

版本	变更
v22.1.0, v20.13.0	CustomEvent 现在是稳定的。
v18.7.0, v16.17.0	加入于: v18.7.0, v16.17.0

[稳定度: 2 - 稳定]

稳定度: 2 稳定度: 2 - 稳定

类型: <any> 返回初始化时传递的自定义数据。

只读。

类: `NodeEventTarget`

加入于: v14.5.0

继承: <EventTarget>

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

`nodeEventTarget.addListener(type, listener)`

加入于: v14.5.0

type <string>
listener <Function> | <EventListener>
返回: <EventTarget> this

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

`nodeEventTarget.emit(type, arg)`

加入于: v15.2.0

type <string>
arg <any>
返回: <boolean> 如果存在为 type 注册的事件监听器，则为 true，否则为 false。

Node.js 特定的 EventTarget 类的扩展，它将 arg 分派到 type 的处理程序列表。

`nodeEventTarget.eventNames()`

加入于: v14.5.0

返回: <string[]>

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

`nodeEventTarget.listenerCount(type)`

加入于: v14.5.0

type <string>
返回: <number>

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

`nodeEventTarget.setMaxListeners(n)`

新增于: v14.5.0

n <number>

Node.js 针对 EventTarget 类的特定扩展，用于设置最大事件监听器的数量为 n。

`nodeEventTarget.getMaxListeners()`

新增于: v14.5.0

返回: <number>

Node.js 针对 EventTarget 类的特定扩展，用于返回最大事件监听器的数量。

`nodeEventTarget.off(type, listener[, options])`

新增于: v14.5.0

type <string>
listener <Function> | <EventListener>
options <Object>
- capture <boolean>
返回: <EventTarget> this

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

`nodeEventTarget.on(type, listener)`

新增于: v14.5.0

type <string>
listener <Function> | <EventListener>
返回: <EventTarget> this

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

`nodeEventTarget.once(type, listener)`

新增于: v14.5.0

type <string>
listener <Function> | <EventListener>
返回: <EventTarget> this

Node.js 针对 EventTarget 类的特定扩展，为给定的事件 type 添加一个 once 监听器。这等同于调用 on 并将 once 选项设置为 true。

`nodeEventTarget.removeAllListeners([type])`

新增于: v14.5.0

type <string>
返回: <EventTarget> this

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

`nodeEventTarget.removeListener(type, listener[, options])`

新增于: v14.5.0

type <string>
listener <Function> | <EventListener>
options <Object>
- capture <boolean>
返回: <EventTarget> this

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

事件 ​

将参数和 this 传递给监听器 ​

异步 vs. 同步 ​

仅处理一次事件 ​

错误事件 ​

捕获 Promise 的拒绝 ​

类: EventEmitter ​

事件: 'newListener' ​

事件: 'removeListener' ​

emitter.addListener(eventName, listener) ​

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

emitter.eventNames() ​

emitter.getMaxListeners() ​

emitter.listenerCount(eventName[, listener]) ​

emitter.listeners(eventName) ​

emitter.off(eventName, listener) ​

emitter.on(eventName, listener) ​

emitter.once(eventName, listener) ​

emitter.prependListener(eventName, listener) ​

emitter.prependOnceListener(eventName, listener) ​

emitter.removeAllListeners([eventName]) ​

emitter.removeListener(eventName, listener) ​

emitter.setMaxListeners(n) ​

emitter.rawListeners(eventName) ​

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

events.defaultMaxListeners ​

events.errorMonitor ​

events.getEventListeners(emitterOrTarget, eventName) ​

events.getMaxListeners(emitterOrTarget) ​

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

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

events.captureRejections ​

events.captureRejectionSymbol ​

events.listenerCount(emitter, eventName) ​

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

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

events.addAbortListener(signal, listener) ​

类: events.EventEmitterAsyncResource extends EventEmitter ​

new events.EventEmitterAsyncResource([options]) ​

eventemitterasyncresource.asyncId ​

eventemitterasyncresource.asyncResource ​

eventemitterasyncresource.emitDestroy() ​

eventemitterasyncresource.triggerAsyncId ​

EventTarget 和 Event API ​

Node.js EventTarget 与 DOM EventTarget ​

NodeEventTarget 与 EventEmitter ​

事件监听器 ​

EventTarget 错误处理 ​

类: Event ​

event.bubbles ​

event.cancelBubble ​

event.cancelable ​

event.composed ​

event.composedPath() ​

event.currentTarget ​

event.defaultPrevented ​

event.eventPhase ​

event.initEvent(type[, bubbles[, cancelable]]) ​

event.isTrusted ​

event.preventDefault() ​

event.returnValue ​

event.srcElement ​

event.stopImmediatePropagation() ​

event.stopPropagation() ​

event.target ​

event.timeStamp ​

event.type ​

类: EventTarget ​

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

eventTarget.dispatchEvent(event) ​

eventTarget.removeEventListener(type, listener[, options]) ​

类: CustomEvent ​

event.detail ​

类: NodeEventTarget ​

nodeEventTarget.addListener(type, listener) ​

nodeEventTarget.emit(type, arg) ​

nodeEventTarget.eventNames() ​

nodeEventTarget.listenerCount(type) ​

nodeEventTarget.setMaxListeners(n) ​

nodeEventTarget.getMaxListeners() ​

事件

将参数和 `this` 传递给监听器

异步 vs. 同步

仅处理一次事件

错误事件

捕获 Promise 的拒绝

类: `EventEmitter`

事件: `'newListener'`

事件: `'removeListener'`

`emitter.addListener(eventName, listener)`

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

`emitter.eventNames()`

`emitter.getMaxListeners()`

`emitter.listenerCount(eventName[, listener])`

`emitter.listeners(eventName)`

`emitter.off(eventName, listener)`

`emitter.on(eventName, listener)`

`emitter.once(eventName, listener)`

`emitter.prependListener(eventName, listener)`

`emitter.prependOnceListener(eventName, listener)`

`emitter.removeAllListeners([eventName])`

`emitter.removeListener(eventName, listener)`

`emitter.setMaxListeners(n)`

`emitter.rawListeners(eventName)`

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

`events.defaultMaxListeners`

`events.errorMonitor`

`events.getEventListeners(emitterOrTarget, eventName)`

`events.getMaxListeners(emitterOrTarget)`

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

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

`events.captureRejections`

`events.captureRejectionSymbol`

`events.listenerCount(emitter, eventName)`

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

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

`events.addAbortListener(signal, listener)`

类: `events.EventEmitterAsyncResource extends EventEmitter`

`new events.EventEmitterAsyncResource([options])`

`eventemitterasyncresource.asyncId`

`eventemitterasyncresource.asyncResource`

`eventemitterasyncresource.emitDestroy()`

`eventemitterasyncresource.triggerAsyncId`

`EventTarget` 和 `Event` API

Node.js `EventTarget` 与 DOM `EventTarget`

`NodeEventTarget` 与 `EventEmitter`

事件监听器

`EventTarget` 错误处理

类: `Event`

`event.bubbles`

`event.cancelBubble`

`event.cancelable`

`event.composed`

`event.composedPath()`

`event.currentTarget`

`event.defaultPrevented`

`event.eventPhase`

`event.initEvent(type[, bubbles[, cancelable]])`

`event.isTrusted`

`event.preventDefault()`

`event.returnValue`

`event.srcElement`

`event.stopImmediatePropagation()`

`event.stopPropagation()`

`event.target`

`event.timeStamp`

`event.type`

类: `EventTarget`

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

`eventTarget.dispatchEvent(event)`

`eventTarget.removeEventListener(type, listener[, options])`

类: `CustomEvent`

`event.detail`

类: `NodeEventTarget`

`nodeEventTarget.addListener(type, listener)`

`nodeEventTarget.emit(type, arg)`

`nodeEventTarget.eventNames()`

`nodeEventTarget.listenerCount(type)`

`nodeEventTarget.setMaxListeners(n)`

`nodeEventTarget.getMaxListeners()`