smart-event-bus

一个轻量级、支持高级功能的事件总线库，适用于 Vue 3 项目。内置自动解绑、节流、防抖、订阅次数限制、调试模式等功能，适合非父子组件通信、全局事件广播等场景。

安装

pnpm install smart-event-bus

使用示例

基础事件订阅 / 发送

import { useEventBus, emitEvent } from 'smart-event-bus'

useEventBus('hello', (msg) => {
  console.log('收到消息:', msg)
})

emitEvent('hello', '你好，Vue3')

自动解绑（结合 Vue 生命周期）

<script setup>
useEventBus('logout', () => {
  console.log('组件销毁前自动解绑')
})
</script>

节流 & 防抖

// 防抖 500ms
useEventBus('input', (val) => {
  console.log('防抖输入:', val)
}, { debounce: 500 })

// 节流 1s
useEventBus('scroll', () => {
  console.log('节流触发滚动')
}, { throttle: 1000 })

限制订阅次数 & 调试模式

useEventBus('click', () => {
  console.log('只触发 3 次')
}, { maxCalls: 3, debug: true })

once 事件

onceEvent('init', () => {
  console.log('仅第一次触发')
})

命名空间事件总线(不支持自动解绑)

import { createNamespacedBus } from 'smart-event-bus'

const authBus = createNamespacedBus('auth')
authBus.on('login', (user) => console.log(user))
authBus.emit('login', { id: 1, name: 'Jack' })

事件缓冲：先触发，后订阅

emitEvent('ready', '数据准备好了') // 监听器未挂载
useEventBus('ready', (msg) => console.log(msg), { buffer: true })
// 控制台立即打印：数据准备好了

中间件处理机制

useEventBus('save', (data) => console.log('已保存:', data), {
  middleware: (payload) => {
    if (!payload.valid) return false // 阻止事件
    payload.savedAt = Date.now()
    return payload
  }
})

emitEvent('save', { valid: true })

API 文档

useEventBus(event, handler, options?)

在组件中注册监听函数，并在组件卸载时自动取消订阅。

| 参数 | 类型 | 说明 | | --------- | ------------------------ | --------------- | | event | string | 事件名称 | | handler | (payload: any) => void | 事件处理函数 | | options | EventBusOptions（可选） | 控制节流、防抖、限制次数等配置 |

emitEvent(event, payload)

触发指定事件，传递参数。

onceEvent(event, handler, options?)

只执行一次的事件订阅。

clearEvent(event?)

移除指定事件的所有监听器，或全部清空。

createNamespacedBus(namespace)

创建带命名空间的事件总线实例，防止事件冲突。

EventBusOptions 配置项

interface EventBusOptions {
  debounce?: number        // 防抖间隔时间（ms）
  throttle?: number        // 节流间隔时间（ms）
  maxCalls?: number        // 最多触发次数
  debug?: boolean          // 控制台调试信息输出
  buffer?: boolean         // 是否接收事件缓冲（先触发后监听）
  middleware?: (payload: any) => any | false  // 中间件拦截器，返回 false 阻止事件
}

项目优势

• ✅ Vue 3 生命周期绑定自动清理
• ✅ 支持防抖、节流控制频率
• ✅ 限制订阅次数，自动移除
• ✅ 一键开启调试模式，方便排查
• ✅ 事件缓冲机制（先触发后监听）
• ✅ 命名空间支持，避免事件污染
• ✅ 中间件机制，灵活控制事件行为
• ✅ 零依赖，适合通用模块