Node.js v18.18.2 文档

将参数和this传递给侦听器#

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

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(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(kCapture)]: false
  //   } true
});
myEmitter.emit('event', 'a', 'b');copy

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

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 {}
});
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');copy

异步与同步#

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

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');copy

仅处理一次事件#

当使用eventEmitter.on()方法注册侦听器时，每次发出指定事件时都会调用该侦听器。

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: 2const 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: 2copy

使用eventEmitter.once()方法，可以注册一个针对特定事件最多调用一次的侦听器。一旦事件被发出，监听器就会被取消注册，然后被调用。

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');
// Ignoredconst 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');
// Ignoredcopy

错误事件#

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

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

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// Throws and crashes Node.jsconst EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('whoops!'));
// Throws and crashes Node.jscopy

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

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

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!'));
// Prints: whoops! there was an errorconst 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!'));
// Prints: whoops! there was an errorcopy

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

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

const myEmitter = new EventEmitter();
myEmitter.on(errorMonitor, (err) => {
  MyMonitoringTool.log(err);
});
myEmitter.emit('error', new Error('whoops!'));
// Still throws and crashes Node.jsconst { EventEmitter, errorMonitor } = require('node:events');

const myEmitter = new EventEmitter();
myEmitter.on(errorMonitor, (err) => {
  MyMonitoringTool.log(err);
});
myEmitter.emit('error', new Error('whoops!'));
// Still throws and crashes Node.jscopy

捕获对 Promise 的拒绝#

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

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');
});copy

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

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;copy

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

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);copy

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

类：EventEmitter#

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

import { EventEmitter } from 'node:events';const EventEmitter = require('node:events');copy

当添加新侦听器时，所有EventEmitter都会发出事件'newListener' ；当删除现有侦听器时，所有 'removeListener' 都会发出事件 'removeListener' 。

它支持以下选项：

• captureRejections <boolean>它可以 自动捕获 Promise 拒绝。 默认值： false。

事件：'newListener'#

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

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

为'newListener'事件注册的侦听器将传递事件名称和对要添加的侦听器的引用。

事实上，在添加侦听器之前触发该事件有一个微妙但重要的副作用：在'newListener'回调中注册到同一 name 的任何其他侦听器都会插入到要添加的侦听器之前。在添加过程中。

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

const myEmitter = new MyEmitter();
// Only do this once so we don't loop forever
myEmitter.once('newListener', (event, listener) => {
  if (event === 'event') {
    // Insert a new listener in front
    myEmitter.on('event', () => {
      console.log('B');
    });
  }
});
myEmitter.on('event', () => {
  console.log('A');
});
myEmitter.emit('event');
// Prints:
//   B
//   Aconst EventEmitter = require('node:events');
class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
// Only do this once so we don't loop forever
myEmitter.once('newListener', (event, listener) => {
  if (event === 'event') {
    // Insert a new listener in front
    myEmitter.on('event', () => {
      console.log('B');
    });
  }
});
myEmitter.on('event', () => {
  console.log('A');
});
myEmitter.emit('event');
// Prints:
//   B
//   Acopy

事件：'removeListener'#

• eventName <字符串> | <符号>事件名称
• listener <Function>事件处理函数

删除listener后会发出'removeListener'事件。

emitter.addListener(eventName, listener)#

• eventName <字符串> | <符号>
• listener <函数>

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

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

• eventName <字符串> | <符号>
• ...args <任意>
• 返回：<布尔值>

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

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

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

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third 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);

// Prints:
// [
//   [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 listenerconst EventEmitter = require('node:events');
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third 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);

// Prints:
// [
//   [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 listenercopy

emitter.eventNames()#

• 返回：<数组>

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

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());
// Prints: [ '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());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]copy

emitter.getMaxListeners()#

• 返回：<整数>

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

emitter.listenerCount(eventName[, listener])#

• eventName <字符串> | <symbol>正在监听的事件的名称
• listener <Function>事件处理函数
• 返回：<整数>

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

emitter.listeners(eventName)#

