@composy/event-vue

@composy/event-vue

App 隔离与生命周期约定

默认 createEventVuePlugin() 不在工厂阶段创建共享 Bus；每次 app.use() 都会创建独立的 App-owned EventBus 和 EventChannelManager。App 卸载时会恢复原有 $eventBus，并销毁这两个 App-owned 资源。

需要跨 App 共享时必须显式传入 externalBus（bus 仍作为兼容别名），此时插件只解除注入，不会在 App 卸载时销毁外部 Bus。也可以传入 channelManager 明确借用 channel 管理器。

useEventBus() 和 useEventChannel() 默认要求当前 App 已安装插件并完成注入；它们不会创建模块级 singleton。SSR、测试或无插件场景请显式使用 useLocalEventBus()、useLocalEventChannel()，或传入具体的 Bus/Manager。所有 composable 订阅均绑定当前 effect scope，并在 scope 销毁时清理。

所有订阅 composable 都可额外传入 { signal }：AbortController.abort() 只取消当前订阅，不会销毁注入的 App-owned 或 external EventBus。组件 scope 清理与 signal 取消相互幂等，因此可同时使用“请求级取消”和“组件级兜底”两层生命周期。

@composy/event-vue 是 @composy/event-core 的 Vue 3 适配层，提供 composables、注入 key，以及同时兼容两种插件安装方式的桥接插件。

安装

pnpm add @composy/event-vue @composy/event-core vue

导出面

• 根入口：@composy/event-vue
• composables：@composy/event-vue/composables
• plugins：@composy/event-vue/plugins
• keys：@composy/event-vue/keys

原生 Vue Plugin 用法

import { createEventVuePlugin } from '@composy/event-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createEventVuePlugin({
    maxHistory: 100,
    globalPropertyName: '$eventBus',
  })
)

app.mount('#app')

@composy/engine-core Plugin 用法

import { createVueEngine } from '@composy/engine-vue'
import { createEventEngineVuePlugin } from '@composy/event-vue'

const engine = createVueEngine({
  plugins: [createEventEngineVuePlugin()],
})

await engine.start?.()

createEventEngineVuePlugin() 有两个目标：

• 作为 engine plugin 安装时，复用 @composy/event-core 的引擎状态总线，并在 app 可用后自动注入 Vue。
• 作为 Vue plugin 直接 app.use() 时，如果当前 app 已经挂有 $engine，会优先复用引擎里的同一份 EventBus。

Composables

import {
  useEventBus,
  useEventChannel,
  useEventFilter,
  useEventHistory,
  useEventNamespace,
  useEventScheduler,
} from '@composy/event-vue'

interface DemoEvents {
  'panel:open': { id: string }
}

const { prependListener, emit } = useEventBus<DemoEvents>()
const namespace = useEventNamespace<DemoEvents>('admin')
const channel = useEventChannel<DemoEvents>('panel')
const filter = useEventFilter<DemoEvents>()
const history = useEventHistory('panel:open')
const scheduler = useEventScheduler()

filter.addRule('panel:*', (_event, payload) => Boolean(payload))
namespace.on('panel:open', payload => channel.emit('panel:open', payload))
scheduler.register('panel:open', { mode: 'debounce', wait: 120, maxWait: 1000 })
prependListener('panel:open', payload => console.log('before other listeners', payload.id))
await emit('panel:open', { id: 'overview' })
history.refresh()

const controller = new AbortController()
const { on } = useEventBus<DemoEvents>()
on('panel:open', payload => console.log(payload.id), { signal: controller.signal })
controller.abort()

• useEventBus()：直接操作当前注入的 EventBus，支持 on、prependListener、once、off、emit 和 observe；订阅可传 EventSubscriptionOptions，使用具体事件映射时，通配符监听器的 payload 会自动按 */** 层级收窄
• useEventNamespace(name)：生成模块级命名空间
• useEventChannel(name)：生成独立频道；bridge() 会按源/目标事件推导 filter 和 transform 的载荷类型
• useEventFilter()：组合规则过滤发送，支持 removeRules() 与 removeAllRules() 清理规则
• useEventScheduler()：注册调度策略，并可通过 cancel(event) 取消当前待执行调度而保留策略
• useEventHistory()：响应式读取历史记录，默认通过 observe() 增量刷新

目录结构

src/
  composables/
  keys/
    eventBusKey.ts
  plugins/
    vuePlugin.ts
    engineVuePlugin.ts
    shared/
      installEventBus.ts
      resolveEngineContext.ts

plugins/shared/* 负责共享安装逻辑和 engine 上下文解析，避免 Vue 插件和 engine 插件各自复制接线代码。

构建与验证

本包只使用 ldesign-builder 的内置 rolldown 打包器。pnpm run build 会生成并检查完整的 dist/（UMD + minified）、es/（ESM + 类型）、esm/（ESM + 类型）和 lib/（CJS + 类型）目录。Builder、ESLint 与 TypeScript 的权威配置位于本包 .ldesign/；根目录同名配置保留为兼容入口。

pnpm --filter @composy/event-vue run type-check
pnpm --filter @composy/event-vue run test:run
pnpm --filter @composy/event-vue run build
pnpm --filter @composy/event-vue run outputs:check