- assert断言
- async_hooks异步钩子
- async_hooks/context异步上下文
- buffer缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process子进程
- cluster集群
- CLI命令行
- console控制台
- Corepack核心包
- crypto加密
- crypto/webcrypto网络加密
- debugger调试器
- deprecation弃用
- dgram数据报
- diagnostics_channel诊断通道
- dns域名服务器
- domain域
- Error错误
- events事件触发器
- fs文件系统
- global全局变量
- http超文本传输协议
- http2超文本传输协议2.0
- https安全超文本传输协议
- inspector检查器
- Intl国际化
- module模块
- module/cjsCommonJS模块
- module/esmECMAScript模块
- module/package包模块
- net网络
- os操作系统
- path路径
- perf_hooks性能钩子
- policy安全策略
- process进程
- punycode域名代码
- querystring查询字符串
- readline逐行读取
- repl交互式解释器
- report诊断报告
- stream流
- stream/web网络流
- string_decoder字符串解码器
- test测试
- timers定时器
- tls安全传输层
- trace_events跟踪事件
- tty终端
- url网址
- util实用工具
- v8引擎
- vm虚拟机
- wasi网络汇编系统接口
- worker_threads工作线程
- zlib压缩
Node.js v18.7.0 文档
- Node.js 18.7.0
-
►
目录
- events 事件触发器
- 将参数和 this 传给监听器
- 异步 VS 同步
- 仅处理事件一次
- 错误事件
- 捕捉 Promise 拒绝
EventEmitter
类'newListener'
事件'removeListener'
事件emitter.addListener(eventName, listener)
emitter.emit(eventName[, ...args])
emitter.eventNames()
emitter.getMaxListeners()
emitter.listenerCount(eventName)
emitter.listeners(eventName)
emitter.off(eventName, listener)
emitter.on(eventName, listener)
emitter.once(eventName, listener)
emitter.prependListener(eventName, listener)
emitter.prependOnceListener(eventName, listener)
emitter.removeAllListeners([eventName])
emitter.removeListener(eventName, listener)
emitter.setMaxListeners(n)
emitter.rawListeners(eventName)
emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])
events.defaultMaxListeners
events.errorMonitor
events.getEventListeners(emitterOrTarget, eventName)
events.once(emitter, name[, options])
events.captureRejections
events.captureRejectionSymbol
events.listenerCount(emitter, eventName)
events.on(emitter, eventName[, options])
events.setMaxListeners(n[, ...eventTargets])
- events.EventEmitterAsyncResource 类继承 EventEmitter 类
- EventTarget 与 Event API
- Node.js EventTarget 对比 DOM EventTarge
- NodeEventTarget 对比 EventEmitter
- 事件监听器
- EventTarget 的错误处理
Event
类event.bubbles
event.cancelBubble()
event.cancelable
event.composed
event.composedPath()
event.currentTarget
event.defaultPrevented
event.eventPhase
event.isTrusted
event.preventDefault()
event.returnValue
event.srcElement
event.stopImmediatePropagation()
event.stopPropagation()
event.target
event.timeStamp
event.type
EventTarget
类CustomEvent
类NodeEventTarget
类nodeEventTarget.addListener(type, listener[, options])
nodeEventTarget.eventNames()
nodeEventTarget.listenerCount(type)
nodeEventTarget.off(type, listener)
nodeEventTarget.on(type, listener[, options])
nodeEventTarget.once(type, listener[, options])
nodeEventTarget.removeAllListeners([type])
nodeEventTarget.removeListener(type, listener)
- events 事件触发器
-
►
索引
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS模块
- module/esm ECMAScript模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- policy 安全策略
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- ► 其他版本
- 文档搜索
- 会员登录
目录
- events 事件触发器
- 将参数和 this 传给监听器
- 异步 VS 同步
- 仅处理事件一次
- 错误事件
- 捕捉 Promise 拒绝
EventEmitter
类'newListener'
事件'removeListener'
事件emitter.addListener(eventName, listener)
emitter.emit(eventName[, ...args])
emitter.eventNames()
emitter.getMaxListeners()
emitter.listenerCount(eventName)
emitter.listeners(eventName)
emitter.off(eventName, listener)
emitter.on(eventName, listener)
emitter.once(eventName, listener)
emitter.prependListener(eventName, listener)
emitter.prependOnceListener(eventName, listener)
emitter.removeAllListeners([eventName])
emitter.removeListener(eventName, listener)
emitter.setMaxListeners(n)
emitter.rawListeners(eventName)
emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])
events.defaultMaxListeners
events.errorMonitor
events.getEventListeners(emitterOrTarget, eventName)
events.once(emitter, name[, options])
events.captureRejections
events.captureRejectionSymbol
events.listenerCount(emitter, eventName)
events.on(emitter, eventName[, options])
events.setMaxListeners(n[, ...eventTargets])
- events.EventEmitterAsyncResource 类继承 EventEmitter 类
- EventTarget 与 Event API
- Node.js EventTarget 对比 DOM EventTarge
- NodeEventTarget 对比 EventEmitter
- 事件监听器
- EventTarget 的错误处理
Event
类event.bubbles
event.cancelBubble()
event.cancelable
event.composed
event.composedPath()
event.currentTarget
event.defaultPrevented
event.eventPhase
event.isTrusted
event.preventDefault()
event.returnValue
event.srcElement
event.stopImmediatePropagation()
event.stopPropagation()
event.target
event.timeStamp
event.type
EventTarget
类CustomEvent
类NodeEventTarget
类nodeEventTarget.addListener(type, listener[, options])
nodeEventTarget.eventNames()
nodeEventTarget.listenerCount(type)
nodeEventTarget.off(type, listener)
nodeEventTarget.on(type, listener[, options])
nodeEventTarget.once(type, listener[, options])
nodeEventTarget.removeAllListeners([type])
nodeEventTarget.removeListener(type, listener)
events 事件触发器#
Node.js 的大部分核心 API 都是围绕惯用的异步事件驱动架构构建的,在该架构中,某些类型的对象(称为"触发器")触发命名事件,使 Function
对象("监听器")被调用。
将参数和 this 传给监听器#
eventEmitter.emit()
方法允许将任意一组参数传给监听器函数。
记住,当调用普通的监听器函数时,标准的 this
关键字会被有意地设置为引用监听器绑定到的 EventEmitter
实例。
异步 VS 同步#
EventEmitter
按照注册的顺序同步地调用所有监听器。
这确保了事件的正确排序,并有助于避免竞争条件和逻辑错误。
在适当的时候,监听器函数可以使用 setImmediate()
或 process.nextTick()
方法切换到异步的操作模式:
仅处理事件一次#
当使用 eventEmitter.on()
方法注册监听器时,每次触发命名事件时都会调用该监听器。
错误事件#
当 EventEmitter
实例中发生错误时,典型的操作是触发 'error'
事件。
这些在 Node.js 中被视为特殊情况。
捕捉 Promise 拒绝#
将 async
函数与事件句柄一起使用是有问题的,因为它会在抛出异常的情况下导致未处理的拒绝:
EventEmitter
类#
EventEmitter
类由 node:events
模块定义和暴露:
'newListener'
事件#
在将监听器添加到其内部监听器数组之前,EventEmitter
实例将触发自身的 'newListener'
事件。
'removeListener'
事件#
在移除 listener
后触发 'removeListener'
事件。
emitter.addListener(eventName, listener)
#
emitter.on(eventName, listener)
的别名。
emitter.emit(eventName[, ...args])
#
按注册顺序同步地调用为名为 eventName
的事件注册的每个监听器,并将提供的参数传给每个监听器。
emitter.eventNames()
#
返回列出触发器已为其注册监听器的事件的数组。
数组中的值是字符串或 Symbol
。
emitter.getMaxListeners()
#
返回 EventEmitter
的当前最大监听器数的值,该值由 emitter.setMaxListeners(n)
设置或默认为 events.defaultMaxListeners
。
emitter.listenerCount(eventName)
#
返回监听名为 eventName
的事件的监听器数量。
emitter.listeners(eventName)
#
返回名为 eventName
的事件的监听器数组的副本。
emitter.off(eventName, listener)
#
emitter.on(eventName, listener)
#
将 listener
函数添加到名为 eventName
的事件的监听器数组的末尾。
不检查是否已添加 listener
。
多次调用传入相同的 eventName
和 listener
组合将导致多次添加和调用 listener
。
emitter.once(eventName, listener)
#
为名为 eventName
的事件添加单次的 listener
函数。
下次触发 eventName
时,将移除此监听器,然后再调用。
emitter.prependListener(eventName, listener)
#
将 listener
函数添加到名为 eventName
的事件的监听器数组的开头。
不检查是否已添加 listener
。
多次调用传入相同的 eventName
和 listener
组合将导致多次添加和调用 listener
。
emitter.prependOnceListener(eventName, listener)
#
将名为 eventName
的事件的单次 listener
函数添加到监听器数组的开头。
下次触发 eventName
时,将移除此监听器,然后再调用。
emitter.removeAllListeners([eventName])
#
删除所有监听器,或指定 eventName
的监听器。
emitter.removeListener(eventName, listener)
#
从名为 eventName
的事件的监听器数组中移除指定的 listener
。
emitter.setMaxListeners(n)
#
默认情况下,如果为特定事件添加了 10
个以上的监听器,则 EventEmitter
将打印警告。
这是一个有用的默认值,有助于查找内存泄漏。
emitter.setMaxListeners()
方法允许修改此特定 EventEmitter
实例的限制。
该值可以设置为 Infinity
(或 0
)以指示无限数量的监听器。
emitter.rawListeners(eventName)
#
返回名为 eventName
的事件的监听器数组的副本,包括任何封装器(例如由 .once()
创建的封装器)。
emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])
#
Symbol.for('nodejs.rejection')
方法被调用,以防在触发事件时发生 promise 拒绝,并且在触发器上启用了 captureRejections
。
可以使用 events.captureRejectionSymbol
代替 Symbol.for('nodejs.rejection')
。
events.defaultMaxListeners
#
默认情况下,最多可为任何单个事件注册 10
个监听器。
可以使用 emitter.setMaxListeners(n)
方法为单个 EventEmitter
实例更改此限制。
要更改所有 EventEmitter
实例的默认值,则可以使用 events.defaultMaxListeners
属性。
如果该值不是正数,则抛出 RangeError
。
events.errorMonitor
#
此符号应用于安装仅监视 'error'
事件的监听器。
在调用常规 'error'
监听器之前调用使用此符号安装的监听器。
events.getEventListeners(emitterOrTarget, eventName)
#
返回名为 eventName
的事件的监听器数组的副本。
events.once(emitter, name[, options])
#
创建 Promise
,其在 EventEmitter
触发给定事件时被履行,或者如果 EventEmitter
在等待时触发 'error'
则被拒绝。
Promise
将使用触发给定事件的所有参数的数组解决。
等待 process.nextTick() 上触发的多个事件#
当使用 events.once()
函数等待在同一批 process.nextTick()
操作中触发的多个事件时,或者同步触发多个事件时,有一个边缘情况值得注意。
具体来说,因为 process.nextTick()
队列在 Promise
微任务队列之前被排空,并且因为 EventEmitter
同步触发所有事件,所以 events.once()
有可能错过事件。
events.captureRejections
#
值: <boolean>
events.captureRejectionSymbol
#
值: Symbol.for('nodejs.rejection')
events.listenerCount(emitter, eventName)
#
返回在给定 emitter
上注册的给定 eventName
的监听器数量的类方法。
events.on(emitter, eventName[, options])
#
返回迭代 eventName
事件的 AsyncIterator
。
如果 EventEmitter
触发 'error'
,则将抛出错误。
它在退出循环时删除所有监听器。
每次迭代返回的 value
是由触发的事件参数组成的数组。
events.setMaxListeners(n[, ...eventTargets])
#
events.EventEmitterAsyncResource 类继承 EventEmitter 类#
为需要手动异步跟踪的 EventEmitter
集成 EventEmitter
和 <AsyncResource>。
具体来说,events.EventEmitterAsyncResource
实例触发的所有事件都将在其异步上下文中运行。
new events.EventEmitterAsyncResource(options)
#
eventemitterasyncresource.asyncId
#
eventemitterasyncresource.asyncResource
#
返回的 AsyncResource
对象具有额外的 eventEmitter
属性,提供对此 EventEmitterAsyncResource
的引用。
eventemitterasyncresource.emitDestroy()
#
调用所有的 destroy
钩子。
这应该只被调用一次。
如果多次调用,则会报错。
这个必须手动调用。
如果资源留给 GC 收集,则永远不会调用 destroy
钩子。
eventemitterasyncresource.triggerAsyncId
#
EventTarget 与 Event API#
EventTarget
和 Event
对象是一些 Node.js 核心 API 暴露的 EventTarget
Web API 的特定于 Node.js 的实现。
Node.js EventTarget 对比 DOM EventTarge#
Node.js EventTarget
和 EventTarget
Web API 之间有两个主要区别:
NodeEventTarget 对比 EventEmitter#
NodeEventTarget
对象实现了 EventEmitter
API 的修改子集,允许它在某些情况下接近地模拟 EventEmitter
。
NodeEventTarget
不是 EventEmitter
的实例,在大多数情况下不能代替 EventEmitter
。
事件监听器#
为事件 type
注册的事件监听器可以是 JavaScript 函数,也可以是具有值为函数的 handleEvent
属性的对象。
EventTarget 的错误处理#
当注册的事件监听器抛出错误(或返回拒绝的 Promise)时,默认情况下,错误将被视为 process.nextTick()
上的未捕获异常。
这意味着 EventTarget
中未捕获的异常将默认终止 Node.js 进程。
Event
类#
Event
对象是对 Event
Web API 的改写。
实例由 Node.js 在内部创建。
event.bubbles
#
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.cancelBubble()
#
event.stopPropagation()
的别名。
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.cancelable
#
event.composed
#
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.composedPath()
#
返回包含当前 EventTarget
作为唯一条目的数组,如果未调度事件则返回空数组。
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.currentTarget
#
event.target
的别名。
event.defaultPrevented
#
如果 cancelable
为 true
且 event.preventDefault()
已被调用,则为 true
。
event.eventPhase
#
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.isTrusted
#
<AbortSignal> "abort"
事件是在 isTrusted
设置为 true
的情况下触发的。
在所有其他情况下,该值为 false
。
event.preventDefault()
#
如果 cancelable
是 true
,则将 defaultPrevented
属性设置为 true
。
event.returnValue
#
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.srcElement
#
event.target
的别名。
event.stopImmediatePropagation()
#
当前事件监听器完成后停止调用。
event.stopPropagation()
#
这在 Node.js 中没有使用,纯粹是为了完整性而提供的。
event.target
#
event.timeStamp
#
创建 Event
对象时的毫秒时间戳。
event.type
#
事件类型标识符。
EventTarget
类#
eventTarget.addEventListener(type, listener[, options])
#
为 type
事件添加新的句柄。
对于每个 type
和每个 capture
选项值,任何给定的 listener
仅添加一次。
eventTarget.dispatchEvent(event)
#
将 event
调度到 event.type
的句柄列表。
eventTarget.removeEventListener(type, listener)
#
从事件 type
的句柄列表中删除 listener
。
CustomEvent
类#
CustomEvent
对象是对 CustomEvent
Web API 的改写。
实例由 Node.js 在内部创建。
event.detail
#
只读。
NodeEventTarget
类#
NodeEventTarget
是 EventTarget
的 Node.js 特定扩展,它模拟了 EventEmitter
API 的子集。
nodeEventTarget.addListener(type, listener[, options])
#
EventTarget
类的 Node.js 特定扩展,可模拟等效的 EventEmitter
API。
addListener()
和 addEventListener()
之间的唯一区别是 addListener()
将返回对 EventTarget
的引用。
nodeEventTarget.eventNames()
#
Node.js 特定于 EventTarget
类的扩展,它返回事件 type
名称的数组,事件监听器注册了这些名称。
nodeEventTarget.listenerCount(type)
#
EventTarget
类的 Node.js 特定扩展,返回为 type
注册的事件监听器的数量。
nodeEventTarget.off(type, listener)
#
eventTarget.removeListener()
的 Node.js 特定别名。
nodeEventTarget.on(type, listener[, options])
#
eventTarget.addListener()
的 Node.js 特定别名。
nodeEventTarget.once(type, listener[, options])
#
EventTarget
类的 Node.js 特定扩展,它为给定的事件 type
添加了 once
监听器。
这相当于调用 on
并将 once
选项设置为 true
。
nodeEventTarget.removeAllListeners([type])
#
EventTarget
类的 Node.js 特定扩展。
如果指定了 type
,则删除 type
的所有注册监听器,否则删除所有注册的监听器。
nodeEventTarget.removeListener(type, listener)
#
Node.js 特定于 EventTarget
类的扩展,用于删除给定 type
的 listener
。
removeListener()
和 removeEventListener()
之间的唯一区别是 removeListener()
将返回对 EventTarget
的引用。