BeShell 文档

简体中文

English

简体中文

English

类: EventEmitter

约 1928 字大约 6 分钟

2026-03-20

简介

EventEmitter 类，事件发布/订阅基类

EventEmitter 是一个基础类，提供了事件发布/订阅（Pub/Sub）模式的实现。 其他类可以继承 EventEmitter 来获得事件处理能力。

EventEmitter 支持以下特性：

  • 监听事件：on()、once()
  • 取消监听：off()
  • 触发事件：emit()
  • 监听所有事件：使用通配符 *，监听器会收到事件名作为第一个参数
  • 竞争监听：race() - 多个事件中只响应第一个触发的事件

示例：

import { EventEmitter } from 'beshell'

// 创建 EventEmitter 实例
const emitter = new EventEmitter()

// 监听特定事件
emitter.on('data', (data) => {
  console.log('收到数据:', data)
})

// 触发事件
emitter.emit('data', 'hello world')

// 只监听一次
emitter.once('connect', () => {
  console.log('已连接')
})

// 使用通配符 * 监听所有事件
// 监听器第一个参数是事件名，后续参数是触发事件时传递的参数
emitter.on('*', (eventName, ...args) => {
  console.log('事件:', eventName, '参数:', args)
})

// 触发 'data' 事件时，通配符监听器收到: 'data', 'hello world'
emitter.emit('data', 'hello world')

类方法

方法 on

原型: on (event:string|Array<string>, handle:function, norepeat:boolean=false)

监听事件

为指定事件添加一个监听器。当事件被触发时，监听器函数会被调用。 可以多次调用 on() 为同一个事件添加多个监听器，它们会按添加顺序执行。

使用通配符 * 可以监听所有事件，监听器会收到事件名作为第一个参数。

示例：

emitter.on('message', (msg) => {
  console.log('收到消息:', msg)
})

// 监听多个事件
emitter.on(['connect', 'disconnect'], (event) => {
  console.log('状态变化:', event)
})

// 使用通配符监听所有事件
emitter.on('*', (eventName, ...args) => {
  console.log('事件:', eventName, '参数:', args)
})

// 不重复添加相同的监听器
emitter.on('update', handler, true)  // norepeat=true

参数:

  • event

    类型string, Array<string>

    参数说明事件名称、事件名称数组，或通配符 *

  • handle

    类型function

    参数说明事件处理函数

  • norepeat

    类型boolean

    默认值false

    参数说明如果为 true，不重复添加相同的处理函数

返回值:

类型undefined

方法 once

原型: once (eventName:string, handle:function, norepeat:boolean=false)

监听事件（只触发一次）

为指定事件添加一个只触发一次的监听器。事件触发后，监听器会自动移除。

示例：

emitter.once('ready', () => {
  console.log('准备就绪，只触发一次')
})

参数:

  • eventName

    类型string

    参数说明事件名称

  • handle

    类型function

    参数说明事件处理函数

  • norepeat

    类型boolean

    默认值false

    参数说明如果为 true，不重复添加相同的处理函数

返回值:

类型undefined

方法 race

原型: race (events:Array<string>, callback:function)

竞争监听

同时监听多个事件，只响应第一个触发的事件，然后自动取消监听。 适用于等待多个异步事件中任意一个完成的场景。

示例：

// 等待 connect 或 error 事件，只处理第一个触发的
emitter.race(['connect', 'error'], (eventName, ...args) => {
  console.log('最先触发的事件:', eventName)
})

参数:

  • events

    类型Array<string>

    参数说明事件名称数组

  • callback

    类型function

    参数说明回调函数，参数为 (eventName, ...args)

返回值:

类型undefined

方法 off

原型: off (eventName:string, handle:function=undefined, all:boolean=false)

取消监听事件

移除指定事件的监听器。可以移除特定处理函数，或移除所有监听器。

示例：

const handler = (data) => console.log(data)

// 添加监听
emitter.on('data', handler)

// 移除特定监听器
emitter.off('data', handler)

// 移除所有监听器
emitter.off('data')

// 移除所有匹配的监听器（all=true）
emitter.off('data', handler, true)

参数:

  • eventName

    类型string

    参数说明事件名称

  • handle

    类型function

    默认值undefined

    参数说明要移除的处理函数，不传则移除所有

  • all

    类型boolean

    默认值false

    参数说明如果为 true，移除所有匹配的处理函数

返回值:

类型undefined

方法 emit

原型: emit (eventName:string, ...args:any)

触发事件

触发指定事件，调用所有已注册的监听器。可以传递任意数量的参数给监听器。 使用 * 可以触发通配符监听器。

示例：

// 触发事件并传递参数
emitter.emit('data', 'hello', 123)

// 通配符监听器会收到事件名作为第一个参数
emitter.on('*', (eventName, ...args) => {
  console.log('事件:', eventName, '参数:', args)
})
emitter.emit('data', 'hello')  // 通配符监听器收到: 'data', 'hello'

参数:

  • eventName

    类型string

    参数说明事件名称

  • ...args

    类型any

    参数说明传递给监听器的参数

返回值:

类型undefined

方法 originHandle

原型: originHandle (handle:function)

获取原始处理函数

内部方法，用于获取被包装的处理函数的原始函数。 主要用于 once() 等内部包装场景。

参数:

  • handle

    类型function

    参数说明处理函数

返回值:

类型function

说明原始处理函数

方法 isListening

原型: isListening (event:string, handle:function)

检查是否正在监听事件

检查指定事件是否有特定的处理函数在监听。

示例：

const handler = () => {}
emitter.on('data', handler)

console.log(emitter.isListening('data', handler))  // true
console.log(emitter.isListening('data', () => {})) // false

参数:

  • event

    类型string

    参数说明事件名称

  • handle

    类型function

    参数说明处理函数

返回值:

类型boolean

说明是否正在监听

方法 destroy

原型: destroy ()

销毁 EventEmitter

清理所有事件监听器，释放资源。 销毁后，EventEmitter 实例不再可用。

返回值:

类型undefined