Node.js API —— Events（事件）

// 說明

    Node API 版本爲 v0.10.31。
    中文參考：http://nodeapi.ucdok.com/#/api/，http://blog.sina.com.cn/oleoneoy

    本段爲博主註解。

目錄

● 事件
    ○ Class: events.EventEmitter

       ■ emitter.addListener(event, listener)

       ■ emitter.on(event, listener)

       ■ emitter.once(event, listener)

       ■ emitter.removeListener(event, listener)

       ■ emitter.removeAllListener([events])

       ■ emitter.setMaxListener(n)

       ■ emitter.listeners(event)

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

       ■ Class Method: EventEmitter.listenerCount(emitter, event)

       ■ Event: 'new listener'

       ■ Event: 'removeListener'

 事件

穩定性：4 - API 凍結

    Node 的不少對象都會發射事件：net.Server 在每次對等鏈接鏈接過來時發射一個事件，fs.readStream 在文件打開時發射一個事件。全部發射事件的對象都是 events.eventEmitter 的實例。你能夠這樣來訪問本模塊：require("events");
    典型地，事件名用一個駝峯格式字符串表明，然而，那沒有任何嚴格的約束，由於任何的字符串均可被接受。
    而後函數就能夠被關聯到對象上，當一個事件被髮射後函數會被執行。這些函數被稱爲監聽器。在監聽器函數裏面，this 指向監聽器關聯的 EventEmitter。

Class: events.EventEmitter

    爲了訪問 EventEmitter 類，require('events').EventEmitter。
    當一個 EventEmitter 實例遇到一個錯誤，典型的操做是發射一個 'error' 事件。 在node 中 Error 事件做爲特殊狀況對待。若是它沒有任何監聽器，那麼默認的操做是打印堆棧跟蹤信息而後退出程序。
    全部的 EventEmitter 都會在新的監聽器添加時發射事件 'newListener'，在監聽器移除時發射事件 'removeListener'。

emitter.addListener(event, listener)
emitter.on(event, listener)

    爲特定的事件添加一個監聽器到監聽器數組的末尾。

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

    返回發射器，於是能夠鏈式調用。

emitter.once(event, listener)

   爲事件添加一個執行一次的監聽器。監聽器只在下次事件觸發的時候調用，以後它會被移除。

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

   返回發射器，於是能夠鏈式調用。

emitter.removeListener(event, listener)

    爲指定的事件從監聽器數組裏移除指定的監聽器。警告：這將改變該監聽器後面的監聽器元素的數組下標。

1 var callback = function(stream) {
2   console.log('someone connected!');
3 };
4 server.on('connection', callback);
5 // ...
6 server.removeListener('connection', callback);

     返回發射器，於是能夠鏈式調用。

emitter.removeAllListener([event])

    移除全部的監聽器，或特定時間的全部監聽器。移除在代碼其它地方添加的監聽器不是一個好主意，特別是當它關聯在一個不是你建立的發射器上（例如 socket 或文件流）。
    返回發射器，於是能夠鏈式調用。

emitter.setMaxListeners(n)

     默認狀況下若是超過10個監聽器被添加到特定的事件上， EventEmitter 將打印一個警告。這是一個有用的默認值，能夠幫助找到內存泄露。明顯地不是全部發射器應該限制爲10。本函數容許它增加。若無限制設置爲0。

emitter.listeners(event)

    返回特定事件的監聽器數組。

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

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

    使用提供的參數按順序執行每一個監聽器。
    若是有監聽器返回 true，不然返回 false。

Class Method: EventEmitter.listenerCount(emitter, event)

    返回給出事件的監聽器數量。

Event: 'newListener'

    ● event 字符串類型 事件名
    ● listener 函數類型 事件處理函數

    在每次添加新的監聽器時本事件被髮射。若是 listener 在 emitter.listeners(event) 返回的列表中，本函數的行爲未明確指明。

Event: 'removeListener'

    ● event 字符串類型 事件名
    ● listener 函數類型 事件處理函數

    在每次移除監聽器時本事件被髮射。若是 listener 在 emitter.listeners(event) 返回的列表中，本函數的行爲未明確指明。