目录

events（事件触发器）#

稳定性: 2 - 稳定

源代码: lib/events.js

大多数 Node.js 核心 API 构建于惯用的异步事件驱动架构，其中某些类型的对象（又称触发器，Emitter）会触发命名事件来调用函数（又称监听器，Listener）。

例如，net.Server 会在每次有新连接时触发事件，fs.ReadStream 会在打开文件时触发事件，stream会在数据可读时触发事件。

所有能触发事件的对象都是 EventEmitter 类的实例。 这些对象有一个 eventEmitter.on() 函数，用于将一个或多个函数绑定到命名事件上。 事件的命名通常是驼峰式的字符串，但也可以使用任何有效的 JavaScript 属性键。。

当 EventEmitter 对象触发一个事件时，所有绑定在该事件上的函数都会被同步地调用。 被调用的监听器返回的任何值都将会被忽略并丢弃。

例子，一个简单的 EventEmitter 实例，绑定了一个监听器。 eventEmitter.on() 用于注册监听器， eventEmitter.emit() 用于触发事件。

const EventEmitter = require('events');

class MyEmitter extends EventEmitter {}

const myEmitter = new MyEmitter();
myEmitter.on('event', () => {
  console.log('触发事件');
});
myEmitter.emit('event');

将参数和 this 传给监听器#

eventEmitter.emit() 方法可以传任意数量的参数到监听器函数。 当监听器函数被调用时， this 关键词会被指向监听器所绑定的 EventEmitter 实例。

const myEmitter = new MyEmitter();
myEmitter.on('event', function(a, b) {
  console.log(a, b, this, this === myEmitter);
  // 打印:
  //   a b MyEmitter {
  //     domain: null,
  //     _events: { event: [Function] },
  //     _eventsCount: 1,
  //     _maxListeners: undefined } true
});
myEmitter.emit('event', 'a', 'b');

也可以使用 ES6 的箭头函数作为监听器。但 this 关键词不会指向 EventEmitter 实例：

const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  console.log(a, b, this);
  // 打印: a b {}
});
myEmitter.emit('event', 'a', 'b');

异步 VS 同步#

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

const myEmitter = new MyEmitter();
myEmitter.on('event', (a, b) => {
  setImmediate(() => {
    console.log('异步地发生');
  });
});
myEmitter.emit('event', 'a', 'b');

仅处理事件一次#

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

const myEmitter = new MyEmitter();
let m = 0;
myEmitter.on('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// 打印: 1
myEmitter.emit('event');
// 打印: 2

使用 eventEmitter.once() 可以注册最多可调用一次的监听器。 当事件被触发时，监听器会被注销，然后再调用。

const myEmitter = new MyEmitter();
let m = 0;
myEmitter.once('event', () => {
  console.log(++m);
});
myEmitter.emit('event');
// 打印: 1
myEmitter.emit('event');
// 不触发

错误事件#

当 EventEmitter 实例出错时，应该触发 'error' 事件。 这些在 Node.js 中被视为特殊情况。

如果没有为 'error' 事件注册监听器，则当 'error' 事件触发时，会抛出错误、打印堆栈跟踪、并退出 Node.js 进程。

const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('错误信息'));
// 抛出错误并使 Node.js 崩溃。

为了防止崩溃 Node.js 进程，可以使用 domain 模块。 （但请注意，不推荐使用 domain 模块。）

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

const myEmitter = new MyEmitter();
myEmitter.on('error', (err) => {
  console.error('错误信息');
});
myEmitter.emit('error', new Error('错误'));
// 打印: 错误信息

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

const myEmitter = new MyEmitter();
myEmitter.on(EventEmitter.errorMonitor, (err) => {
  MyMonitoringTool.log(err);
});
myEmitter.emit('error', new Error('错误'));
// 仍然抛出错误并使 Node.js 崩溃。

捕捉 Promise 的拒绝#

稳定性: 1 - captureRejections is experimental.

