快速开始

本章介绍如何安装并使用 @ai-zen/event-bus。

安装

npm install @ai-zen/event-bus
# 或
pnpm add @ai-zen/event-bus

引入

import EventBus, { eventBus } from "@ai-zen/event-bus";

• EventBus：默认导出，为可实例化的类。
• eventBus：具名导出，为全局单例，可在多处共享。

创建实例

const bus = new EventBus();

若不想维护多个实例，可直接使用全局单例：

import { eventBus } from "@ai-zen/event-bus";
eventBus.on("event", handler);

订阅与触发

const bus = new EventBus();

bus.on("greet", (name: string) => {
  console.log(`Hello, ${name}!`);
});

bus.emit("greet", "AI-Zen"); // Hello, AI-Zen!

emit 会将后续参数原样传给所有已订阅的 handler。

退订

使用 off

const handler = () => console.log("hi");
bus.on("greet", handler);

bus.off("greet", handler); // 退订该 handler

使用 Disposable

on / once 返回一个 Disposable，可用 dispose() 退订：

const disposable = bus.on("greet", handler);
disposable.dispose(); // 等价于 bus.off("greet", handler)

清除事件或全局

bus.offAll("greet"); // 清除 "greet" 的所有 handler
bus.destroy();       // 清除全部订阅

一次性订阅：once

once 订阅后，事件第一次触发即自动退订：

bus.once("greet", (name) => {
  console.log(`Hello once, ${name}!`);
});

bus.emit("greet", "A"); // Hello once, A!
bus.emit("greet", "B"); // 不再触发

Promise 化：promise

promise 返回一个在事件触发时会 resolve 的 Promise：

const result = await bus.promise("reply");
bus.emit("reply", "done");
// result === "done"

收集结果：gather / gatherMap

gather 返回所有 handler 的返回结果数组，gatherMap 返回以 handler 为键的结果 Map：

bus.on("calc", () => 1);
bus.on("calc", () => 2);

const results = bus.gather<number>("calc");       // [1, 2]
const resultsMap = bus.gatherMap<number>("calc"); // Map(handler -> result)

错误处理：error

为事件注册错误处理器，再通过 error 派发错误：

bus.on("load", () => {
  // 正常处理
}, (reason) => {
  console.error("load failed:", reason);
});

bus.error("load", new Error("boom")); // 触发该事件的错误处理器

亦可结合 promise 使用：

bus.promise("load").catch((reason) => {
  console.error("load failed:", reason);
});
bus.error("load", new Error("boom"));

参考

• EventBus 事件管理库 —— 概述与核心特性。
• API 参考 —— 完整方法说明。