@fyh-mengxiang/vue3-event-bus 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+# vue3-event-bus
+
+一个简单轻量的Vue 3事件总线库，支持Composition API和Option API。
+
+## 特性
+
+- ✅ 支持Vue 3的Composition API和Option API
+- ✅ 提供单例模式，全局共享
+- ✅ 支持事件订阅、发布、取消订阅
+- ✅ 支持一次性事件
+- ✅ 提供事件管理功能
+- ✅ 轻量无依赖
+- ✅ 兼容TypeScript
+
+## 安装
+
+### NPM安装
+
+```bash
+npm install vue3-event-bus
+```
+
+### 本地开发安装
+
+```bash
+# 在项目根目录执行
+npm install ./vue3-event-bus
+```
+
+## 使用
+
+### 1. 全局注册（推荐）
+
+在`main.js`中使用`Vue.use()`注册：
+
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+import EventBus from 'vue3-event-bus'
+
+const app = createApp(App)
+app.use(EventBus, { debug: true }) // debug选项可选
+app.mount('#app')
+```
+
+### 2. 在组件中使用
+
+#### Option API
+
+```vue
+<template>
+  <div>
+    <button @click="sendEvent">发送事件</button>
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    sendEvent() {
+      // 发送事件
+      this.$eventBus.emit('test-event', 'Hello EventBus')
+    },
+  },
+  mounted() {
+    // 订阅事件
+    this.$eventBus.on('test-event', this.handleEvent)
+  },
+  beforeUnmount() {
+    // 取消订阅
+    this.$eventBus.off('test-event', this.handleEvent)
+  },
+}
+</script>
+```
+
+#### Composition API
+
+```vue
+<template>
+  <div>
+    <button @click="sendEvent">发送事件</button>
+  </div>
+</template>
+
+<script setup>
+import { inject, onMounted, onUnmounted } from 'vue'
+
+// 通过inject获取eventBus实例
+const eventBus = inject('eventBus')
+
+// 事件处理函数
+const handleEvent = (data) => {
+  console.log('收到事件:', data)
+}
+
+// 发送事件
+const sendEvent = () => {
+  eventBus.emit('test-event', 'Hello EventBus')
+}
+
+onMounted(() => {
+  // 订阅事件
+  eventBus.on('test-event', handleEvent)
+})
+
+onUnmounted(() => {
+  // 取消订阅
+  eventBus.off('test-event', handleEvent)
+})
+</script>
+```
+
+### 3. 直接使用单例实例
+
+```javascript
+import { eventBus } from 'vue3-event-bus'
+
+eventBus.on('test-event', (data) => {
+  console.log('收到事件:', data)
+})
+
+eventBus.emit('test-event', 'Hello EventBus')
+```
+
+## API
+
+### `on(eventName, callback, options?)`
+
+订阅事件
+
+- `eventName`: 事件名称（字符串）
+- `callback`: 回调函数
+- `options`: 可选配置
+  - `once`: 是否只触发一次（布尔值，默认为false）
+- 返回值: 取消订阅的函数
+
+### `once(eventName, callback)`
+
+订阅一次事件，触发后自动取消订阅
+
+- `eventName`: 事件名称（字符串）
+- `callback`: 回调函数
+- 返回值: 取消订阅的函数
+
+### `off(eventName, callback?)`
+
+取消订阅事件
+
+- `eventName`: 事件名称（字符串）
+- `callback`: 可选，指定要取消的回调函数。如果不提供，则取消该事件的所有订阅
+
+### `emit(eventName, ...args)`
+
+发布/触发事件
+
+- `eventName`: 事件名称（字符串）
+- `...args`: 传递给回调函数的参数
+
+### `listenerCount(eventName)`
+
+获取指定事件的订阅者数量
+
+- `eventName`: 事件名称（字符串）
+- 返回值: 订阅者数量（数字）
+
+### `getEvents()`
+
+获取所有订阅的事件名称
+
+- 返回值: 事件名称数组
+
+### `clear()`
+
+清除所有事件订阅
+
+## 示例
+
+### 基本使用
+
+```javascript
+// 订阅事件
+const unsubscribe = eventBus.on('test-event', (data) => {
+  console.log('收到数据:', data)
+})
+
+// 发送事件
+eventBus.emit('test-event', { message: 'Hello' })
+
+// 取消订阅
+unsubscribe() // 或 eventBus.off('test-event')
+```
+
+### 一次性事件
+
+```javascript
+eventBus.once('once-event', (data) => {
+  console.log('这个事件只会触发一次:', data)
+})
+
+eventBus.emit('once-event', '第一次触发') // 会执行
+
+eventBus.emit('once-event', '第二次触发') // 不会执行
+```
+
+### 事件管理
+
+```javascript
+// 获取事件数量
+const count = eventBus.listenerCount('test-event')
+console.log('订阅者数量:', count)
+
+// 获取所有事件名称
+const events = eventBus.getEvents()
+console.log('所有事件:', events)
+
+// 清除所有订阅
+eventBus.clear()
+```
+
+## 注意事项
+
+1. **组件卸载时取消订阅**：为避免内存泄漏，组件卸载前应取消订阅相关事件
+2. **事件名称规范**：建议使用命名空间（如`user:login`）避免事件名称冲突
+3. **回调函数作用域**：注意回调函数中的`this`指向
+4. **不要滥用EventBus**：对于复杂的状态管理，建议使用Vuex或Pinia
+
+## 浏览器支持
+
+- Chrome (最新)
+- Firefox (最新)
+- Safari (最新)
+- Edge (最新)
+
+解决Bug
+一.如何解决页面执行时先emit后on导致事件监听失效的问题
+
+## 1. 核心改进
+
+- 添加了事件缓存机制 ：当事件发布时如果没有订阅者，事件会被缓存起来
+- 订阅时自动触发缓存事件 ：当组件订阅事件时，会自动触发所有缓存的该事件
+- 配置化设计 ：支持通过选项控制缓存行为，如是否启用缓存、最大缓存数量等
+- 完整的缓存管理 ：提供了清除缓存、查看缓存数量等API
+  // main.js中配置
+  app.use(EventBus, {
+  debug: true, // debug模式
+  eventBusOptions: {
+  enableCache: true, // 启用事件缓存
+  maxCacheSize: 10, // 每个事件最大缓存10条,默认缓存10条
+  clearCacheAfterSubscribe: true // 订阅后自动清除缓存
+  }
+  })

package/index.js

@@ -0,0 +1,43 @@
+/**
+ * Vue 3 EventBus 主入口文件
+ * 支持 Vue.use() 安装方式
+ */
+
+import EventBus from './src/EventBus.js'
+
+// 创建单例实例，支持通过 install 方法传递选项
+let eventBusInstance = new EventBus()
+
+/**
+ * Vue 3 插件安装函数
+ * @param {import('vue').App} app - Vue 应用实例
+ * @param {Object} options - 插件选项
+ */
+function install(app, options = {}) {
+  // 如果提供了 EventBus 配置，重新创建实例
+  if (options.eventBusOptions) {
+    eventBusInstance = new EventBus(options.eventBusOptions)
+  }
+
+  // 全局注入 eventBus，支持 Composition API
+  app.provide('eventBus', eventBusInstance)
+
+  // 添加到全局属性，支持 Option API
+  app.config.globalProperties.$eventBus = eventBusInstance
+
+  // 可选：在控制台输出安装信息
+  if (options.debug) {
+    console.log('Vue 3 EventBus 已安装', { options })
+  }
+}
+
+// 导出插件
+export default {
+  install,
+}
+
+// 导出单例实例，支持直接使用
+export const eventBus = eventBusInstance
+
+// 导出类，支持自定义实例
+export { EventBus }

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@fyh-mengxiang/vue3-event-bus",
+  "version": "1.0.0",
+  "description": "A simple and lightweight EventBus for Vue 3, supporting both Composition API and Option API",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "echo \"Build completed\"",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "vue3",
+    "eventbus",
+    "vue-event-bus",
+    "vue3-event-bus",
+    "event-emitter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "devDependencies": {
+    "vue": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fyh-mengxiang/vue3-plugins.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fyh-mengxiang/vue3-plugins/issues"
+  },
+  "homepage": "https://github.com/fyh-mengxiang/vue3-plugins#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/EventBus.js

@@ -0,0 +1,242 @@
+/**
+ * Vue 3 EventBus 核心实现
+ * 支持事件订阅、发布、取消订阅等功能
+ * 支持事件缓存，解决先执行顺序先emit后on的问题
+ */
+
+class EventBus {
+  constructor(options = {}) {
+    // 存储事件订阅者
+    this.events = {}
+    // 存储已发布但未被订阅的事件（事件缓存）
+    this.eventCache = {}
+    // 配置选项
+    this.options = {
+      // 是否启用事件缓存
+      enableCache: options.enableCache !== false,
+      // 每个事件的最大缓存数量，0表示不限制
+      maxCacheSize: options.maxCacheSize || 10,
+      // 是否在订阅后自动清除缓存
+      clearCacheAfterSubscribe: options.clearCacheAfterSubscribe !== false,
+      ...options,
+    }
+  }
+
+  /**
+   * 订阅事件
+   * @param {string} eventName - 事件名称
+   * @param {Function} callback - 回调函数
+   * @param {Object} options - 选项配置
+   * @param {boolean} options.once - 是否只触发一次
+   * @returns {Function} - 取消订阅的函数
+   */
+  on(eventName, callback, options = {}) {
+    if (typeof callback !== 'function') {
+      throw new TypeError('回调函数必须是函数类型')
+    }
+
+    if (!this.events[eventName]) {
+      this.events[eventName] = []
+    }
+
+    // 创建订阅者对象
+    const subscriber = {
+      callback,
+      once: !!options.once,
+    }
+
+    this.events[eventName].push(subscriber)
+
+    // 检查是否有缓存的事件，如果有则触发
+    if (this.options.enableCache && this.eventCache[eventName]) {
+      // 复制缓存列表，防止在处理过程中修改
+      const cachedEvents = [...this.eventCache[eventName]]
+
+      // 触发所有缓存的事件
+      cachedEvents.forEach((cached) => {
+        try {
+          callback(...cached.args)
+        } catch (error) {
+          console.error(`EventBus 缓存事件 "${eventName}" 回调执行出错:`, error)
+        }
+
+        // 如果是一次性事件，触发后移除订阅
+        if (subscriber.once) {
+          this.off(eventName, callback)
+        }
+      })
+
+      // 根据配置清除缓存
+      if (this.options.clearCacheAfterSubscribe) {
+        delete this.eventCache[eventName]
+      }
+    }
+
+    // 返回取消订阅的函数，方便在组件中使用
+    return () => this.off(eventName, callback)
+  }
+
+  /**
+   * 订阅一次事件
+   * @param {string} eventName - 事件名称
+   * @param {Function} callback - 回调函数
+   * @returns {Function} - 取消订阅的函数
+   */
+  once(eventName, callback) {
+    return this.on(eventName, callback, { once: true })
+  }
+
+  /**
+   * 取消订阅事件
+   * @param {string} eventName - 事件名称
+   * @param {Function} [callback] - 可选的回调函数，不提供则取消该事件的所有订阅
+   */
+  off(eventName, callback) {
+    if (!this.events[eventName]) {
+      return
+    }
+
+    if (!callback) {
+      // 取消该事件的所有订阅
+      delete this.events[eventName]
+      return
+    }
+
+    // 取消指定的订阅
+    this.events[eventName] = this.events[eventName].filter(
+      (listener) => listener.callback !== callback,
+    )
+
+    // 如果没有订阅者了，清理该事件
+    if (this.events[eventName].length === 0) {
+      delete this.events[eventName]
+    }
+  }
+
+  /**
+   * 发布/触发事件
+   * @param {string} eventName - 事件名称
+   * @param {...any} args - 传递给回调函数的参数
+   */
+  emit(eventName, ...args) {
+    let hasListeners = false
+
+    // 如果有订阅者，直接触发
+    if (this.events[eventName]) {
+      hasListeners = true
+      // 复制一份订阅者列表，防止在触发过程中修改订阅列表
+      const listeners = [...this.events[eventName]]
+
+      listeners.forEach((listener) => {
+        try {
+          listener.callback(...args)
+        } catch (error) {
+          console.error(`EventBus 事件 "${eventName}" 回调执行出错:`, error)
+        }
+
+        // 如果是一次性事件，触发后自动取消订阅
+        if (listener.once) {
+          this.off(eventName, listener.callback)
+        }
+      })
+    }
+
+    // 如果没有订阅者且启用了事件缓存，将事件缓存起来
+    if (!hasListeners && this.options.enableCache) {
+      // 初始化缓存数组
+      if (!this.eventCache[eventName]) {
+        this.eventCache[eventName] = []
+      }
+
+      // 添加到缓存
+      this.eventCache[eventName].push({
+        args: [...args],
+        timestamp: Date.now(),
+      })
+
+      // 限制缓存数量
+      if (this.options.maxCacheSize > 0) {
+        const overflow = this.eventCache[eventName].length - this.options.maxCacheSize
+        if (overflow > 0) {
+          // 移除最早的缓存
+          this.eventCache[eventName].splice(0, overflow)
+        }
+      }
+    }
+  }
+
+  /**
+   * 获取指定事件的订阅者数量
+   * @param {string} eventName - 事件名称
+   * @returns {number} - 订阅者数量
+   */
+  listenerCount(eventName) {
+    return this.events[eventName] ? this.events[eventName].length : 0
+  }
+
+  /**
+   * 获取指定事件的缓存数量
+   * @param {string} eventName - 事件名称
+   * @returns {number} - 缓存事件数量
+   */
+  cacheCount(eventName) {
+    return this.eventCache[eventName] ? this.eventCache[eventName].length : 0
+  }
+
+  /**
+   * 清除所有事件订阅
+   * @param {boolean} clearCache - 是否同时清除事件缓存
+   */
+  clear(clearCache = true) {
+    this.events = {}
+    if (clearCache) {
+      this.clearCache()
+    }
+  }
+
+  /**
+   * 清除事件缓存
+   * @param {string} [eventName] - 可选，指定要清除的事件缓存，不提供则清除所有
+   */
+  clearCache(eventName) {
+    if (eventName) {
+      delete this.eventCache[eventName]
+    } else {
+      this.eventCache = {}
+    }
+  }
+
+  /**
+   * 获取所有订阅的事件名称
+   * @returns {string[]} - 事件名称数组
+   */
+  getEvents() {
+    return Object.keys(this.events)
+  }
+
+  /**
+   * 获取所有缓存的事件名称
+   * @returns {string[]} - 事件名称数组
+   */
+  getCachedEvents() {
+    return Object.keys(this.eventCache)
+  }
+
+  /**
+   * 获取事件缓存配置
+   * @returns {Object} - 配置选项
+   */
+  getOptions() {
+    return { ...this.options }
+  }
+
+  /**
+   * 更新事件缓存配置
+   * @param {Object} newOptions - 新的配置选项
+   */
+  updateOptions(newOptions) {
+    this.options = { ...this.options, ...newOptions }
+  }
+}
+
+export default EventBus