Node.js api 中文文档 - Events


稳定度: 2 - 稳定

node.js中的许多对象触发事件:一个net.Server每次被连接时触发事件,一个fs.readStream当文件打开时触发事件。所有触发事件的对象都是events.EventEmitter的实例。你可以通过require("events");来取得这个模块。

通常,事件名以驼峰字符串来命令,但是这不是严格要求的,任何字符串都是可以接受的。

为了处理触发的事件,我们将函数关联到对象上。这些函数被称为监听器。在监听器中,this指向监听器所关联的EventEmitter实例。

Class: events.EventEmitter

使用require('events')来获取这个EventEmitter类。

var EventEmitter = require('events');

当一个EventEmitter实例发生了一个错误,一个典型的做法是触发一个error事件。error事件在node.js中被视为一个特殊的事件,如果没有为其添加监听器,默认的行为是打印堆栈追踪信息并推出程序。

所有的EventEmitter实例,在被添加新的监听器时,都会触发newListener事件。当有监听器被移除时,都会触发removeListener事件。

emitter.addListener(event, listener)

emitter.on(event, listener)

为指定的事件,在其监听器数组的末尾添加一个新的监听器。不会去检查这个事件是否已经被监听过。事件的多次触发会导致监听器的多次被调用。

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

返回一个emitter,所以可以被链式调用。

emitter.once(event, listener)

为事件添加一个 一次性 监听器。这个监听器只会在下次事件触发时被调用,之后被移除。

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

返回一个emitter,所以可以被链式调用。

emitter.removeListener(event, listener)

从监听器数组中移除指定事件的一个监听器。注意:在数组中,此监听器被移除后,其之后的监听器的索引会被改变。

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

removeListener一次只会从监听器数组中移除一个监听器。如果特定事件的单个的监听器被添加了多次,removeListener也必须调用同样多次来移除它们。

返回一个emitter,所以可以被链式调用。

emitter.removeAllListeners([event])

移除指定事件的所有监听器。使用这个方法来 移除不是在你的代码中创建的emitter(如socketfs)的所有监听器 ,并不是一个明智的选择。

返回一个emitter,所以可以被链式调用。

emitter.setMaxListeners(n)

默认的,当一个特定事件被添加了超过10个监听器时,EventEmitter会打印一个警告。这是一个对于发现内存泄露非常有用的默认警告。但是显然,并不是所有的emitter都应当被限制。这个函数可以用来增加这个上限。如果想要无限制,请设置0

返回一个emitter,所以可以被链式调用。

emitter.getMaxListeners()

返回emitter当前的最大监听器数的值,可能是emitter.setMaxListeners(n)设置的值,或者是EventEmitter.defaultMaxListeners

这个值对于调节最大监听器数来避免 不负责任的警告 或 最大监听器数过大,都非常有用。

emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', function () {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

EventEmitter.defaultMaxListeners

emitter.setMaxListeners(n)在实例级别设置最大监听器数。这个类属性让你可以设置所有EventEmitter的默认最大监听器数,对当前已创建的和未来创建的EventEmitter都有效。请谨慎使用它。

注意,emitter.setMaxListeners(n)仍优先于EventEmitter.defaultMaxListeners

emitter.listeners(event)

返回指定事件的监听器数组。

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

emitter.emit(event[, arg1][, arg2][, ...])

使用提供的参数,执行每一个监听器。

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

Class Method: EventEmitter.listenerCount(emitter, event)

返回指定事件的监听器数。

Event: 'newListener'

  • event String 事件名
  • listener Function 事件监听器函数

这个事件在监听器被添加前触发。当这个事件被触发时,监听器还没有被添加到事件的监听器数组中。在newListener事件的回调函数中拿到事件名时,监听器还没有开始被添加到该事件。

Event: 'removeListener'

  • event String 事件名
  • listener Function 事件监听器函数

这个事件在监听器被移除后触发。当这个事件被触发时,监听器已经从事件的监听器数组中被移除了。

更多Node.js教程

学习更多Node.js教程