• eventName <字符串> | <符号>
• 返回：<函数[]>

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

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ] copy

emitter.off(eventName, listener)#

• eventName <字符串> | <符号>
• listener <函数>
• 返回：<事件发射器>

emitter.removeListener()的别名。

emitter.on(eventName, listener)#

• eventName <字符串> | <符号>事件的名称。
• listener <Function>回调函数
• 返回：<事件发射器>

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

server.on('connection', (stream) => {
  console.log('someone connected!');
}); copy

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

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

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

emitter.once(eventName, listener)#

• eventName <字符串> | <符号>事件的名称。
• listener <Function>回调函数
• 返回：<事件发射器>

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

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

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

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

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
//   aconst 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
//   acopy

emitter.prependListener(eventName, listener)#

• eventName <字符串> | <符号>事件的名称。
• listener <Function>回调函数
• 返回：<事件发射器>

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

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
}); copy

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

emitter.prependOnceListener(eventName, listener)#

• eventName <字符串> | <符号>事件的名称。
• listener <Function>回调函数
• 返回：<事件发射器>

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

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

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

emitter.removeAllListeners([eventName])#

• eventName <字符串> | <符号>
• 返回：<事件发射器>

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

删除代码中其他位置添加的侦听器是不好的做法，特别是当EventEmitter实例是由某些其他组件或模块（例如套接字或文件流）创建时。

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

emitter.removeListener(eventName, listener)#

• eventName <字符串> | <符号>
• listener <函数>
• 返回：<事件发射器>

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

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

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

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

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 removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   Aconst 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 removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   Acopy

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

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

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');copy

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

emitter.setMaxListeners(n)#

• n <整数>
• 返回：<事件发射器>

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

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

emitter.rawListeners(eventName)#

• eventName <字符串> | <符号>
• 返回：<函数[]>

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

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

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');const EventEmitter = require('node:events');
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');copy

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

• err错误
• eventName <字符串> | <符号>
• ...args <任意>

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

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.
  }
}copy

events.defaultMaxListeners#

默认情况下，任何单个事件最多可以注册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()方法暂时避免此警告：

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));
});copy

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

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

events.errorMonitor#

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

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

events.getEventListeners(emitterOrTarget, eventName)#

• emitterOrTarget <EventEmitter> | <事件目标>
• eventName <字符串> | <符号>
• 返回：<函数[]>

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

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

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

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] ]
}copy

events.getMaxListeners(emitterOrTarget)#

• emitterOrTarget <EventEmitter> | <事件目标>
• 返回：<数字>

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

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

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

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
}copy

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

• emitter <事件发射器>
• name <字符串>
• options <对象>
  • signal <AbortSignal>可用于取消等待事件。
• 返回：< Promise >

创建一个Promise ，当EventEmitter发出给定事件时满足，或者当EventEmitter在等待时发出'error'时被拒绝。Promise将解析为向给定事件发出的所有参数的数组。

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

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();copy

仅当使用events.once() 等待另一个事件时，才会使用 'error' 事件的特殊处理。如果events.once()用于等待error'事件本身，则将其视为任何其他类型的事件，无需特殊处理：

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 boomconst { 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 boomcopy

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

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(); // Abort waiting for the event
ee.emit('foo'); // 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(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!copy

正在等待process.nextTick()上发出的多个事件#

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

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');

  // This Promise will never resolve because the 'foo' event will
  // have already been emitted before the Promise is created.
  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');

  // This Promise will never resolve because the 'foo' event will
  // have already been emitted before the Promise is created.
  await once(myEE, 'foo');
  console.log('foo');
}

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

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

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

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'));copy

events.captureRejections#

值：<布尔值>

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

events.captureRejectionSymbol#

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

了解如何编写自定义拒绝处理程序。

events.listenerCount(emitter, eventName)#

• emitter <EventEmitter>要查询的发射器
• eventName <字符串> | <符号>事件名称

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

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

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2const { EventEmitter, listenerCount } = require('node:events');

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

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

• emitter <事件发射器>
• eventName <字符串> | <symbol>正在监听的事件的名称
• options <对象>
  • signal <AbortSignal>可用于取消等待事件。
