事件

文檔: 4 - API 凍結

Node 里很多對象會分發事件： 每次有連接的時候 net.Server 會分發事件，當文件打開的時候 fs.readStream 會分發事件。所有能分發事件的對象都是 events.EventEmitter 的實例。通過 require("events"); 能訪問這個模塊。

一般來說，事件名都遵照駝峰規則，但這不是強制規定，任何形式的字符串都可以做為事件名。

為了處理事件，通常將函數關聯到對象上。這些函數也叫監聽者(listeners)。在這個函數里，this 指向 監聽者所關聯的 EventEmitter。

類: events.EventEmitter

通過 require('events').EventEmitter 獲取 EventEmitter 類。

EventEmitter 實例遇到錯誤后，通常會觸發一個錯誤事件。錯誤事件在 node 里是特殊例子。如果沒有監聽者，默認的操作是打印一個堆棧信息并退出程序。

當添加新的監聽者時， EventEmitters 會觸發'newListener' 事件，當移除時會觸發'removeListener'。

emitter.addListener(event, listener)

emitter.on(event, listener)

添加一個監聽者到特定 event 的監聽數組的尾部，觸發器不會檢查是否已經添加過這個監聽者。 多次調用相同的 event 和 listener 將會導致 listener 添加多次。

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

返回 emitter。

emitter.once(event, listener)

給事件添加一個一次性的 listener，這個 listener 只會被觸發一次，之后就會被移除。

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

返回emitter。

emitter.removeListener(event, listener)

從一個某個事件的 listener 數組中移除一個 listener。注意，這個操作會改變 listener 數組內容的次序。

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

removeListener 最多會移除數組里的一個 listener。如果多次添加同一個 listener 到數組，那就需要多次調用 removeListener 來移除每一個實例。

返回emitter。

emitter.removeAllListeners([event])

移除所有的 listener，或者某個事件的 listener。最好不要移除全部 listener，尤其是那些不是你傳入的（比如 socket 或 文件流）。

返回emitter。

emitter.setMaxListeners(n)

默認情況下，給單個事件添加超過 10 個 listener ，事件分發器會打印警告。這樣有利于檢查內存泄露。不過不是所有的分發器都應該限制在 10 個，這個函數允許改變 listener 數量，無論是 0 還是更多。

返回emitter。

EventEmitter.defaultMaxListeners

emitter.setMaxListeners(n) 設置一個分發器的最大 listener 數，而這個函數會立即設置所有EventEmitter 的當前值和默認值。要小心使用。

請注意， emitter.setMaxListeners(n) 的優先級高于 EventEmitter.defaultMaxListeners.

emitter.listeners(event)

返回事件的 listener 數組。

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

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

使用指定的參數順序的執行每一個 listener.

如果事件有 listener,返回 true， 否則 false

類方法: EventEmitter.listenerCount(emitter, event)

返回指定事件的 listener 數量。

Event: 'newListener'

• event {String} 事件名
• listener {Function} 事件處理函數

添加 listener 的時候會觸發這個事件。當這個事件觸發的時候，listener 可能還沒添加到 listener 數組。

Event: 'removeListener'

• event {String} 事件名
• listener {Function} 事件處理函數

刪除 listener 的時候會觸發這個事件。當這個事件觸發的時候，listener 可能還還沒從 listener 數組移除。