文档: 4 - API 冻结
Node 里很多对象会分发事件: 每次有连接的时候 net.Server
会分发事件,当文件打开的时候 fs.readStream
会分发事件。所有能分发事件的对象都是 events.EventEmitter
的实例。通过 require("events");
能访问这个模块。
一般来说,事件名都遵照驼峰规则,但这不是强制规定,任何形式的字符串都可以做为事件名。
为了处理事件,通常将函数关联到对象上。这些函数也叫监听者(listeners)。在这个函数里,this
指向 监听者所关联的 EventEmitter
。
通过 require('events').EventEmitter
获取 EventEmitter 类。
EventEmitter
实例遇到错误后,通常会触发一个错误事件。错误事件在 node 里是特殊例子。如果没有监听者,默认的操作是打印一个堆栈信息并退出程序。
当添加新的监听者时, EventEmitters 会触发'newListener'
事件,当移除时会触发'removeListener'
。
添加一个监听者到特定 event
的监听数组的尾部,触发器不会检查是否已经添加过这个监听者。 多次调用相同的 event
和 listener
将会导致 listener
添加多次。
server.on('connection', function (stream) { console.log('someone connected!'); });
返回 emitter。
给事件添加一个一次性的 listener,这个 listener 只会被触发一次,之后就会被移除。
server.once('connection', function (stream) { console.log('Ah, we have our first user!'); });
返回emitter。
从一个某个事件的 listener 数组中移除一个 listener。注意,这个操作会改变 listener 数组内容的次序。
var callback = function(stream) { console.log('someone connected!'); }; server.on('connection', callback); // ... server.removeListener('connection', callback);
removeListener
最多会移除数组里的一个 listener。如果多次添加同一个 listener 到数组,那就需要多次调用 removeListener
来移除每一个实例。
返回emitter。
移除所有的 listener,或者某个事件的 listener。最好不要移除全部 listener,尤其是那些不是你传入的(比如 socket 或 文件流)。
返回emitter。
默认情况下,给单个事件添加超过 10 个 listener ,事件分发器会打印警告。这样有利于检查内存泄露。不过不是所有的分发器都应该限制在 10 个,这个函数允许改变 listener 数量,无论是 0 还是更多。
返回emitter。
emitter.setMaxListeners(n)
设置一个分发器的最大 listener 数,而这个函数会立即设置所有EventEmitter
的当前值和默认值。要小心使用。
请注意, emitter.setMaxListeners(n)
的优先级高于 EventEmitter.defaultMaxListeners
.
返回事件的 listener 数组。
server.on('connection', function (stream) { console.log('someone connected!'); }); console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
使用指定的参数顺序的执行每一个 listener.
如果事件有 listener,返回 true
, 否则 false
返回指定事件的 listener 数量。
event
{String} 事件名
listener
{Function} 事件处理函数
添加 listener 的时候会触发这个事件。当这个事件触发的时候,listener 可能还没添加到 listener 数组。
event
{String} 事件名
listener
{Function} 事件处理函数
删除 listener 的时候会触发这个事件。当这个事件触发的时候,listener 可能还还没从 listener 数组移除。