### 穩定度: 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 事件監聽器函數
這個事件在監聽器被移除后觸發。當這個事件被觸發時,監聽器已經從事件的監聽器數組中被移除了。