Node.js v10.13.0 文档


events - 事件触发器#

查看英文版参与翻译

稳定性: 2 - 稳定的

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

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

所有能触发事件的对象都是 EventEmitter 类的实例。 这些对象有一个 eventEmitter.on() 函数,用于将一个或多个函数绑定到命名事件上。 事件的命名通常是驼峰式的字符串。

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');
// 不触发

`error` 事件#

查看英文版参与翻译

EventEmitter 实例出错时,应该触发 'error' 事件。

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

const myEmitter = new MyEmitter();
myEmitter.emit('error', new Error('错误信息'));
// 抛出错误

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

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

EventEmitter 类#

查看英文版参与翻译

EventEmitter 类由 events 模块定义:

const EventEmitter = require('events');

当新增监听器时,会触发 'newListener' 事件;当移除已存在的监听器时,则触发 'removeListener' 事件。

'newListener' 事件#

查看英文版参与翻译

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

在添加监听器之前触发 'newListener' 事件有一个副作用: 如果在回调中注册同名事件的监听器,则该监听器会被插入到正被添加的监听器前面。

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' 事件#

查看英文版参与翻译

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

EventEmitter.listenerCount(emitter, eventName)#

本段落暂不提供翻译

Stability: 0 - Deprecated: Use emitter.listenerCount() instead.

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#

查看英文版参与翻译

默认情况下,每个事件可以注册最多 10 个监听器。 可以使用 emitter.setMaxListeners(n) 方法改变单个 EventEmitter 实例的限制。 可以使用 EventEmitter.defaultMaxListeners 属性改变所有 EventEmitter 实例的默认值。

设置 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));
});

emitter.addListener(eventName, listener)#

查看英文版参与翻译

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

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

查看英文版参与翻译

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

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

emitter.eventNames()#

查看英文版参与翻译

返回已注册监听器的事件名数组。 数组中的值为字符串或 `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()#

查看英文版参与翻译

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

emitter.listenerCount(eventName)#

查看英文版参与翻译

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

emitter.listeners(eventName)#

查看英文版参与翻译

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

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

emitter.off(eventName, listener)#

查看英文版参与翻译

emitter.removeListener() 的别名。

emitter.on(eventName, listener)#

查看英文版参与翻译

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

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

默认情况下,事件监听器会按照添加的顺序依次调用。 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)#

查看英文版参与翻译

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

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

默认情况下,事件监听器会按照添加的顺序依次调用。 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)#

查看英文版参与翻译

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

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

emitter.prependOnceListener(eventName, listener)#

查看英文版参与翻译

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

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

emitter.removeAllListeners([eventName])#

查看英文版参与翻译

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

emitter.removeListener(eventName, listener)#

查看英文版参与翻译

从名为 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.setMaxListeners(n)#

查看英文版参与翻译

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

emitter.rawListeners(eventName)#

查看英文版参与翻译

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