Booxin 插件开发者文档

Booxin 插件的定位是扩展启动器本身， 而不是重新实现 Minecraft Mod Loader。 插件开发者应该优先使用 Booxin 提供的公开扩展接口， 而不是直接修改 Launcher 内部文件。

兼容性原则

• 优先使用公开文档中明确说明的 API。
• 不要依赖 Android 应用内部绝对路径。
• 不要依赖插件安装后的内部缓存结构。
• 不要假设某个字段一定存在于所有 Launcher 版本。
• 插件如果依赖特定版本能力，应在插件说明中明确标注版本要求。

开发插件时，第一步通常不是写复杂的 UI，而是先确认 Launcher 能正确识别你的插件。

2.1 创建插件目录

推荐在本地建立一个独立目录，并把插件清单文件放在插件 ZIP 的根目录。

hello-booxin/
├── booxin-plugin.json
├── icon.png
├── pages/
│   └── index.html
├── assets/
│   └── ...
└── fonts/
    └── ...

2.2 插件清单

插件清单用于描述插件的基本信息。 下面只演示通用的基础信息字段，不代表所有版本的完整字段集合。

{
  "name": "Hello Booxin",
  "version": "1.0.0",
  "author": "YourName",
  "description": "我的第一个 Booxin 插件"
}

至少应该保证插件名称、版本、作者和描述能够准确表达插件用途。

2.3 先验证插件是否被识别

1. 创建插件目录。
2. 放入插件清单文件。
3. 按照目标 Launcher 版本要求打包。
4. 安装插件。
5. 在插件管理界面确认插件是否出现。

2.4 关于“问候语插件”

“问候语插件”适合作为第一个入门示例， 但不要在没有确认 API 的情况下自行添加一个所谓的 greeting、homeGreeting 或其他字段。

如果目标版本已经提供问候语相关 API， 请直接按照该版本的实际字段和事件接口编写。 本文档不会虚构一个固定字段名。

Booxin 插件的一个主要用途是扩展启动器 UI。 UI API 可以理解成几个层次： 插件信息 → UI 配置 → 视觉表现 → 控件行为 → 页面逻辑。

3.1 基础 UI 配置

UI 配置一般需要解决三个问题： “是什么”、“显示什么”、“是否启用”。

3.2 常见视觉能力

如果当前版本开放对应能力，插件可以参与启动器的视觉表现。

3.3 自定义控件

自定义控件的核心可以拆成以下几个部分：

3.4 主题字段

主题系统可以理解为一组统一的视觉变量。 常见概念包括：

3.5 操作与事件

操作系统可以简单理解为： 用户产生事件 → Launcher 判断事件 → 插件执行对应逻辑。

3.6 自定义页面与 JavaScript

如果当前版本开放页面插件能力， 可以使用 HTML、CSS、JavaScript 制作插件自己的页面。

一个页面配置可以抽象成：

{
  "type": "page",
  "id": "example-page",
  "name": "Example Page",
  "url": "pages/index.html"
}

JavaScript Bridge

JavaScript Bridge 用于让插件页面与 Launcher 进行通信。 具体可调用的方法必须以当前版本实际提供的 Bridge API 为准。

常见需求包括：

• 读取插件或 Launcher 提供的信息。
• 显示提示信息。
• 打开外部链接。
• 请求页面导航。
• 关闭插件页面。

3.7 深度换皮（customShell）

若只想改配色 / 壁纸 / 文案，请使用 customTheme。 若需要用一整套自定义界面（侧栏、主页、启动按钮等）替换默认顶栏与主页， 请使用 customShell。

深度换皮由启动器托管 WebView 加载插件内 HTML， 不是替换任意 Android 原生布局 XML。

{
  "schema": 1,
  "id": "my-custom-shell",
  "name": "我的界面包",
  "version": "1.0.0",
  "type": "ui",
  "features": {
    "customShell": true
  },
  "shell": {
    "entry": "shell/index.html",
    "hideChrome": true,
    "keepBackground": true
  }
}

权限

启用含 customShell 的插件时，启动器会弹出 自定义界面权限 确认框。 用户允许后才会替换默认界面并注入桥接对象。 拒绝后仍可启用主题等其它能力。

JavaScript Bridge：BooxinShell

用户授权后注入。常用方法：

插件可以携带自己的资源文件。 推荐将资源放在插件自己的目录中，并通过相对路径引用。

hello-booxin/
├── booxin-plugin.json
├── icon.png
├── assets/
│   ├── background.png
│   ├── logo.png
│   └── sounds/
├── pages/
│   └── index.html
└── fonts/
    └── custom.ttf

资源建议

• 文件名尽量使用英文、数字、下划线或短横线。
• 不要使用绝对路径。
• 不要依赖其他插件的私有资源。
• 大图片应注意文件体积和内存占用。
• 字体文件应确认许可证允许随插件分发。

插件开发完成后，建议按照以下顺序进行测试。

5.1 基础安装测试

1. 确认插件清单文件存在。
2. 确认 ZIP 结构正确。
3. 安装插件。
4. 检查插件是否出现在插件管理界面。
5. 启用插件。
6. 重启 Launcher 再检查一次。

5.2 功能测试

• 检查插件 UI 是否正常显示。
• 检查按钮和输入操作。
• 检查页面打开和关闭。
• 检查资源加载。
• 检查不同窗口尺寸。
• 检查 PC / 移动端差异。

5.3 卸载测试

一个合格的插件不仅要能够安装，也应该能够被正常禁用和卸载。

Renderer、Driver 等属于比普通 UI 插件更底层的扩展能力。 如果目标版本已经正式开放相关能力，请严格按照对应版本提供的安装器、 文件格式和兼容性要求使用。

为什么需要单独规范？

Renderer / Driver 会直接影响图形渲染和游戏启动环境， 与普通 UI 插件的生命周期不同。 因此不能简单地认为“把一个 APK 或 so 放进去就能作为插件”。

如果当前版本没有公开某种 Renderer / Driver 插件规范， 请不要自行制作依赖内部目录的安装方案。

如果插件通过 Booxin 插件商店或其他分发渠道发布， 插件包除了能够运行，还需要满足基本的可分发要求。

插件包要求

• 插件信息完整。
• 版本号明确。
• 作者信息真实。
• 插件用途描述清楚。
• 资源文件能够正常加载。
• 不存在明显恶意行为。
• 不会通过插件偷偷修改与自身功能无关的用户文件。

下载失败排查

准备发布插件时，建议提供以下信息：

建议同时提供

• 插件图标。
• 功能截图。
• 兼容 Launcher 版本。
• 已知问题。
• 更新日志。
• 开源地址（如果插件开源）。
• 联系方式。

以下分类用于帮助开发者理解插件功能方向， 不应理解成某个固定的官方枚举值。

最重要的排查方法

如果插件出现问题，先把问题缩小到最小：

1. 只保留插件清单。
2. 确认 Launcher 能识别。
3. 加入一个最简单的功能。
4. 确认功能正常。
5. 再逐步加入其他代码和资源。

发布之前可以逐项检查下面的内容。

如果你不想完全手写插件，可以使用 Booxin 提供的开发工具或相关工具链进行开发。