Using async functions with event handlers is problematic, because it can lead to an unhandled rejection in case of a thrown exception:

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

The captureRejections option in the EventEmitter constructor or the global setting change this behavior, installing a .then(undefined, handler) handler on the Promise. This handler routes the exception asynchronously to the Symbol.for('nodejs.rejection') method if there is one, or to 'error' event handler if there is none.

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;

Setting EventEmitter.captureRejections = true will change the default for all new instances of EventEmitter.

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

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

The 'error' events that are generated by the captureRejections behavior do not have a catch handler to avoid infinite error loops: the recommendation is to not use async functions as 'error' event handlers.

EventEmitter 类#

版本历史
版本变更
v13.4.0, v12.16.0

Added captureRejections option.

v0.1.26

新增于: v0.1.26

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

const EventEmitter = require('events');

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

它支持以下选项：

'newListener' 事件#

新增于: v0.1.26

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

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

在添加监听器之前触发事件的事实具有微妙但重要的副作用：在 'newListener' 回调中注册到相同 name 的任何其他监听器将插入到正在添加的监听器之前。

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

For listeners attached using .once(), the listener argument now yields the original listener function.

v0.9.3

新增于: v0.9.3

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

EventEmitter.listenerCount(emitter, eventName)#

新增于: v0.9.12弃用于: v3.2.0

稳定性: 0 - 弃用: 改为使用 emitter.listenerCount() 。

A class method that returns the number of listeners for the given eventName registered on the given emitter.

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

EventEmitter.defaultMaxListeners#

新增于: v0.11.2

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

设置 EventEmitter.defaultMaxListeners 要谨慎，因为会影响所有 EventEmitter 实例，包括之前创建的。 因而，优先使用 emitter.setMaxListeners(n) 而不是 EventEmitter.defaultMaxListeners。

限制不是硬性的。 EventEmitter 实例可以添加超过限制的监听器，但会向 stderr 输出跟踪警告，表明检测到可能的内存泄漏。 对于单个 EventEmitter 实例，可以使用 emitter.getMaxListeners() 和 emitter.setMaxListeners() 暂时地消除警告：

emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // 做些操作
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

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

触发的警告可以通过 process.on('warning') 进行检查，并具有附加的 emitter、 type 和 count 属性，分别指向事件触发器实例、事件名称、以及附加的监听器数量。 其 name 属性设置为 'MaxListenersExceededWarning'。

EventEmitter.errorMonitor#

新增于: v13.6.0, v12.16.0

This symbol shall be used to install a listener for only monitoring 'error' events. Listeners installed using this symbol are called before the regular 'error' listeners are called.

Installing a listener using this symbol does not change the behavior once an 'error' event is emitted, therefore the process will still crash if no regular 'error' listener is installed.

emitter.addListener(eventName, listener)#

新增于: v0.1.26

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

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

新增于: v0.1.26

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

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

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

// 第一个监听器。
myEmitter.on('event', function firstListener() {
  console.log('第一个监听器');
});
// 第二个监听器。
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`第二个监听器中的事件有参数 ${arg1}、${arg2}`);
});
// 第三个监听器
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`第三个监听器中的事件有参数 ${parameters}`);
});

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

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

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// 第一个监听器
// 第二个监听器中的事件有参数 1、2
// 第三个监听器中的事件有参数 1, 2, 3, 4, 5

emitter.eventNames()#

新增于: v6.0.0

返回已注册监听器的事件名数组。 数组中的值为字符串或 Symbol。

