Node.js v16.18.1 文档


目录

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.removeListener() 的别名。

                      emitter.on(eventName, listener)#

                      中英对照

                        listener 函数添加到名为 eventName 的事件的监听器数组的末尾。 不检查是否已添加 listener。 多次调用传入相同的 eventNamelistener 组合将导致多次添加和调用 listener

                        
                        

                        
                        

                        emitter.once(eventName, listener)#

                        中英对照

                          为名为 eventName 的事件添加单次的 listener 函数。 下次触发 eventName 时,将移除此监听器,然后再调用。

                          
                          

                          
                          

                          emitter.prependListener(eventName, listener)#

                          中英对照

                            listener 函数添加到名为 eventName 的事件的监听器数组的开头。 不检查是否已添加 listener。 多次调用传入相同的 eventNamelistener 组合将导致多次添加和调用 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#

                                                          中英对照

                                                          EventTargetEvent 对象是一些 Node.js 核心 API 暴露的 EventTarget Web API 的特定于 Node.js 的实现。

                                                          
                                                          

                                                          Node.js EventTarget 对比 DOM EventTarge#

                                                          中英对照

                                                          Node.js EventTargetEventTarget Web API 之间有两个主要区别:

                                                            NodeEventTarget 对比 EventEmitter#

                                                            中英对照

                                                            NodeEventTarget 对象实现了 EventEmitter API 的修改子集,允许它在某些情况下接近地模拟 EventEmitterNodeEventTarget 不是 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#

                                                                      中英对照

                                                                        如果 cancelabletrueevent.preventDefault() 已被调用,则为 true

                                                                        event.eventPhase#

                                                                        中英对照

                                                                          这在 Node.js 中没有使用,纯粹是为了完整性而提供的。

                                                                          event.isTrusted#

                                                                          中英对照

                                                                            <AbortSignal> "abort" 事件是在 isTrusted 设置为 true 的情况下触发的。 在所有其他情况下,该值为 false

                                                                            event.preventDefault()#

                                                                            中英对照

                                                                            如果 cancelabletrue,则将 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#

                                                                                                中英对照

                                                                                                  NodeEventTargetEventTarget 的 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 类的扩展,用于删除给定 typelistenerremoveListener()removeEventListener() 之间的唯一区别是 removeListener() 将返回对 EventTarget 的引用。

                                                                                                                  返回顶部