tzdwindows 7
7badbb0d8e
- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
# RegistrationTopic 类技术文档
|
||
|
||
**包路径:** `com.axis.innovators.box.register.RegistrationTopic`
|
||
**主要功能:** 主题/外观 (LookAndFeel) 注册中心、视觉模式管理
|
||
**作者:** tzdwindows 7
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
`RegistrationTopic` 是 **Axis Innovators Box** 框架中负责视觉外观管理的核心组件。它充当了一个“主题仓库”，统一管理应用程序支持的所有 `LookAndFeel`（外观）。通过该类，开发者可以注册系统原生主题、第三方现代主题（如 FlatLaf、Material UI）以及自定义的视觉样式。
|
||
|
||
该类不仅存储主题的实现，还记录了主题的元数据（名称、图标、描述）以及色彩属性（明/暗模式），为设置中心的 UI 渲染和全局主题切换提供了数据支持。
|
||
|
||
## 2. 核心职责
|
||
|
||
* **多模式注册:** 支持通过“类全限定名（String）”或“主题实例（LookAndFeel）”两种方式注册主题。
|
||
* **状态追踪:** 记录当前正在加载的主题，并提供实时状态查询。
|
||
* **明/暗模式识别:** 维护每个主题的色彩属性，允许框架根据当前主题自动调整其他组件（如代码编辑器、图标）的色调。
|
||
* **生命周期保护:** 严格限制注册时机，确保 UI 稳定性。
|
||
|
||
## 3. 核心机制详解
|
||
|
||
### 3.1 双路注册支持
|
||
为了兼容不同的 UI 库，`RegistrationTopic` 提供了重载的 `addTopic` 方法：
|
||
1. **基于类名注册:** 适用于 JVM 默认提供的或在类路径下的标准主题（如 `UIManager.getSystemLookAndFeelClassName()`）。
|
||
2. **基于实例注册:** 适用于需要初始化参数的现代主题（如 `new FlatMacDarkLaf()`），这允许主题在注册前进行预配置。
|
||
|
||
### 3.2 同步列表结构
|
||
该类内部使用多个对齐的 `ArrayList` 来维护数据。每个主题在所有列表中的索引（Index）是统一的。例如，索引为 `5` 的项，其类名、图标、描述和暗黑模式标志位都存储在各自列表的第 `5` 位。
|
||
|
||
### 3.3 明/暗模式感知 (`isDarkMode`)
|
||
该方法通过查找当前活跃主题（`loadTopics`）在注册列表中的位置，返回其对应的 `isDarkMode` 布尔值。这对于实现“跟随主题自动切换图标颜色”等高级 UI 特性至关重要。
|
||
|
||
---
|
||
|
||
## 4. API 接口说明
|
||
|
||
### 4.1 注册方法
|
||
|
||
| 方法签名 | 描述 |
|
||
| :--- | :--- |
|
||
| `addTopic(String class, String name, String tip, Icon icon, String regName, boolean isDark)` | 通过主题类名注册。 |
|
||
| `addTopic(LookAndFeel laf, String name, String tip, Icon icon, String regName, boolean isDark)` | 通过 LookAndFeel 实例注册。 |
|
||
|
||
### 4.2 状态管理与查询
|
||
|
||
| 方法 | 描述 |
|
||
| :--- | :--- |
|
||
| `void setLoading(String regName)` | 设置当前激活的主题 ID（注册名）。 |
|
||
| `boolean isLoading(String regName)` | 检查指定的主题是否是当前正在使用的主题。 |
|
||
| `boolean isDarkMode()` | 获取当前激活的主题是否属于暗黑模式。 |
|
||
| `boolean isEmpty()` | 检查仓库中是否尚未注册任何主题。 |
|
||
|
||
---
|
||
|
||
## 5. 关键约束：注册时机
|
||
|
||
与 `RegistrationTool` 类似，`RegistrationTopic` 具有严格的**时机约束**：
|
||
|
||
* **限制:** 所有的主题注册必须在 `AxisInnovatorsBox.isWindow()` 为 `false` 时进行（即主窗口启动前）。
|
||
* **违规处理:** 如果在窗口显示后尝试调用 `addTopic`，系统会记录警告日志：`logger.warn("Wrong time to add topics")`，且该注册请求会被忽略。
|
||
* **设计目的:** 保证 Swing 的 `UIManager` 状态在初始化阶段是确定的，防止运行时切换导致的界面渲染异常或部分组件更新失败。
|
||
|
||
## 6. 错误处理
|
||
|
||
如果在注册过程中出现**重复的注册名称**（`registeredName`），该类会抛出 `RegistrationError`。这确保了每个主题在设置界面和配置文件中都有唯一的引用 ID。
|
||
|
||
## 7. 使用示例
|
||
|
||
在 `AxisInnovatorsBox` 初始化阶段注册主题：
|
||
|
||
```java
|
||
RegistrationTopic topicRegistry = main.getRegistrationTopic();
|
||
|
||
// 1. 注册系统默认主题
|
||
topicRegistry.addTopic(
|
||
UIManager.getSystemLookAndFeelClassName(),
|
||
"系统默认",
|
||
"使用操作系统的原生外观",
|
||
null,
|
||
"system:native",
|
||
false
|
||
);
|
||
|
||
// 2. 注册 FlatLaf 现代暗黑主题
|
||
topicRegistry.addTopic(
|
||
new com.formdev.flatlaf.themes.FlatMacDarkLaf(),
|
||
"MacOS Dark",
|
||
"现代化的深色苹果风格界面",
|
||
new ImageIcon("mac_dark_icon.png"),
|
||
"system:flatMacDark",
|
||
true
|
||
);
|
||
```
|
||
|
||
---
|
||
*文档生成时间: 2026-01-02* |