docs: 添加 Axis Innovators Box 框架完整 API 文档
- 新增浏览器模块技术文档,涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档,包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
This commit is contained in:
101
api-documentation/events/GlobalEventBus.md
Normal file
101
api-documentation/events/GlobalEventBus.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# GlobalEventBus 类技术文档
|
||||
|
||||
**包路径:** `com.axis.innovators.box.events.GlobalEventBus`
|
||||
**主要功能:** 全局单例事件总线访问点
|
||||
**作者:** tzdwindows 7
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
`GlobalEventBus` 是 **Axis Innovators Box** 框架中 `EventBus` 机制的静态包装类。它的核心作用是提供一个**全局唯一的、线程安全**的事件分发中心。
|
||||
|
||||
在一个复杂的解耦系统中,虽然可以实例化多个 `EventBus`(用于局部通信),但通常需要一个贯穿整个应用程序生命周期的主总线。`GlobalEventBus` 通过预定义的静态实例,消除了在不同模块、控制器或类之间传递 `EventBus` 引用的复杂性,实现了真正的“随处注册,随处发布”。
|
||||
|
||||
## 2. 核心架构设计
|
||||
|
||||
### 2.1 单例模式 (Singleton)
|
||||
该类采用了最简洁的静态常量初始化方式:
|
||||
```java
|
||||
public static final EventBus EVENT_BUS = new EventBus();
|
||||
```
|
||||
* **线程安全性**: 依赖于 Java 类加载机制,保证了 `EVENT_BUS` 实例在全局范围内的唯一性且只会被初始化一次。
|
||||
* **可见性**: `public` 修饰符允许框架内任何位置的代码直接访问,无需通过复杂的依赖注入(DI)容器。
|
||||
|
||||
### 2.2 职责定位
|
||||
`GlobalEventBus` 本身不包含复杂的逻辑,它更像是一个“门户”:
|
||||
1. **持有者**: 持有 `EventBus` 的核心实例。
|
||||
2. **默认中心**: 作为系统默认的、最高层级的通信渠道。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键特性
|
||||
|
||||
* **零配置访问**: 开发者无需关心 `EventBus` 的初始化时机,直接通过 `GlobalEventBus.EVENT_BUS` 即可获取能力。
|
||||
* **一致性**: 确保了核心系统事件(如应用启动、配置变更、全局错误处理)都在同一个频道内流动。
|
||||
* **低耦合**: 模块 A 只需要知道 `GlobalEventBus` 和事件类,而无需知道模块 B 的存在,即可实现与模块 B 的交互。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 使用指南
|
||||
|
||||
由于 `GlobalEventBus` 是对 `EventBus` 的静态引用,其主要操作均通过 `EVENT_BUS` 成员完成。
|
||||
|
||||
| 操作类型 | 代码示例 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| **注册监听** | `GlobalEventBus.EVENT_BUS.register(this);` | 在组件初始化(如 `onInit`)时调用。 |
|
||||
| **发送事件** | `GlobalEventBus.EVENT_BUS.post(new ConfigChangedEvent());` | 在任何业务逻辑发生点触发。 |
|
||||
| **取消注册** | `GlobalEventBus.EVENT_BUS.unregister(this);` | 在组件销毁(如 `onDestroy`)时调用,防止内存泄漏。 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 最佳实践
|
||||
|
||||
### 5.1 何时使用 GlobalEventBus?
|
||||
* **全局生命周期事件**: 如用户登录/登出、系统配置刷新。
|
||||
* **跨层级通信**: 例如底层的网络模块需要通知最顶层的 UI 界面显示通知。
|
||||
* **临时任务**: 不需要长期维护引用关系的瞬时事件处理。
|
||||
|
||||
### 5.2 注意事项
|
||||
1. **内存管理**: 凡是使用 `GlobalEventBus.EVENT_BUS.register()` 的对象,必须在生命周期结束时手动调用 `unregister()`,否则该对象将因为被全局静态引用持有而无法被 JVM 回收。
|
||||
2. **性能考量**: 虽然单次分发效率很高,但若全局总线上挂载了数千个监听器,频繁发布高频事件(如鼠标移动)可能会产生性能抖动。
|
||||
|
||||
---
|
||||
|
||||
## 6. 使用代码示例
|
||||
|
||||
### 场景:全局错误处理系统
|
||||
```java
|
||||
// 1. 定义全局异常事件
|
||||
public class GlobalErrorEvent {
|
||||
public final String message;
|
||||
public GlobalErrorEvent(String msg) { this.message = msg; }
|
||||
}
|
||||
|
||||
// 2. 在 UI 层注册监听
|
||||
public class MainNotificationUI {
|
||||
public MainNotificationUI() {
|
||||
GlobalEventBus.EVENT_BUS.register(this);
|
||||
}
|
||||
|
||||
@SubscribeEvent
|
||||
public void onErrorMessage(GlobalErrorEvent event) {
|
||||
showToast("系统错误: " + event.message);
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 在底层业务逻辑处发布
|
||||
public class DatabaseWorker {
|
||||
public void doWork() {
|
||||
try {
|
||||
// 某些业务操作...
|
||||
} catch (Exception e) {
|
||||
// 发现错误,直接向全局总线抛出,无需持有 UI 的引用
|
||||
GlobalEventBus.EVENT_BUS.post(new GlobalErrorEvent(e.getMessage()));
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
*文档生成时间: 2026-01-02*
|
||||
Reference in New Issue
Block a user