events 事件模块:订阅、触发与移除
🎯 引言
学完这篇文章,你能用 EventEmitter 通知其他模块任务结果,并管理监听函数。
🧱 EventEmitter 用来发出与接收通知
EventEmitter 是 Node.js 的事件通知对象。一个功能完成工作后发出事件,其他部分提前订阅,就能执行自己的处理。例如文件处理完成后,日志功能收到通知并记录名称。
事件名由双方约定,比如 done。它不是 Node.js 自动识别的业务动作,只有程序明确调用触发方法时,监听函数才会运行。
创建 events.mjs,先准备事件对象,后续代码按顺序追加:
import { EventEmitter } from 'node:events'
const bus = new EventEmitter()
bus 是这组通知的发送与订阅入口。这里只创建对象,还没有输出。
👂 on:先登记谁要收到通知
const log = file => console.log(`已处理:${file}`)
bus.on('done', log)
on 的参数是事件名和监听函数。执行后仍然没有输出,因为注册不等于触发。函数被保存下来,等待以后收到 done。
on 返回这个事件对象本身,不是监听函数的执行结果;日常注册时通常无需使用这个返回值。
📣 emit:触发通知并传数据
bus.emit('done', 'note.txt')
运行当前文件,会输出 已处理:note.txt。事件名后面的值被传给监听函数,所以 log 的 file 参数收到了 note.txt。
emit 返回是否存在该事件的监听函数:有则为 true,没有则为 false。这个返回值不代表某项业务已经成功,只表示是否有监听者。
再次触发 done,on 注册的监听还会执行,因此它适合持续观察。
🧹 off:不再需要时取消监听
bus.off('done', log)
bus.emit('done', 'other.txt')
新增的这次触发没有日志,因为 log 已经移除。off 必须传入注册时的函数引用;需要移除的监听应保留引用,避免注册匿名函数后无法解除。
组件、任务或服务对象结束使用时,移除不再需要的监听,能避免重复处理以及长期保留无用数据。
1️⃣ once:只处理一次通知
不论后续发生多少次,只关心首次完成时用 once:
bus.once('ready', () => console.log('准备完成'))
bus.emit('ready')
bus.emit('ready')
只输出一次 准备完成。监听在首次调用时自动移除;它也不会补收注册之前已经发出的历史事件。
⏱️ emit 默认同步调用监听函数
在上述文件中追加一个新的事件例子:
bus.on('check', () => console.log('监听执行'))
bus.emit('check')
console.log('触发之后')
结果先是 监听执行,然后是 触发之后。emit 会在继续下一句之前调用监听;多个监听按注册顺序执行。因此耗时监听仍会阻塞后续 JavaScript。
📂 异步监听:在监听内部处理文件读取失败
事件适合发出通知;触发通知的代码不会等待异步监听完成。 例如通知日志功能读取一份文件,读取成功或失败都由日志功能自己报告。
单独新建 async-events.mjs,先准备事件对象和文件读取方法:
import { EventEmitter } from 'node:events'
import { readFile } from 'node:fs/promises'
const bus = new EventEmitter()
接着注册监听,把 try/catch 放在异步监听内部:
bus.on('show-file', async file => {
try {
const text = await readFile(file, 'utf8')
console.log('文件内容:', text)
} catch (error) {
console.error('读取失败:', error.code)
process.exitCode = 1
}
})
最后触发通知:
bus.emit('show-file', 'note.txt')
console.log('通知已发出')
在同目录准备内容为 hello 的 note.txt,运行 node async-events.mjs:先输出 通知已发出,之后才输出 文件内容: hello。文件不存在时,先输出通知,再报告 读取失败: ENOENT,程序结束时返回退出码 1。
emit 调用了监听,但不会接收并等待它返回的 Promise。把 try/catch 放在 bus.emit(...) 外面,抓不到稍后发生的文件读取失败;写成 await bus.emit(...) 也无法等待读取完成,因为 emit 返回的是布尔值。
⏳ 下一步依赖读取结果时,直接等待函数
如果你必须先取得文件内容才能继续,就让函数返回读取结果,由调用处等待它。另存为 read-task.mjs:
import { readFile } from 'node:fs/promises'
async function loadText(file) {
return readFile(file, 'utf8')
}
在同一文件中追加调用:
try {
const text = await loadText('note.txt')
console.log('文件内容:', text)
console.log('读取完成,可以继续处理')
} catch (error) {
console.error('读取失败:', error.code)
process.exitCode = 1
}
运行 node read-task.mjs,文件存在时先输出内容,再输出 读取完成,可以继续处理;文件不存在时只报告读取失败,不执行成功分支。
两种方式的选择依据是:只通知其他功能自行处理,用事件;当前任务需要取得结果再继续,用函数返回值和 await。
⚠️ error 是需要处理的特殊事件
对可能报告错误的事件对象,先注册错误监听,再执行相关操作:
bus.on('error', error => console.error(error.message))
bus.emit('error', new Error('读取失败'))
输出 读取失败。如果没有 error 监听就触发该事件,Node.js 会抛出错误;它与普通事件没有监听时返回 false 的行为不同。
本篇默认创建的 EventEmitter 不会把 async 监听的 Promise 拒绝自动转成 error 事件。上面的异步读取仍要在监听内部捕获,不能只注册 error 监听就认为所有失败都处理好了。
❓ 知识问答
Q1:事件先触发再订阅能收到吗?
普通 EventEmitter 不保存历史事件,后订阅不会补收到此前通知。
Q2:为什么一次触发输出多次?
检查是否重复注册了监听,on 不会自动去重。
Q3:emit 能取得 async 监听的结果吗?
不能。emit 返回是否存在监听者,不返回监听函数的结果;需要文件内容时,使用上面的 loadText,并在调用处 await。
🧪 小练习
添加一个 once 监听,连续触发两次事件,比较它与 on 监听的输出次数。
// 请在这里编写代码
🎉 现在可以用自己的例子验证这些用法啦!
