# BrowserCreationCallback 接口技术文档

**包路径:** `com.axis.innovators.box.events.BrowserCreationCallback`  
**类型:** 接口 (Interface)  
**主要功能:** 浏览器窗口布局自定义回调  
**作者:** tzdwindows 7

---

## 1. 概述

`BrowserCreationCallback` 是 **Axis Innovators Box** 框架中用于高度定制浏览器窗口布局的扩展接口。

在框架启动嵌入式浏览器窗口（如 HTML 查看器、数据库管理工具、或 AI 界面）时，默认会执行一套标准的布局逻辑（通常是将浏览器组件充满整个内容区域）。通过实现此接口，开发者可以拦截并接管窗口的布局过程，从而在浏览器组件周边添加自定义的 UI 元素（如侧边栏、工具栏、状态栏等）。

## 2. 核心方法详解

### 2.1 `onLayoutCustomization`

```java
boolean onLayoutCustomization(
        Window window,
        Container contentPane,
        Component browserComponent,
        Object builder
);
```

#### 参数说明：
*   **`window`**: 当前正在创建的顶级窗口对象（通常是 `JFrame` 或 `JDialog` 的实例）。
*   **`contentPane`**: 窗口的主内容面板。开发者应在此容器上执行 `setLayout` 或 `add` 操作。
*   **`browserComponent`**: 已经实例化完成的浏览器渲染组件（UI 组件）。
*   **`builder`**: 触发创建流程的构建器对象（通常是内部的 `BrowserWindowBuilder`）。通过此对象可以获取更多上下文配置。

#### 返回值逻辑：
*   **`true` (已处理)**: 告诉框架：*“我已经手动安排好了所有组件的布局，请不要再执行系统默认的布局逻辑。”*
*   **`false` (未完全处理)**: 告诉框架：*“我可能做了一些预处理（如设置了背景色），但请继续执行默认的布局逻辑（通常是将 `browserComponent` 放入 `BorderLayout.CENTER`）。”*

---

## 3. 使用场景

该回调接口通常用于以下高级自定义需求：
1.  **添加导航栏**: 在浏览器组件上方添加地址栏、后退/前进按钮。
2.  **集成侧边栏**: 在浏览器左侧添加树状菜单或历史记录面板。
3.  **多组件混排**: 将浏览器作为界面的一部分，与其他 Swing 组件（如表格、控制台）共同展示。
4.  **注入装饰器**: 为浏览器窗口添加自定义的边框、水印或重写背景。

---

## 4. 代码示例：在浏览器上方添加工具栏

以下示例展示了如何使用该回调在浏览器窗口中插入一个简单的工具栏：

```java
BrowserCreationCallback myCallback = (window, contentPane, browserComponent, builder) -> {
    // 1. 设置内容面板布局
    contentPane.setLayout(new BorderLayout());
    
    // 2. 创建自定义工具栏
    JPanel toolbar = new JPanel(new FlowLayout(FlowLayout.LEFT));
    toolbar.add(new JButton("刷新"));
    toolbar.add(new JButton("主页"));
    
    // 3. 将自定义组件和浏览器组件添加到面板
    contentPane.add(toolbar, BorderLayout.NORTH);
    contentPane.add(browserComponent, BorderLayout.CENTER);
    
    // 4. 返回 true，表示我们已经手动完成了布局
    return true; 
};
```

---

## 5. 设计优势

*   **非侵入式修改**: 无需修改框架核心代码即可改变浏览器窗口的呈现方式。
*   **灵活性**: 基于接口的设计允许每个工具（Tool）根据自身业务需求定义完全不同的布局方案。
*   **控制反转 (IoC)**: 框架负责处理繁琐的浏览器引擎初始化，而将 UI 的最终决定权交还给开发者。

---
*文档生成时间: 2026-01-02*