• 返回：<AsyncIterator>，迭代由emitter发出的eventName事件

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

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable hereconst { on, EventEmitter } = require('node:events');

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

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo')) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();copy

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

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

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

const ac = new AbortController();

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

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());const { on, EventEmitter } = require('node:events');

const ac = new AbortController();

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

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

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

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

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

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);copy

events.addAbortListener(signal, resource)#

• signal <中止信号>
• listener <函数> | <事件监听器>
• 返回：<Disposable>，删除abort侦听器。

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

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

此 API 允许在 Node.js API 中安全地使用AbortSignal，通过侦听事件来解决这两个问题，这样stopImmediatePropagation不会阻止侦听器运行。

返回一次性内容，以便更轻松地取消订阅。

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]();
  }
}copy

类：events.EventEmitterAsyncResource extends EventEmitter#

将EventEmitter与<AsyncResource>集成，以实现需要手动异步跟踪的EventEmitter 。具体来说，由events.EventEmitterAsyncResource实例发出的所有事件都将在其async context中运行。

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

// Async tracking tooling will identify this as 'Q'.
const ee1 = new EventEmitterAsyncResource({ name: 'Q' });

// 'foo' listeners will run in the EventEmitters async context.
ee1.on('foo', () => {
  strictEqual(executionAsyncId(), ee1.asyncId);
  strictEqual(triggerAsyncId(), ee1.triggerAsyncId);
});

const ee2 = new EventEmitter();

// 'foo' listeners on ordinary EventEmitters that do not track async
// context, however, run in the same async context as the 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');

// Async tracking tooling will identify this as 'Q'.
const ee1 = new EventEmitterAsyncResource({ name: 'Q' });

// 'foo' listeners will run in the EventEmitters async context.
ee1.on('foo', () => {
  strictEqual(executionAsyncId(), ee1.asyncId);
  strictEqual(triggerAsyncId(), ee1.triggerAsyncId);
});

const ee2 = new EventEmitter();

// 'foo' listeners on ordinary EventEmitters that do not track async
// context, however, run in the same async context as the emit().
ee2.on('foo', () => {
  notStrictEqual(executionAsyncId(), ee2.asyncId);
  notStrictEqual(triggerAsyncId(), ee2.triggerAsyncId);
});

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

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

new events.EventEmitterAsyncResource([options])#

• options <对象>
  • 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挂钩。这应该只被调用一次。如果多次调用就会抛出错误。这必须手动调用。如果资源留待 GC 收集，则永远不会调用destroy挂钩。

eventemitterasyncresource.triggerAsyncId#

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

EventTarget和Event API#

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

const target = new EventTarget();

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

Node.js EventTarget与 DOM EventTarget#

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

1. 尽管 DOM EventTarget实例可能是分层的，但 Node.js 中没有分层结构和事件传播的概念。也就是说，分派到EventTarget 的事件不会通过嵌套目标对象的层次结构传播，每个目标对象可能都有自己的一组事件处理程序。
2. 在 Node.js EventTarget中，如果事件侦听器是异步函数或返回Promise，并且返回的Promise拒绝，则会自动捕获拒绝并处理方式与同步抛出的侦听器相同（有关详细信息，请参阅EventTarget错误处理）。

NodeEventTarget与EventEmitter#

NodeEventTarget对象实现了EventEmitter API的修改子集 ，使其能够在某些情况下紧密模拟EventEmitter 。NodeEventTarget不是EventEmitter的实例，在大多数情况下 不能用来代替{ { {0502}}} 。

1. 与EventEmitter不同，任何给定的listener每个事件最多可以注册一次type。多次尝试注册listener将被忽略。
2. NodeEventTarget不模拟完整的EventEmitter API 。具体来说，不模拟prependListener()、prependOnceListener()、 rawListeners()和errorMonitor API。'newListener'和'removeListener'事件也不会被发出。
3. NodeEventTarget不会为类型为'error'的事件实现任何特殊的默认行为。
4. NodeEventTarget支持EventListener对象以及函数作为所有事件类型的处理程序。