const EventEmitter = require('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

返回 EventEmitter 当前的监听器最大限制数的值，该值可以使用 emitter.setMaxListeners(n) 设置或默认为 EventEmitter.defaultMaxListeners。

emitter.listenerCount(eventName)#

新增于: v3.2.0

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

emitter.listeners(eventName)#

版本历史
版本变更
v7.0.0

For listeners attached using .once() this returns the original listeners instead of wrapper functions now.

v0.1.26

新增于: v0.1.26

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

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

emitter.off(eventName, listener)#

新增于: v10.0.0

emitter.removeListener() 的别名。

emitter.on(eventName, listener)#

新增于: v0.1.101

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

server.on('connection', (stream) => {
  console.log('已连接');
});

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

默认情况下，事件监听器会按照添加的顺序依次调用。 emitter.prependListener() 方法可用于将事件监听器添加到监听器数组的开头。

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

添加单次监听器 listener 到名为 eventName 的事件。 当 eventName 事件下次触发时，监听器会先被移除，然后再调用。

server.once('connection', (stream) => {
  console.log('第一次调用');
});

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

默认情况下，事件监听器会按照添加的顺序依次调用。 emitter.prependOnceListener() 方法可用于将事件监听器添加到监听器数组的开头。

const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// 打印:
//   b
//   a

emitter.prependListener(eventName, listener)#

新增于: v6.0.0

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

server.prependListener('connection', (stream) => {
  console.log('已连接');
});

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

emitter.prependOnceListener(eventName, listener)#

新增于: v6.0.0

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

server.prependOnceListener('connection', (stream) => {
  console.log('第一次调用');
});

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

emitter.removeAllListeners([eventName])#

新增于: v0.1.26

移除全部监听器或指定的 eventName 事件的监听器。

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

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

emitter.removeListener(eventName, listener)#

新增于: v0.1.26

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

const callback = (stream) => {
  console.log('已连接');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

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

一旦事件被触发，所有绑定到该事件的监听器都会按顺序依次调用。 这意味着，在事件触发之后、且最后一个监听器执行完成之前， removeListener() 或 removeAllListeners() 不会从 emit() 中移除它们。 后续事件的行为符合预期。

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

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

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

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

emitter.rawListeners(eventName)#

新增于: v9.4.0

返回 eventName 事件的监听器数组的拷贝，包括封装的监听器（例如由 .once() 创建的）。

const emitter = new EventEmitter();
emitter.once('log', () => console.log('只记录一次'));

// 返回一个数组，包含了一个封装了 `listener` 方法的监听器。
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// 打印 “只记录一次”，但不会解绑 `once` 事件。
logFnWrapper.listener();

// 打印 “只记录一次”，且移除监听器。
logFnWrapper();

emitter.on('log', () => console.log('持续地记录'));
// 返回一个数组，只包含 `.on()` 绑定的监听器。
const newListeners = emitter.rawListeners('log');

// 打印两次 “持续地记录”。
newListeners[0]();
emitter.emit('log');

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

新增于: v13.4.0, v12.16.0

稳定性: 1 - captureRejections is experimental.

The Symbol.for('nodejs.rejection') method is called in case a promise rejection happens when emitting an event and captureRejections is enabled on the emitter. It is possible to use events.captureRejectionSymbol in place of Symbol.for('nodejs.rejection').

const { EventEmitter, captureRejectionSymbol } = require('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.once(emitter, name)#

新增于: v11.13.0, v10.16.0

创建一个 Promise，当 EventEmitter 触发给定的事件时则会被解决，如果等待时 EventEmitter 触发 'error' 则会被拒绝。 解决 Promise 时将会带上触发到给定事件的所有参数的数组。

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

const { once, EventEmitter } = require('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('错误信息');
  process.nextTick(() => {
    ee.emit('error', err);
  });

  try {
    await once(ee, 'myevent');
  } catch (err) {
    console.log('出错', err);
  }
}

run();

The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

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

const ee = new EventEmitter();

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

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

// Prints: ok boom

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

There is an edge case worth noting when using the events.once() function to await multiple events emitted on in the same batch of process.nextTick() operations, or whenever multiple events are emitted synchronously. Specifically, because the process.nextTick() queue is drained before the Promise microtask queue, and because EventEmitter emits all events synchronously, it is possible for events.once() to miss an event.

const { EventEmitter, once } = require('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'));

To catch both events, create each of the Promises before awaiting either of them, then it becomes possible to use Promise.all(), Promise.race(), or Promise.allSettled():

const { EventEmitter, once } = require('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#

新增于: v13.4.0, v12.16.0

稳定性: 1 - captureRejections is experimental.

Value: <boolean>

Change the default captureRejections option on all new EventEmitter objects.

events.captureRejectionSymbol#

新增于: v13.4.0, v12.16.0

稳定性: 1 - captureRejections is experimental.

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

See how to write a custom rejection handler.

events.on(emitter, eventName)#

新增于: v13.6.0, v12.16.0 
const { on, EventEmitter } = require('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
})();

Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

EventTarget 与 Event API#

新增于: v14.5.0

稳定性: 1 - 实验

The EventTarget and Event objects are a Node.js-specific implementation of the EventTarget Web API that are exposed by some Node.js core APIs. Neither the EventTarget nor Event classes are available for end user code to create.

const target = getEventTargetSomehow();

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

Node.js EventTarget 对比 DOM EventTarge#

There are two key differences between the Node.js EventTarget and the EventTarget Web API:

  1. Whereas DOM EventTarget instances may be hierarchical, there is no concept of hierarchy and event propagation in Node.js. That is, an event dispatched to an EventTarget does not propagate through a hierarchy of nested target objects that may each have their own set of handlers for the event.
  2. In the Node.js EventTarget, if an event listener is an async function or returns a Promise, and the returned Promise rejects, the rejection is automatically captured and handled the same way as a listener that throws synchronously (see EventTarget error handling for details).

NodeEventTarget 对比 EventEmitter#

The NodeEventTarget object implements a modified subset of the EventEmitter API that allows it to closely emulate an EventEmitter in certain situations. A NodeEventTarget is not an instance of EventEmitter and cannot be used in place of an EventEmitter in most cases.

  1. Unlike EventEmitter, any given listener can be registered at most once per event type. Attempts to register a listener multiple times are ignored.
  2. The NodeEventTarget does not emulate the full EventEmitter API. Specifically the prependListener(), prependOnceListener(), rawListeners(), setMaxListeners(), getMaxListeners(), and errorMonitor APIs are not emulated. The 'newListener' and 'removeListener' events will also not be emitted.
  3. The NodeEventTarget does not implement any special default behavior for events with type 'error'.
  4. The NodeEventTarget supports EventListener objects as well as functions as handlers for all event types.

事件监听器#

Event listeners registered for an event type may either be JavaScript functions or objects with a handleEvent property whose value is a function.

In either case, the handler function is invoked with the event argument passed to the eventTarget.dispatchEvent() function.

Async functions may be used as event listeners. If an async handler function rejects, the rejection is captured and handled as described in EventTarget error handling.

An error thrown by one handler function does not prevent the other handlers from being invoked.

The return value of a handler function is ignored.

Handlers are always invoked in the order they were added.

Handler functions may mutate the event object.

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 = getEventTargetSomehow();

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

EventTarget 的错误处理#

When a registered event listener throws (or returns a Promise that rejects), by default the error is forwarded to the process.on('error') event on process.nextTick(). Throwing within an event listener will not stop the other registered handlers from being invoked.

The EventTarget does not implement any special default handling for 'error' type events.

Event 类#

新增于: v14.5.0

The Event object is an adaptation of the Event Web API. Instances are created internally by Node.js.

event.bubbles#

新增于: v14.5.0

This is not used in Node.js and is provided purely for completeness.

event.cancelBubble()#

新增于: v14.5.0

Alias for event.stopPropagation(). This is not used in Node.js and is provided purely for completeness.

event.cancelable#

新增于: v14.5.0
  • Type: <boolean> True if the event was created with the cancelable option.

event.composed#

新增于: v14.5.0

This is not used in Node.js and is provided purely for completeness.

event.composedPath()#

新增于: v14.5.0

Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness.

event.currentTarget#

新增于: v14.5.0

Alias for event.target.

event.defaultPrevented#

新增于: v14.5.0

Is true if cancelable is true and event.preventDefault() has been called.

event.eventPhase#

新增于: v14.5.0
  • Type: <number> Returns 0 while an event is not being dispatched, 2 while it is being dispatched.

This is not used in Node.js and is provided purely for completeness.

event.isTrusted#

新增于: v14.5.0

This is not used in Node.js and is provided purely for completeness.

event.preventDefault()#

新增于: v14.5.0

Sets the defaultPrevented property to true if cancelable is true.

event.returnValue#

新增于: v14.5.0
  • Type: <boolean> True if the event has not been canceled.

This is not used in Node.js and is provided purely for completeness.

event.srcElement#

新增于: v14.5.0

Alias for event.target.

event.stopImmediatePropagation()#

新增于: v14.5.0

Stops the invocation of event listeners after the current one completes.

event.stopPropagation()#

新增于: v14.5.0

This is not used in Node.js and is provided purely for completeness.

event.target#

新增于: v14.5.0

event.timeStamp#

新增于: v14.5.0

The millisecond timestamp when the Event object was created.

event.type#

新增于: v14.5.0

The event type identifier.

EventTarget 类#

新增于: v14.5.0

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

新增于: v14.5.0
  • type <string>
  • listener <Function> | <EventListener>
  • options <Object>
    • once <boolean> When true, the listener is automatically removed when it is first invoked. Default: false.
    • passive <boolean> When true, serves as a hint that the listener will not call the Event object's preventDefault() method. Default: false.
    • capture <boolean> Not directly used by Node.js. Added for API completeness. Default: false.

Adds a new handler for the type event. Any given listener is added only once per type and per capture option value.

If the once option is true, the listener is removed after the next time a type event is dispatched.

The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.

function handler(event) {}

const target = getEventTargetSomehow();
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 });

