# 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*