IO.js Events

稳定度: 2 - 稳定

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

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

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

Class: events.EventEmitter

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

var EventEmitter = require('events');

当一个EventEmitter实例发生了一个错误，一个典型的做法是触发一个error事件。error事件在io.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（如socket和fs）的所有监听器 ，并不是一个明智的选择。

返回一个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 事件监听器函数

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