docs: 添加 Axis Innovators Box 框架完整 API 文档
- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
This commit is contained in:
782
README.md
782
README.md
@@ -1,662 +1,320 @@
|
||||
# AxisInnovatorsBoxWindowApi
|
||||
# AxisInnovatorsBox Window API
|
||||
|
||||
[项目链接](https://gitea.lingqi.vip/lanxi/window-axis-innovators-box) |
|
||||
[官网](https://box.nimblenexa.cn)
|
||||
| 简体中文
|
||||
[项目链接](https://gitea.lingqi.vip/lanxi/window-axis-innovators-box) | [官网](https://box.nimblenexa.cn) | 简体中文
|
||||
|
||||
---
|
||||
|
||||
## 项目概述
|
||||
## 📖 项目概述
|
||||
|
||||
`AxisInnovatorsBoxWindowApi` 是一个为 **AxisInnovatorsBox** 平台设计的管理API接口库，开发者可通过此API创建自定义插件，实现窗口管理、事件交互等核心功能。该仓库提供了接口定义、类说明文档及插件开发示例代码，帮助开发者快速接入AxisInnovatorsBox生态系统。
|
||||
`AxisInnovatorsBoxWindowApi` 是专为 **AxisInnovatorsBox** 平台打造的核心扩展 API 库。它赋予开发者创建自定义插件的能力，支持窗口深度管理、跨语言事件交互及 UI 定制。该仓库包含完整的接口定义、开发文档及示例代码，旨在帮助开发者无缝接入并扩展 AxisInnovatorsBox 生态系统。
|
||||
|
||||
## ✨ 功能特性
|
||||
|
||||
* 🖥️ **全生命周期窗口管理** - 精确控制窗口创建、销毁、最小化/最大化及模态状态。
|
||||
* 🎮 **事件驱动架构** - 基于发布/订阅模式的事件总线，支持系统级事件监听与自定义事件广播。
|
||||
* 📦 **多语言插件引擎** - 原生支持 Java 插件，并通过 Jython 实现 Python 插件的无缝加载与互操作。
|
||||
* 📄 **动态配置与国际化** - 支持通过 Properties 灵活管理配置，提供完整的 I18n 多语言支持。
|
||||
* 📊 **统一日志系统** - 集成 Java 日志框架，自动捕获并同步 Python 插件的运行日志与异常堆栈。
|
||||
|
||||
---
|
||||
|
||||
## 功能特性
|
||||
## 🧩 插件开发指南
|
||||
|
||||
- 🖥️ **窗口生命周期管理** - 创建/销毁窗口、调整窗口状态（最小化/最大化）
|
||||
- 🎮 **事件驱动交互** - 支持窗口事件监听与自定义事件触发
|
||||
- 📦 **跨语言插件支持** - 基于 Java 平台无缝加载 Python 插件，提供标准插件基类（Java/Python）实现快速扩展
|
||||
- 📄 **动态配置管理** - 通过 properties 配置文件灵活加载多语言插件（支持 Java/Python 插件声明）
|
||||
- 📊 **统一日志追踪** - 集成 Java 平台日志系统，同步记录 Python 插件的运行状态与异常信息
|
||||
插件加载系统是程序的核心组件，由主程序内部自动调度。
|
||||
|
||||
---
|
||||
### 1. Java 插件开发 (Jar)
|
||||
Jar 格式插件需放置在 `/plug-in` 目录下。
|
||||
|
||||
## 插件加载系统说明
|
||||
- 插件加载系统核心组件。
|
||||
- 插件加载系统由 **程序内部** 完成
|
||||
**核心注解 `@PluginMeta`**：
|
||||
用于描述插件的基本信息。系统会自动实例化被标记的类，并填充 `INSTANCE` 字段。
|
||||
|
||||
### 注册Jar插件
|
||||
- Jar插件在/plug-in中添加
|
||||
```java
|
||||
@PluginMeta(id = "test", name = "测试插件",
|
||||
supportedVersions = {"0.0.2"},
|
||||
description = "测试插件",
|
||||
icon = "",
|
||||
registeredName = "test")
|
||||
package com.example.plugin;
|
||||
|
||||
import com.axis.innovators.box.plugins.PluginDescriptor;
|
||||
import com.axis.innovators.box.plugins.PluginMeta;
|
||||
import com.axis.innovators.box.events.GlobalEventBus;
|
||||
import com.axis.innovators.box.events.StartupEvent;
|
||||
import com.axis.innovators.box.events.SubscribeEvent;
|
||||
import com.axis.innovators.box.window.MainWindow;
|
||||
|
||||
@PluginMeta(
|
||||
id = "test_plugin",
|
||||
name = "测试插件",
|
||||
version = "1.0.0",
|
||||
supportedVersions = {"0.0.2"},
|
||||
description = "这是一个Java插件示例",
|
||||
icon = "icon.png",
|
||||
registeredName = "test"
|
||||
)
|
||||
public class Template {
|
||||
// 系统加载时会自动注入此描述符
|
||||
public static PluginDescriptor INSTANCE = null;
|
||||
|
||||
public Template() {
|
||||
// 在构造函数中注册事件监听
|
||||
GlobalEventBus.EVENT_BUS.register(this);
|
||||
}
|
||||
|
||||
|
||||
|
||||
@SubscribeEvent
|
||||
public void onStartup(StartupEvent event) {
|
||||
MainWindow.ToolCategory category = new MainWindow.ToolCategory("测试插件", "test", "测试插件");
|
||||
// 在启动事件中注册工具栏分类
|
||||
MainWindow.ToolCategory category = new MainWindow.ToolCategory("测试分类", "test_icon", "分类描述");
|
||||
event.main().getRegistrationTool().addToolCategory(
|
||||
category,
|
||||
INSTANCE,
|
||||
"templatePlugin"
|
||||
"templatePlugin::category"
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
- 插件加载系统会自动填充 **INSTANCE** 内容
|
||||
- 使用PluginMeta注册插件信息
|
||||
|
||||
### Python插件注册
|
||||
- Python插件在/plug-in/python中添加
|
||||
- Python可以直接调用Java类实现对插件系统的控制
|
||||
- 插件还需要单独的放在一个子文件夹中，如/plug-in/python/Examples
|
||||
- Python插件需要声明一个metadata.json文件，如：
|
||||
### 2. Python 插件开发 (Script)
|
||||
Python 插件需放置在 `/plug-in/python` 的子目录中（例如 `/plug-in/python/Examples`）。Python 脚本可直接调用 Java 类库。
|
||||
|
||||
**必要文件结构**：
|
||||
* `metadata.json`: 插件元数据
|
||||
* `main.py`: 入口脚本
|
||||
|
||||
**metadata.json 示例**：
|
||||
```json
|
||||
{
|
||||
"id": "testing",
|
||||
"name": "测试",
|
||||
"id": "py_testing",
|
||||
"name": "Python测试插件",
|
||||
"version": "0.0.1",
|
||||
"description": "测试插件",
|
||||
"description": "Python脚本插件示例",
|
||||
"author": "tzdwindows 7",
|
||||
"dependencies": [],
|
||||
"_comment": {
|
||||
"warning": "本文件为插件元数据配置，修改后需重启应用生效",
|
||||
"path": "插件资源应放置在plugins/{id}/目录下"
|
||||
"path": "资源文件应放置在 plugins/{id}/ 目录下"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Python插件需要声明一个main.py文件做为插件的主脚本，如：
|
||||
|
||||
**main.py 示例**：
|
||||
```python
|
||||
"""
|
||||
工具模块初始化脚本
|
||||
功能：向Axis Innovators Box注册自定义工具类别和工具项
|
||||
作者：tzdwindows 7
|
||||
版本：1.1
|
||||
功能：注册自定义工具类别和工具项
|
||||
"""
|
||||
from com.axis.innovators.box.python import PyLocalSide
|
||||
from javax.swing import AbstractAction
|
||||
|
||||
class MyAction(AbstractAction):
|
||||
def actionPerformed(self, event):
|
||||
"""工具项点击事件处理"""
|
||||
print("[DEBUG] Tool item clicked! Event source:", event.getSource())
|
||||
print("[DEBUG] Python工具项被点击！事件源:", event.getSource())
|
||||
|
||||
def onStartup():
|
||||
"""
|
||||
系统启动时自动执行的初始化逻辑
|
||||
功能：
|
||||
1. 创建工具类别
|
||||
2. 创建工具项并绑定动作
|
||||
3. 注册到系统全局工具集
|
||||
"""
|
||||
print('[INFO] 正在初始化自定义工具...')
|
||||
"""系统启动钩子函数"""
|
||||
print('[INFO] 初始化Python插件...')
|
||||
|
||||
# --------------------------
|
||||
# 创建工具类别（参数顺序：显示名称，图标资源名，描述）
|
||||
# --------------------------
|
||||
# 1. 创建工具类别
|
||||
tool_category = PyLocalSide.getToolCategory(
|
||||
u"数据分析工具", # 显示名称（GUI可见）
|
||||
u"analytics_icon.png", # 图标文件名（需存在于资源目录）
|
||||
u"高级数据分析功能集合" # 悬停提示描述
|
||||
u"数据分析", # 名称
|
||||
u"analytics.png", # 图标
|
||||
u"Python数据分析工具" # 描述
|
||||
)
|
||||
|
||||
# --------------------------
|
||||
# 创建工具项（参数顺序：显示名称，图标，描述，ID，动作对象）
|
||||
# --------------------------
|
||||
# 2. 创建并添加工具项
|
||||
tool_action = MyAction()
|
||||
tool_item = PyLocalSide.getToolItem(
|
||||
u"数据可视化", # 工具项显示名称
|
||||
u"chart_icon.png", # 工具项图标
|
||||
u"生成交互式数据图表", # 工具项描述
|
||||
1001, # 工具项唯一ID（需在配置中统一管理）
|
||||
tool_action # 点击触发的动作
|
||||
u"生成图表",
|
||||
u"chart.png",
|
||||
u"点击生成报表",
|
||||
1001,
|
||||
tool_action
|
||||
)
|
||||
tool_category.addTool(tool_item)
|
||||
|
||||
# --------------------------
|
||||
# 注册工具类别到系统（参数：类别对象，全局唯一注册名称）
|
||||
# --------------------------
|
||||
# 3. 注册到系统
|
||||
PyLocalSide.addToolCategory(
|
||||
tool_category,
|
||||
u"custom_module::data_analysis_tools" # 推荐命名规则：模块名::功能名
|
||||
u"py_module::analysis"
|
||||
)
|
||||
print('[SUCCESS] 工具类别注册成功')
|
||||
print('[SUCCESS] Python插件加载完成')
|
||||
|
||||
# 将 onStartup 绑定到全局作用域，供 Java 端调用
|
||||
if __name__ == '__main__':
|
||||
result = 0
|
||||
errorResult = ""
|
||||
|
||||
# 确保Jython运行时可以访问onStartup函数
|
||||
# 原理：将函数显式绑定到全局字典
|
||||
globals()['onStartup'] = onStartup
|
||||
globals()['onStartup'] = onStartup
|
||||
```
|
||||
|
||||
### 声明CorePlugins
|
||||
* CorePlugins核心组件可以修改部分模块的字节码。
|
||||
* CorePlugins需要在jar的属性中添加 **CorePlugins: CorePlugins类位置**
|
||||
* 自动化构建，在build.gradle中添加如下代码：
|
||||
```groovy
|
||||
jar {
|
||||
manifest {
|
||||
attributes 'CorePlugin': 'com.axis.core.template.TemplateLoadingCorePlugin'
|
||||
### 3. CorePlugins (字节码增强)
|
||||
CorePlugins 允许在类加载阶段修改目标类的字节码（ASM）。
|
||||
|
||||
**配置步骤**：
|
||||
1. 在 `build.gradle` 中声明 Manifest 属性：
|
||||
```groovy
|
||||
jar {
|
||||
manifest {
|
||||
attributes 'CorePlugin': 'com.axis.core.template.TemplateLoadingCorePlugin'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
* CorePlugins核心组件需要实现 **CorePlugins** 接口，如：
|
||||
```java
|
||||
package com.axis.core.template;
|
||||
```
|
||||
2. 实现 `LoadingCorePlugin` 接口：
|
||||
```java
|
||||
public class TemplateLoadingCorePlugin implements LoadingCorePlugin {
|
||||
@Override
|
||||
public String getMainClass() {
|
||||
return Template.class.getName(); // 返回插件主类
|
||||
}
|
||||
|
||||
import com.axis.innovators.box.plugins.LoadingCorePlugin;
|
||||
import com.axis.innovators.template.Template;
|
||||
|
||||
/**
|
||||
* 注册core插件
|
||||
*/
|
||||
public class TemplateLoadingCorePlugin implements LoadingCorePlugin {
|
||||
@Override
|
||||
public String getMainClass() {
|
||||
// 返回主类名
|
||||
return Template.class.getName();
|
||||
@Override
|
||||
public String[] getASMTransformerClass() {
|
||||
return new String[]{TemplateTransformer.class.getName()}; // 返回Transformer类
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public String[] getASMTransformerClass() {
|
||||
// 返回字节码转换器类名
|
||||
return new String[]{TemplateTransformer.class.getName()};
|
||||
```
|
||||
3. 实现 `IClassTransformer` 接口（使用 ASM 修改字节码）：
|
||||
```java
|
||||
public class TemplateTransformer implements IClassTransformer {
|
||||
@Override
|
||||
public byte[] transform(String name, String transformedName, byte[] basicClass) {
|
||||
// 使用 ASM ClassReader/ClassWriter 修改字节码
|
||||
// 示例：将所有 private 字段和方法修改为 public
|
||||
// ... (省略具体ASM代码，参考原文档)
|
||||
return modifiedBytes;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
* IClassTransformer的实现，如：
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📡 事件驱动系统
|
||||
|
||||
基于 `EventBus` 的发布/订阅模式，实现模块解耦与通信。
|
||||
|
||||
### 核心组件
|
||||
* `EventBus`: 基础事件总线。
|
||||
* `GlobalEventBus.EVENT_BUS`: **全局单例总线**，用于跨模块通信。
|
||||
|
||||
### 使用示例
|
||||
```java
|
||||
package com.axis.core.template;
|
||||
|
||||
import com.axis.innovators.box.plugins.IClassTransformer;
|
||||
import org.objectweb.asm.*;
|
||||
|
||||
/**
|
||||
* core plugin transformer
|
||||
* @author tzdwindows 7
|
||||
*/
|
||||
public class TemplateTransformer implements IClassTransformer {
|
||||
@Override
|
||||
public byte[] transform(String s, String s1, byte[] bytes) {
|
||||
ClassReader classReader = new ClassReader(bytes);
|
||||
ClassWriter classWriter = new ClassWriter(ClassWriter.COMPUTE_MAXS);
|
||||
|
||||
ClassVisitor classVisitor = new ClassVisitor(Opcodes.ASM5, classWriter) {
|
||||
@Override
|
||||
public FieldVisitor visitField(int access, String name, String descriptor, String signature, Object value) {
|
||||
if ((access & Opcodes.ACC_PRIVATE) != 0) {
|
||||
access = (access & ~Opcodes.ACC_PRIVATE) | Opcodes.ACC_PUBLIC;
|
||||
System.out.println("Changing field access to public: " + name);
|
||||
}
|
||||
return super.visitField(access, name, descriptor, signature, value);
|
||||
}
|
||||
|
||||
@Override
|
||||
public MethodVisitor visitMethod(int access, String name, String descriptor, String signature, String[] exceptions) {
|
||||
System.out.println(name + " , descriptor:" + descriptor);
|
||||
if ((access & Opcodes.ACC_PRIVATE) != 0) {
|
||||
access = (access & ~Opcodes.ACC_PRIVATE) | Opcodes.ACC_PUBLIC;
|
||||
System.out.println("Changing method access to public: " + name);
|
||||
}
|
||||
return super.visitMethod(access, name, descriptor, signature, exceptions);
|
||||
}
|
||||
};
|
||||
|
||||
classReader.accept(classVisitor, 0);
|
||||
return classWriter.toByteArray();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 事件系统说明
|
||||
- 事件驱动架构核心组件。
|
||||
- 事件总线系统，支持跨模块通信。
|
||||
- 事件总线由 **EventBus & GlobalEventBus** 实现
|
||||
|
||||
### 1.. EventBus & GlobalEventBus 说明
|
||||
应用程序内的事件驱动架构核心组件：
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.events;
|
||||
|
||||
/**
|
||||
* 事件总线系统（支持多总线实例隔离）
|
||||
*/
|
||||
public class EventBus {
|
||||
// 核心方法
|
||||
public void register(Object listener); // 注册监听器
|
||||
public void unregister(Object target); // 注销监听器
|
||||
public boolean post(Object event); // 发布事件
|
||||
public void shutdown(); // 关闭总线
|
||||
}
|
||||
|
||||
public class GlobalEventBus {
|
||||
public static final EventBus EVENT_BUS = new EventBus(); // 全局单例总线
|
||||
}
|
||||
```
|
||||
- **EventBus**：用于处理应用程序内各个模块之间的事件通信。
|
||||
- **GlobalEventBus**：用于处理应用程序内各个模块之间的事件通信，支持多总线实例隔离。
|
||||
|
||||
### 2. EventBus & GlobalEventBus 使用示例
|
||||
|
||||
#### 示例1：基础事件处理
|
||||
```java
|
||||
// 1. 定义事件类型
|
||||
// 1. 定义事件
|
||||
public class UserLoginEvent {
|
||||
private final String username;
|
||||
private boolean cancelled;
|
||||
|
||||
public UserLoginEvent(String username) {
|
||||
this.username = username;
|
||||
}
|
||||
|
||||
// Getter/Setter...
|
||||
public UserLoginEvent(String u) { this.username = u; }
|
||||
// getters...
|
||||
}
|
||||
|
||||
// 2. 创建监听器类
|
||||
public class SecurityLogger {
|
||||
// 2. 注册监听器 (@SubscribeEvent)
|
||||
public class LoginLogger {
|
||||
public LoginLogger() {
|
||||
GlobalEventBus.EVENT_BUS.register(this);
|
||||
}
|
||||
|
||||
@SubscribeEvent
|
||||
public void logLoginAttempt(UserLoginEvent event) {
|
||||
System.out.println("[安全审计] 登录尝试: " + event.getUsername());
|
||||
public void onLogin(UserLoginEvent event) {
|
||||
System.out.println("用户登录: " + event.getUsername());
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 使用全局总线
|
||||
public class Main {
|
||||
public static void main(String[] args) {
|
||||
// 注册监听器
|
||||
GlobalEventBus.EVENT_BUS.register(new SecurityLogger());
|
||||
|
||||
// 模拟用户登录
|
||||
UserLoginEvent loginEvent = new UserLoginEvent("admin");
|
||||
GlobalEventBus.EVENT_BUS.post(loginEvent);
|
||||
}
|
||||
}
|
||||
// 3. 发布事件
|
||||
GlobalEventBus.EVENT_BUS.post(new UserLoginEvent("admin"));
|
||||
```
|
||||
- 示例2：事件取消机制
|
||||
|
||||
### 内置系统事件表
|
||||
| 事件类名 | 描述 |
|
||||
| :--- | :--- |
|
||||
| `StartupEvent` | 程序启动完成事件，常用于注册工具栏 |
|
||||
| `SettingsLoadEvents` | 设置界面初始化事件，用于添加设置项 |
|
||||
| `MainWindowEvents` | 主窗口生命周期相关事件 |
|
||||
| `CategoryRenderingEvent` | 工具栏分类渲染事件 |
|
||||
| `OpenFileEvents` | 外部文件打开请求事件 |
|
||||
| `TABUIEvents` | 选项卡 UI 属性变更事件 |
|
||||
|
||||
---
|
||||
|
||||
## 🌐 HTML 窗口集成 (JCEF)
|
||||
|
||||
通过 JCEF (Chromium) 渲染高性能 HTML/JS 界面，并支持与 Java 双向通信。
|
||||
|
||||
### 创建 HTML 窗口
|
||||
```java
|
||||
// 1. 定义可取消事件
|
||||
public class FileDeleteEvent {
|
||||
private final Path filePath;
|
||||
private boolean cancelled;
|
||||
SwingUtilities.invokeLater(() -> {
|
||||
WindowRegistry.getInstance().createNewChildWindow("ai_toolbox", builder -> {
|
||||
builder.title("AI 工具箱")
|
||||
.size(1280, 720)
|
||||
.htmlPath(FolderCreator.getJavaScriptFolder() + "/ui/index.html") // 本地HTML路径
|
||||
.build();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
// 构造方法/getters/setters...
|
||||
}
|
||||
### Java 与 JavaScript 通信 (`CefMessageRouter`)
|
||||
|
||||
// 2. 创建权限校验监听器
|
||||
public class PermissionValidator {
|
||||
@SubscribeEvent
|
||||
public void validateDeletePermission(FileDeleteEvent event) {
|
||||
if (!checkAdminAccess()) {
|
||||
event.setCancelled(true);
|
||||
System.out.println("文件删除被拒绝：权限不足");
|
||||
**1. JavaScript 调用 Java**
|
||||
```javascript
|
||||
// 在前端 JS 中调用
|
||||
window.cefQuery({
|
||||
request: JSON.stringify({ action: "getData", id: 1 }),
|
||||
onSuccess: function(response) { console.log("Java返回:", response); },
|
||||
onFailure: function(code, msg) { console.error("错误:", msg); }
|
||||
});
|
||||
```
|
||||
|
||||
**2. Java 处理请求**
|
||||
```java
|
||||
// 获取路由并添加处理器
|
||||
CefMessageRouter router = window.getMsgRouter();
|
||||
router.addHandler(new CefMessageRouterHandlerAdapter() {
|
||||
@Override
|
||||
public boolean onQuery(CefBrowser browser, CefFrame frame, long queryId,
|
||||
String request, boolean persistent, CefQueryCallback callback) {
|
||||
if (request.contains("getData")) {
|
||||
callback.success("{\"data\": \"Hello from Java\"}");
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
private boolean checkAdminAccess() {
|
||||
// 权限校验逻辑
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 主业务流程
|
||||
public class FileManager {
|
||||
public void deleteFile(Path path) {
|
||||
FileDeleteEvent event = new FileDeleteEvent(path);
|
||||
GlobalEventBus.EVENT_BUS.post(event);
|
||||
|
||||
if (!event.isCancelled()) {
|
||||
// 执行删除操作
|
||||
System.out.println("正在删除文件: " + path);
|
||||
}
|
||||
}
|
||||
}
|
||||
}, true);
|
||||
```
|
||||
|
||||
### 3.所有系统所支持的事件
|
||||
- `com.axis.innovators.box.events.CategoryRenderingEvent`: 分类栏的渲染事件
|
||||
- `com.axis.innovators.box.events.MainWindowEvents`: 主窗口事件
|
||||
- `com.axis.innovators.box.events.OpenFileEvents`: 接收文件事件
|
||||
- `com.axis.innovators.box.events.SettingsLoadEvents`: 程序初始化事件
|
||||
- `com.axis.innovators.box.events.StartupEvent`: 程序启动事件
|
||||
- `com.axis.innovators.box.events.TABUIEvents`: 选项卡Ui属性事件
|
||||
|
||||
## HTML窗口集成指南
|
||||
|
||||
我们实现了一套高性能的HTML渲染系统，通过Java Chromium Embedded Framework (JCEF) 将HTML内容无缝集成到Java桌面应用中，底层基于[jcefmaven](https://github.com/jcefmaven/jcefmaven)项目。
|
||||
|
||||
### 核心实现步骤
|
||||
|
||||
#### 1. 创建HTML窗口
|
||||
```java
|
||||
// 创建窗口引用
|
||||
AtomicReference<BrowserWindowJDialog> htmlWindow = new AtomicReference<>();
|
||||
|
||||
SwingUtilities.invokeLater(() -> {
|
||||
// 通过窗口注册表创建子窗口
|
||||
WindowRegistry.getInstance().createNewChildWindow("main", builder -> {
|
||||
htmlWindow.set(builder
|
||||
.title("Axis Innovators Box AI 工具箱") // 窗口标题
|
||||
.parentFrame(parentFrame) // 父级窗口
|
||||
.icon(getApplicationIcon()) // 应用图标
|
||||
.size(1280, 720) // 初始尺寸
|
||||
.htmlPath(getHtmlResourcePath()) // HTML文件路径
|
||||
.operationHandler(createOperationHandler()) // 自定义操作处理器
|
||||
.build());
|
||||
});
|
||||
|
||||
// 配置消息路由
|
||||
configureMessageRouter(htmlWindow.get());
|
||||
});
|
||||
```
|
||||
|
||||
#### 2. 辅助方法
|
||||
```java
|
||||
// 获取应用图标
|
||||
private Image getApplicationIcon() {
|
||||
return new ImageIcon(Objects.requireNonNull(
|
||||
MainApplication.class.getClassLoader()
|
||||
.getResource("icons/logo.png")
|
||||
)).getImage();
|
||||
}
|
||||
|
||||
// 获取HTML资源路径
|
||||
private String getHtmlResourcePath() {
|
||||
return FolderCreator.getJavaScriptFolder() + "/AIaToolbox_dark.html";
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 配置消息路由器
|
||||
```java
|
||||
private void configureMessageRouter(BrowserWindowJDialog window) {
|
||||
CefMessageRouter msgRouter = window.getMsgRouter();
|
||||
if (msgRouter == null) return;
|
||||
|
||||
msgRouter.addHandler(new CefMessageRouterHandlerAdapter() {
|
||||
@Override
|
||||
public boolean onQuery(CefBrowser browser, CefFrame frame, long queryId,
|
||||
String request, boolean persistent, CefQueryCallback callback) {
|
||||
// 处理来自HTML的请求
|
||||
handleBrowserRequest(request, callback);
|
||||
return true; // 表示已处理该请求
|
||||
}
|
||||
|
||||
@Override
|
||||
public void onQueryCanceled(CefBrowser browser, CefFrame frame, long queryId) {
|
||||
// 处理请求取消逻辑
|
||||
System.out.println("请求被取消: " + queryId);
|
||||
}
|
||||
}, true); // true表示优先处理
|
||||
}
|
||||
```
|
||||
|
||||
## HTML事件
|
||||
HTML窗口内可以捕捉到一些Java的事件
|
||||
|
||||
| 事件名 | 介绍 | 触发时机 |
|
||||
|--------|------------|---------------------|
|
||||
| `javaFontsLoaded` | Java字体加载完成 | Java字体信息传输到HTML时，或在在更新主题时 |
|
||||
| `javaThemeChanged` | 在主题发生变化时触发 | 在更新主题时 |
|
||||
|
||||
#### 具体示例
|
||||
**3. HTML 监听 Java 事件**
|
||||
HTML 页面可监听来自 Java 的系统级通知：
|
||||
* `javaFontsLoaded`: 字体加载完成。
|
||||
* `javaThemeChanged`: 主题变更通知。
|
||||
|
||||
```javascript
|
||||
// 监听Java字体加载事件
|
||||
document.addEventListener('javaFontsLoaded', function(event) {
|
||||
const fontInfo = event.detail;
|
||||
console.log('接收到Java字体信息:', fontInfo);
|
||||
|
||||
// 应用Java字体到界面
|
||||
applyJavaFonts(fontInfo);
|
||||
});
|
||||
// 监听Java主题变化事件
|
||||
document.addEventListener('javaThemeChanged', function(event) {
|
||||
const themeInfo = event.detail;
|
||||
console.log('接收到Java主题信息:', themeInfo);
|
||||
applyJavaTheme(themeInfo);
|
||||
});
|
||||
```
|
||||
### 窗口管理系统说明
|
||||
|
||||
通过`WindowRegistry`统一管理应用窗口：
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `createNewWindow(String id, Consumer<Builder> config)` | 创建主窗口 |
|
||||
| `createNewChildWindow(String id, Consumer<Builder> config)` | 创建模态子窗口 |
|
||||
| `getWindow(String id)` | 获取已注册窗口 |
|
||||
| `unregisterWindow(String id)` | 关闭指定窗口 |
|
||||
|
||||
### CefMessageRouter 使用指南
|
||||
|
||||
实现Java与JavaScript双向通信的核心组件：
|
||||
|
||||
1. **消息处理流程**：
|
||||
- JavaScript → Java: 通过`window.cefQuery()`发送请求
|
||||
- Java → JavaScript: 使用`CefFrame.executeJavaScript()`执行脚本
|
||||
|
||||
2. **核心方法**：
|
||||
```java
|
||||
// JavaScript调用示例
|
||||
function callJavaMethod(data) {
|
||||
window.cefQuery({
|
||||
request: JSON.stringify(data),
|
||||
onSuccess: response => console.log("Success:", response),
|
||||
onFailure: (err, msg) => console.error("Error:", msg)
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
3. **最佳实践**：
|
||||
- 使用JSON格式进行数据交换
|
||||
- 为不同功能模块使用独立的路由处理器
|
||||
- 在窗口关闭前移除所有路由处理器
|
||||
|
||||
### 生命周期管理
|
||||
```java
|
||||
// 关闭窗口时清理资源
|
||||
htmlWindow.get().addWindowListener(new WindowAdapter() {
|
||||
@Override
|
||||
public void windowClosing(WindowEvent e) {
|
||||
window.getMsgRouter().dispose();
|
||||
CefApp.getInstance().dispose();
|
||||
}
|
||||
document.addEventListener('javaThemeChanged', (e) => {
|
||||
console.log('主题变更为:', e.detail);
|
||||
});
|
||||
```
|
||||
|
||||
## 核心类说明
|
||||
---
|
||||
|
||||
### 1. AxisInnovatorsBox
|
||||
窗口实例的核心操作类，提供以下功能：
|
||||
- `getMain()`: 获取当前AxisInnovatorsBox实例
|
||||
- `getMainWindow()`: 获取主窗口实例
|
||||
- `quit()`: 退出程序
|
||||
- `organizingCrashReports(Exception)`: 组织崩溃报告，用于在应用程序发生异常时生成崩溃报告。
|
||||
- `popupWindow(WindowsJDialog)`: 弹出新的窗口，并将其添加到窗口列表中。
|
||||
- `isWindowStartup(WindowsJDialog)`: 判断指定的窗口是否已经启动。
|
||||
- `clearWindow(WindowsJDialog)`: 清除指定的窗口，并将其从窗口列表中移除。
|
||||
- `reloadAllWindow()`: 重新加载窗口。
|
||||
- `getRegistrationTool()`: 获取注册工具实例。
|
||||
- `getArgs()`: 获取命令行参数。
|
||||
- `isWindow()`: 判断窗口是否已经启动。
|
||||
- `getVersion()`: 获取应用程序的版本号。
|
||||
- `getRegistrationTopic()`: 获取注册主题实例。
|
||||
- `getAuthor()`: 获取应用程序的作者信息。
|
||||
- `getStateManager()`: 获取状态管理器实例。
|
||||
## 📚 核心 API 参考
|
||||
|
||||
### 2. RegistrationTool
|
||||
负责在 **应用程序启动阶段** 注册和管理工具分类的核心组件，具备插件系统集成能力：
|
||||
### 1. `AxisInnovatorsBox` (主程序入口)
|
||||
获取应用全局状态和核心管理器。
|
||||
* `getInstance()` / `getMain()`: 获取单例。
|
||||
* `getRegistrationTool()`: 获取工具注册器。
|
||||
* `getRegistrationTopic()`: 获取主题注册器。
|
||||
* `getMainWindow()`: 获取主窗口对象。
|
||||
* `popupWindow(WindowsJDialog)` / `clearWindow(...)`: 窗口堆栈管理。
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.register;
|
||||
### 2. `RegistrationTool` (工具注册)
|
||||
在 `StartupEvent` 中使用，用于向主界面添加功能入口。
|
||||
* `addToolCategory(category, regName)`: 注册工具分类。
|
||||
* `getToolCategory(UUID)`: 获取已注册分类。
|
||||
|
||||
/**
|
||||
* 工具分类注册中心（窗口启动前必须完成注册）
|
||||
*/
|
||||
public class RegistrationTool {
|
||||
// 构造方法关联主程序实例
|
||||
public RegistrationTool(AxisInnovatorsBox main) { ... }
|
||||
|
||||
// 核心功能方法
|
||||
public boolean addToolCategory(ToolCategory category, String regName);
|
||||
public void addToolCategory(ToolCategory category, PluginDescriptor descriptor, String regName);
|
||||
public ToolCategory getToolCategory(UUID id);
|
||||
public UUID getUUID(String registeredName);
|
||||
}
|
||||
```
|
||||
- `addToolCategory(ToolCategory category, String regName)`: 向工具分类注册中心添加一个新的工具分类。
|
||||
- `addToolCategory(ToolCategory category, PluginDescriptor descriptor, String regName)`: 向工具分类注册中心添加一个新的工具分类，同时关联插件描述符。
|
||||
- `getToolCategory(UUID id)`: 通过UUID获取工具分类。
|
||||
- `getUUID(String registeredName)`: 通过注册名称获取UUID。
|
||||
### 3. `RegistrationTopic` (主题注册)
|
||||
在初始化阶段注册自定义 LookAndFeel 或主题类。
|
||||
* `addTopic(topicClass, name, tip, icon, regName)`: 注册主题。
|
||||
* **注意**: 注册名称 (`regName`) 必须唯一，否则会抛出异常。
|
||||
|
||||
#### 注册示例
|
||||
```java
|
||||
// 创建调试工具分类
|
||||
MainWindow.ToolCategory debugCategory = new MainWindow.ToolCategory(
|
||||
"逆向分析工具",
|
||||
"icons/debugger.png",
|
||||
"二进制逆向分析工具集"
|
||||
);
|
||||
### 4. `RegistrationSettingsItem` (设置项注册)
|
||||
在 `SettingsLoadEvents` 中使用，向设置中心添加面板。
|
||||
* `addSettings(JPanel panel, String title, Icon icon, String tip, PluginDescriptor plugin, String regName)`: 注册设置页。
|
||||
|
||||
// 添加工具项（带点击事件）
|
||||
debugCategory.addTool(new MainWindow.ToolItem(
|
||||
"内存分析器",
|
||||
"icons/memory.png",
|
||||
"实时查看进程内存映射",
|
||||
1,
|
||||
new AbstractAction() {
|
||||
@Override
|
||||
public void actionPerformed(ActionEvent e) {
|
||||
JOptionPane.showMessageDialog(null, "启动内存分析模块...");
|
||||
}
|
||||
}
|
||||
));
|
||||
### 5. `StateManager` (状态持久化)
|
||||
用于保存插件配置或用户偏好设置（键值对）。
|
||||
* `saveState(key, value)`: 持久化保存。
|
||||
* `getStateAsString(key)` / `getStateAsInt(key)`: 读取配置。
|
||||
|
||||
// 注册到系统（必须在窗口初始化前完成）
|
||||
try {
|
||||
registrationTool.addToolCategory(debugCategory, "system:reverseEngineering");
|
||||
} catch (RegistrationError ex) {
|
||||
System.err.println("注册失败: " + ex.getMessage());
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 3. RegistrationTopic
|
||||
负责在 **应用程序初始化阶段** 统一管理UI主题注册的核心组件，支持类名/LookAndFeel双模式主题注入：
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.register;
|
||||
|
||||
/**
|
||||
* 主题注册中心（窗口初始化前必须完成注册）
|
||||
*/
|
||||
public class RegistrationTopic {
|
||||
// 核心注册方法
|
||||
public void addTopic(String topicClass, String name, String tip, Icon icon, String regName);
|
||||
public void addTopic(LookAndFeel laf, String name, String tip, Icon icon, String regName);
|
||||
|
||||
// 状态管理方法
|
||||
public boolean isLoading(String themeName);
|
||||
public void setLoading(String themeName);
|
||||
}
|
||||
```
|
||||
- `addTopic(String topicClass, String name, String tip, Icon icon, String regName)`: 向主题注册中心添加一个新的主题。
|
||||
- `addTopic(LookAndFeel laf, String name, String tip, Icon icon, String regName)`: 向主题注册中心添加一个新的主题，同时关联LookAndFeel。
|
||||
- `isLoading(String themeName)`: 判断指定主题是否正在加载。
|
||||
- `setLoading(String themeName)`: 设置指定主题为正在加载状态。
|
||||
#### 注册示例
|
||||
```java
|
||||
try {
|
||||
// 重复注册相同名称
|
||||
topicRegistry.addTopic("com.axis.light.MaterialTheme",
|
||||
"质感浅色",
|
||||
"Material Design风格",
|
||||
materialIcon,
|
||||
"theme:light"); // 已存在同名注册
|
||||
} catch (RegistrationError ex) {
|
||||
// 捕获异常并提示：theme:light duplicate registered names
|
||||
JOptionPane.showMessageDialog(null, ex.getMessage());
|
||||
}
|
||||
```
|
||||
|
||||
### 4. StateManager
|
||||
应用程序状态管理工具类，提供跨会话的配置持久化能力：
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.tools;
|
||||
|
||||
/**
|
||||
* 状态持久化管理器（线程安全）
|
||||
*/
|
||||
public class StateManager {
|
||||
// 构造方法
|
||||
public StateManager(); // 默认使用toolbox.properties
|
||||
public StateManager(String customFileName); // 自定义状态文件名
|
||||
|
||||
// 核心操作方法
|
||||
public void saveState(String key, [int|long|boolean...] value);
|
||||
public [String|int|boolean...] getStateAs[Type](String key);
|
||||
}
|
||||
```
|
||||
- `saveState(String key, [int|long|boolean...] value)`: 保存状态到配置文件。
|
||||
- `getStateAs[Type](String key)`: 从配置文件获取状态。
|
||||
- `[String|int|boolean...]`: 支持多种数据类型保存到配置文件，并支持多种数据类型从配置文件获取。
|
||||
|
||||
### 5. RegistrationSettingsItem
|
||||
负责管理系统 **设置中心** 的配置面板注册，支持插件化扩展设置项的核心组件：
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.register;
|
||||
|
||||
/**
|
||||
* 设置项注册中心（集成插件配置扩展能力）
|
||||
*/
|
||||
public class RegistrationSettingsItem extends WindowsJDialog {
|
||||
// 核心注册方法
|
||||
public void addSettings(JPanel panel, String title, Icon icon, String tip, String regName);
|
||||
public void addSettings(JPanel panel, String title, Icon icon, String tip,
|
||||
PluginDescriptor plugin, String regName);
|
||||
|
||||
// 查询方法
|
||||
public static List<RegistrationSettingsItem> getRegistrationsByPlugin(PluginDescriptor plugin);
|
||||
}
|
||||
```
|
||||
- `addSettings(JPanel panel, String title, Icon icon, String tip, String regName)`: 向设置项注册中心添加一个新的设置项。
|
||||
- `addSettings(JPanel panel, String title, Icon icon, String tip, PluginDescriptor plugin, String regName)`: 向设置项注册中心添加一个新的设置项，同时关联插件描述符。
|
||||
- `getRegistrationsByPlugin(PluginDescriptor plugin)`: 通过插件描述符获取关联的设置项列表。
|
||||
|
||||
### 6. LanguageManager
|
||||
应用程序多语言管理核心组件，支持动态加载与合并多语言资源：
|
||||
|
||||
```java
|
||||
package com.axis.innovators.box.register;
|
||||
|
||||
/**
|
||||
* 国际化语言管理中心（支持插件扩展语言包）
|
||||
*/
|
||||
public class LanguageManager {
|
||||
// 核心操作方法
|
||||
public static void addLanguage(Language lang);
|
||||
public static void loadLanguage(String regName);
|
||||
public static Language getLoadedLanguages();
|
||||
public static Language getLanguage(String identifier);
|
||||
}
|
||||
```
|
||||
- `addLanguage(Language lang)`: 向语言管理中心添加一个新的语言包。
|
||||
- `loadLanguage(String regName)`: 加载指定语言包。
|
||||
- `getLoadedLanguages()`: 获取当前系统加载的语言包。
|
||||
- `getLanguage(String identifier)`: 通过标识符获取语言包。
|
||||
### 6. `LanguageManager` (国际化)
|
||||
* `addLanguage(Language lang)`: 注册新的语言包。
|
||||
* `getLanguage(String id)`: 获取特定语言资源。
|
||||
|
||||
### 7. `WindowRegistry` (窗口管理)
|
||||
统一管理 JCEF 和原生 Swing 窗口的生命周期。
|
||||
* `createNewChildWindow(id, config)`: 创建模态子窗口。
|
||||
* `unregisterWindow(id)`: 安全关闭并注销窗口。
|
||||
Reference in New Issue
Block a user