eventTarget.dispatchEvent(event)#

新增于: v14.5.0

Dispatches the event to the list of handlers for event.type. The event may be an Event object or any object with a type property whose value is a string.

The registered event listeners is synchronously invoked in the order they were registered.

eventTarget.removeEventListener(type, listener)#

新增于: v14.5.0

Removes the listener from the list of handlers for event type.

NodeEventTarget 类#

新增于: v14.5.0

The NodeEventTarget is a Node.js-specific extension to EventTarget that emulates a subset of the EventEmitter API.

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

新增于: v14.5.0

Node.js-specific extension to the EventTarget class that emulates the equivalent EventEmitter API. The only difference between addListener() and addEventListener() is that addListener() will return a reference to the EventTarget.

nodeEventTarget.eventNames()#

新增于: v14.5.0

Node.js-specific extension to the EventTarget class that returns an array of event type names for which event listeners are registered.

nodeEventTarget.listenerCount(type)#

新增于: v14.5.0

Node.js-specific extension to the EventTarget class that returns the number of event listeners registered for the type.

nodeEventTarget.off(type, listener)#

新增于: v14.5.0

Node.js-speciic alias for eventTarget.removeListener().

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

新增于: v14.5.0

Node.js-specific alias for eventTarget.addListener().

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

新增于: v14.5.0

Node.js-specific extension to the EventTarget class that adds a once listener for the given event type. This is equivalent to calling on with the once option set to true.

nodeEventTarget.removeAllListeners([type])#

新增于: v14.5.0

Node.js-specific extension to the EventTarget class. If type is specified, removes all registered listeners for type, otherwise removes all registered listeners.

nodeEventTarget.removeListener(type, listener)#

新增于: v14.5.0

Node.js-specific extension to the EventTarget class that removes the listener for the given type. The only difference between removeListener() and removeEventListener() is that removeListener() will return a reference to the EventTarget.