事件监听器#

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

无论哪种情况，都会使用传递给eventTarget.dispatchEvent()函数的event参数来调用处理函数。

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

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

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

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

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

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

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

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

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

const target = new EventTarget();

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

EventTarget错误处理#

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

抛出事件侦听器不会阻止调用其他已注册的处理程序。

EventTarget不会对'error' 类型事件（如EventEmitter ）实现任何特殊的默认处理。

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

类：Event#

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

event.bubbles#

• 类型：<boolean>始终返回false。

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

event.cancelBubble#

• 类型：<布尔值>

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

event.cancelable#

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

event.composed#

• 类型：<boolean>始终返回false。

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

event.composedPath()#

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

event.currentTarget#

• 类型：<EventTarget>调度事件的EventTarget。

event.target的别名。

event.defaultPrevented#

• 类型：<布尔值>

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

event.eventPhase#

• 类型：<number>在未调度事件时返回0 ，在调度事件时返回2 。

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

event.isTrusted#

• 类型：<布尔值>

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

event.preventDefault()#

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

event.returnValue#

• 类型：<boolean>如果事件尚未取消，则为 true。

event.returnValue的值始终与event.defaultPrevented相反。这在 Node.js 中没有使用，纯粹是为了完整性而提供的。

event.srcElement#

• 类型：<EventTarget>调度事件的EventTarget。

event.target的别名。

event.stopImmediatePropagation()#

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

event.stopPropagation()#

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

event.target#

• 类型：<EventTarget>调度事件的EventTarget。

event.timeStamp#

• 类型：<数字>

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

event.type#

• 类型：<字符串>

事件类型标识符。

类：EventTarget#

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

• type <字符串>
• listener <函数> | <事件监听器>
• options <对象>
  • 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 。

除了根据EventTarget规范跟踪注册的事件侦听器之外，Node.js 不会以任何功能方式使用 capture选项。具体来说，在注册 listener时， capture选项用作键的一部分。任何单独的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

// Removes the second instance of handler
target.removeEventListener('foo', handler);

// Removes the first instance of handler
target.removeEventListener('foo', handler, { capture: true }); copy

eventTarget.dispatchEvent(event)#

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

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

已注册的事件侦听器将按其注册顺序同步调用。

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

• type <字符串>
• listener <函数> | <事件监听器>
• options <对象>
  • capture <布尔值>

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

类：CustomEvent#

• 扩展：<事件>

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

event.detail#

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

只读。

类：NodeEventTarget#

• 扩展：<EventTarget>

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

nodeEventTarget.addListener(type, listener)#

• type <字符串>

• listener <函数> | <事件监听器>

• 返回：<EventTarget> this

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

nodeEventTarget.emit(type, arg)#

• type <字符串>
• arg <任意>
• 返回：<boolean> true如果为type注册的事件监听器存在，否则为false。

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

nodeEventTarget.eventNames()#

• 返回：<字符串[]>

Node.js 特定于EventTarget类的扩展，该扩展返回为其注册事件侦听器的事件type名称数组。

nodeEventTarget.listenerCount(type)#

• type <字符串>

• 返回：<数字>

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

nodeEventTarget.setMaxListeners(n)#

• n <数字>

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

nodeEventTarget.getMaxListeners()#

• 返回：<数字>

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

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

• type <字符串>

• listener <函数> | <事件监听器>

• options <对象>

  • capture <布尔值>

• 返回：<EventTarget> this

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

nodeEventTarget.on(type, listener)#

• type <字符串>

• listener <函数> | <事件监听器>

• 返回：<EventTarget> this

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

nodeEventTarget.once(type, listener)#

• type <字符串>

• listener <函数> | <事件监听器>

• 返回：<EventTarget> this

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

nodeEventTarget.removeAllListeners([type])#

• type <字符串>

• 返回：<EventTarget> this

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

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

• type <字符串>

• listener <函数> | <事件监听器>

• options <对象>

  • capture <布尔值>

• 返回：<EventTarget> this

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