Events

穩(wěn)定度: 2 - 穩(wěn)定

io.js中的許多對象觸發(fā)事件：一個(gè)net.Server每次被連接時(shí)觸發(fā)事件，一個(gè)fs.readStream當(dāng)文件打開時(shí)觸發(fā)事件。所有觸發(fā)事件的對象都是events.EventEmitter的實(shí)例。你可以通過require("events");來取得這個(gè)模塊。

通常，事件名以駝峰字符串來命令，但是這不是嚴(yán)格要求的，任何字符串都是可以接受的。

為了處理觸發(fā)的事件，我們將函數(shù)關(guān)聯(lián)到對象上。這些函數(shù)被稱為監(jiān)聽器。在監(jiān)聽器中，this指向監(jiān)聽器所關(guān)聯(lián)的EventEmitter實(shí)例。

Class: events.EventEmitter

使用require('events')來獲取這個(gè)EventEmitter類。

var EventEmitter = require('events');

當(dāng)一個(gè)EventEmitter實(shí)例發(fā)生了一個(gè)錯(cuò)誤，一個(gè)典型的做法是觸發(fā)一個(gè)error事件。error事件在io.js中被視為一個(gè)特殊的事件，如果沒有為其添加監(jiān)聽器，默認(rèn)的行為是打印堆棧追蹤信息并推出程序。

所有的EventEmitter實(shí)例，在被添加新的監(jiān)聽器時(shí)，都會觸發(fā)newListener事件。當(dāng)有監(jiān)聽器被移除時(shí)，都會觸發(fā)removeListener事件。

emitter.addListener(event, listener)

emitter.on(event, listener)

為指定的事件，在其監(jiān)聽器數(shù)組的末尾添加一個(gè)新的監(jiān)聽器。不會去檢查這個(gè)事件是否已經(jīng)被監(jiān)聽過。事件的多次觸發(fā)會導(dǎo)致監(jiān)聽器的多次被調(diào)用。

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

返回一個(gè)emitter，所以可以被鏈?zhǔn)秸{(diào)用。

emitter.once(event, listener)

為事件添加一個(gè) 一次性 監(jiān)聽器。這個(gè)監(jiān)聽器只會在下次事件觸發(fā)時(shí)被調(diào)用，之后被移除。

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

返回一個(gè)emitter，所以可以被鏈?zhǔn)秸{(diào)用。

emitter.removeListener(event, listener)

從監(jiān)聽器數(shù)組中移除指定事件的一個(gè)監(jiān)聽器。注意：在數(shù)組中，此監(jiān)聽器被移除后，其之后的監(jiān)聽器的索引會被改變。

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

removeListener一次只會從監(jiān)聽器數(shù)組中移除一個(gè)監(jiān)聽器。如果特定事件的單個(gè)的監(jiān)聽器被添加了多次，removeListener也必須調(diào)用同樣多次來移除它們。

返回一個(gè)emitter，所以可以被鏈?zhǔn)秸{(diào)用。

emitter.removeAllListeners([event])

移除指定事件的所有監(jiān)聽器。使用這個(gè)方法來 移除不是在你的代碼中創(chuàng)建的emitter（如socket和fs）的所有監(jiān)聽器 ，并不是一個(gè)明智的選擇。

返回一個(gè)emitter，所以可以被鏈?zhǔn)秸{(diào)用。

emitter.setMaxListeners(n)

默認(rèn)的，當(dāng)一個(gè)特定事件被添加了超過10個(gè)監(jiān)聽器時(shí)，EventEmitter會打印一個(gè)警告。這是一個(gè)對于發(fā)現(xiàn)內(nèi)存泄露非常有用的默認(rèn)警告。但是顯然，并不是所有的emitter都應(yīng)當(dāng)被限制。這個(gè)函數(shù)可以用來增加這個(gè)上限。如果想要無限制，請?jiān)O(shè)置0。

返回一個(gè)emitter，所以可以被鏈?zhǔn)秸{(diào)用。

emitter.getMaxListeners()

返回emitter當(dāng)前的最大監(jiān)聽器數(shù)的值，可能是emitter.setMaxListeners(n)設(shè)置的值，或者是EventEmitter.defaultMaxListeners。

這個(gè)值對于調(diào)節(jié)最大監(jiān)聽器數(shù)來避免 不負(fù)責(zé)任的警告 或 最大監(jiān)聽器數(shù)過大，都非常有用。

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

EventEmitter.defaultMaxListeners

emitter.setMaxListeners(n)在實(shí)例級別設(shè)置最大監(jiān)聽器數(shù)。這個(gè)類屬性讓你可以設(shè)置所有EventEmitter的默認(rèn)最大監(jiān)聽器數(shù)，對當(dāng)前已創(chuàng)建的和未來創(chuàng)建的EventEmitter都有效。請謹(jǐn)慎使用它。

注意，emitter.setMaxListeners(n)仍優(yōu)先于EventEmitter.defaultMaxListeners。

emitter.listeners(event)

返回指定事件的監(jiān)聽器數(shù)組。

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

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

使用提供的參數(shù)，執(zhí)行每一個(gè)監(jiān)聽器。

如果事件有監(jiān)聽器，那么返回true，否則返回false。

Class Method: EventEmitter.listenerCount(emitter, event)

返回指定事件的監(jiān)聽器數(shù)。

Event: 'newListener'

• event String 事件名
• listener Function 事件監(jiān)聽器函數(shù)

這個(gè)事件在監(jiān)聽器被添加前觸發(fā)。當(dāng)這個(gè)事件被觸發(fā)時(shí)，監(jiān)聽器還沒有被添加到事件的監(jiān)聽器數(shù)組中。在newListener事件的回調(diào)函數(shù)中拿到事件名時(shí)，監(jiān)聽器還沒有開始被添加到該事件。

Event: 'removeListener'

• event String 事件名
• listener Function 事件監(jiān)聽器函數(shù)

這個(gè)事件在監(jiān)聽器被移除后觸發(fā)。當(dāng)這個(gè)事件被觸發(fā)時(shí)，監(jiān)聽器已經(jīng)從事件的監(jiān)聽器數(shù)組中被移除了。