Node.js v21.7.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(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');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 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');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'事件没有捕获处理程序，以避免无限错误循环：建议不要将async函数用作'error'事件处理程序。

类：EventEmitter#

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

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

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

它支持以下选项

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

事件：'newListener'#

• eventName <string> | <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 <string> | <symbol> 事件名称
• listener <Function> 事件处理函数

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

emitter.addListener(eventName, listener)#

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

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

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

• eventName <string> | <symbol>
• ...args <any>
• 返回值：<boolean>

同步调用为名为 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()#

• 返回值：<Array>

返回一个数组，列出发射器已为其注册监听器的事件。数组中的值是字符串或 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 <string> | <symbol> 正在监听的事件的名称
• listener <Function> 事件处理函数
• 返回值：<整数>

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

emitter.listeners(eventName)#

• eventName <string> | <symbol>
• 返回值：<函数[]>

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

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

emitter.off(eventName, listener)#

• eventName <string> | <symbol>
• listener <Function>
• 返回值：<EventEmitter>

是 emitter.removeListener() 的别名。

emitter.on(eventName, listener)#

• eventName <字符串> | <符号> 事件的名称。
• listener <函数> 回调函数
• 返回值：<EventEmitter>

将 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 <函数> 回调函数
• 返回值：<EventEmitter>

为名为 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 <函数> 回调函数
• 返回值：<EventEmitter>

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

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

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

emitter.prependOnceListener(eventName, listener)#

• eventName <字符串> | <符号> 事件的名称。
• listener <函数> 回调函数
• 返回值：<EventEmitter>

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

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

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

emitter.removeAllListeners([eventName])#

• eventName <string> | <symbol>
• 返回值：<EventEmitter>

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

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

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

emitter.removeListener(eventName, listener)#

• eventName <string> | <symbol>
• listener <Function>
• 返回值：<EventEmitter>

从名为 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 <整数>
• 返回值：<EventEmitter>

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

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

emitter.rawListeners(eventName)#

• eventName <string> | <symbol>
• 返回值：<函数[]>

返回名为 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 <string> | <symbol>
• ...args <any>

如果在发出事件时发生 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> | <EventTarget>
• eventName <string> | <symbol>
• 返回值：<函数[]>

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

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

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

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> | <EventTarget>
• 返回：<number>

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

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

对于 EventTarget，这是获取事件目标最大事件监听器的唯一方法。如果单个 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 <EventEmitter>
• name <string>
• options <Object>
  • signal <AbortSignal> 可用于取消等待事件。
• 返回：<Promise>

创建一个Promise，当EventEmitter发出给定事件时，该Promise将被fulfilled；如果EventEmitter在等待时发出'error'，则该Promise将被rejected。该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#

值：<boolean>

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

events.captureRejectionSymbol#

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

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

events.listenerCount(emitter, eventName)#

• emitter <EventEmitter> 要查询的发射器
• eventName <string> | <symbol> 事件名称

一个类方法，返回在给定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 <EventEmitter>
• eventName <string> | <symbol> 正在监听的事件的名称
• options <Object>
  • 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

返回一个 AsyncIterator，它迭代 eventName 事件。如果 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, listener)#

• signal <AbortSignal>
• listener <Function> | <EventListener>
• 返回值: <Disposable> 一个 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 扩展 EventEmitter#

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

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 <Object>
  • captureRejections <boolean> 它启用自动捕获 Promise 拒绝。默认值：false。
  • name <string> 异步事件的类型。默认值： new.target.name.
  • triggerAsyncId <number> 创建此异步事件的执行上下文的 ID。默认值： executionAsyncId()。
  • requireManualDestroy <boolean> 如果设置为 true，则在对象被垃圾回收时禁用 emitDestroy。通常不需要设置此选项（即使手动调用 emitDestroy），除非资源的 asyncId 被检索，并且敏感 API 的 emitDestroy 使用它被调用。当设置为 false 时，垃圾回收时的 emitDestroy 调用仅在至少有一个活动的 destroy 钩子时才会发生。默认值： 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 对 EventTarget Web API 的特定实现，由一些 Node.js 核心 API 公开。

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 的实例，在大多数情况下不能用作 EventEmitter 的替代品。

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 不像 EventEmitter 一样对 'error' 类型事件进行任何特殊的默认处理。

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

类：Event#

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

event.bubbles#

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

这在 Node.js 中未使用，仅出于完整性考虑而提供。

event.cancelBubble#

• 类型：<boolean>

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

event.cancelable#

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

event.composed#

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

这在 Node.js 中未使用，仅出于完整性考虑而提供。

event.composedPath()#

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

event.currentTarget#

• 类型：<EventTarget> 分派事件的 EventTarget。

event.target 的别名。

event.defaultPrevented#

• 类型：<boolean>

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

event.eventPhase#

• 类型：<number> 当事件未被分发时返回 0，当事件正在被分发时返回 2。

这在 Node.js 中未使用，仅出于完整性考虑而提供。

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

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

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

event.isTrusted#

• 类型：<boolean>

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

event.preventDefault()#

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

event.returnValue#

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

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

event.srcElement#

• 类型：<EventTarget> 分派事件的 EventTarget。

event.target 的别名。

event.stopImmediatePropagation()#

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

event.stopPropagation()#

这在 Node.js 中未使用，仅出于完整性考虑而提供。

event.target#

• 类型：<EventTarget> 分派事件的 EventTarget。

event.timeStamp#

• 类型: <number>

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

event.type#

• 类型: <string>

事件类型标识符。

类: EventTarget#

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

• 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 事件添加一个新的处理程序。对于每个 type 和每个 capture 选项值，每个给定的 listener 只添加一次。

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

capture 选项在 Node.js 中除了跟踪根据 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

// 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 <Event>
• 返回值：<boolean> 如果任一事件的 cancelable 属性值为 false 或其 preventDefault() 方法未被调用，则为 true，否则为 false。

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

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

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

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

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

类：CustomEvent#

• 扩展：<Event>

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

event.detail#

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

只读。

类：NodeEventTarget#

• 扩展：<EventTarget>

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

nodeEventTarget.addListener(type, listener)#

• type <string>

• listener <Function> | <EventListener>

• 返回值：<EventTarget> this

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

nodeEventTarget.emit(type, arg)#

• type <string>
• arg <any>
• 返回值：<boolean> 如果为 type 注册了事件监听器，则返回 true，否则返回 false。

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

nodeEventTarget.eventNames()#

• 返回值：<string[]>

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

nodeEventTarget.listenerCount(type)#

• type <string>

• 返回：<number>

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

nodeEventTarget.setMaxListeners(n)#

• n <number>

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

nodeEventTarget.getMaxListeners()#

• 返回：<number>

EventTarget 类在 Node.js 中的特定扩展，它返回最大事件监听器数量。

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

• type <string>

• listener <Function> | <EventListener>

• options <Object>

  • capture <boolean>

• 返回值：<EventTarget> this

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

nodeEventTarget.on(type, listener)#

• type <string>

• listener <Function> | <EventListener>

• 返回值：<EventTarget> this

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

nodeEventTarget.once(type, listener)#

• type <string>

• listener <Function> | <EventListener>

• 返回值：<EventTarget> this

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

nodeEventTarget.removeAllListeners([type])#

• type <string>

• 返回值：<EventTarget> this

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

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

• type <string>

• listener <Function> | <EventListener>

• options <Object>

  • capture <boolean>

• 返回值：<EventTarget> this

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