ffbbcf647f
- 常用颜色网格从固定 4x5 改为根据屏幕宽度自动计算列数 (与 ShortX 图标列表一致的 adaptive layout) - 图标浮窗选择器改为翻页模式，按当前可见容量动态分页 - 修复图标选择器关闭后无法再次打开的问题 - 入口返回信息增加中文 msg/syncMsg 及 updatedModules 字段 - 同步更新 README 文档
194 lines
6.0 KiB
Markdown
194 lines
6.0 KiB
Markdown
# ShortX ToolHub
|
||
|
||
一个模块化的 ShortX JS 浮窗工具框架，支持子模块自动下载、按 `Last-Modified` 热更新、启动日志记录，以及面向大图标库的分页式 ShortX 图标选择器。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
### 实机（ShortX 数据目录）
|
||
```
|
||
shortx.getShortXDir()/
|
||
├── ToolHub/
|
||
│ ├── code/
|
||
│ │ ├── th_01_base.js
|
||
│ │ ├── th_02_core.js
|
||
│ │ ├── th_03_icon.js
|
||
│ │ ├── th_04_theme.js
|
||
│ │ ├── th_05_persistence.js
|
||
│ │ ├── th_06_icon_parser.js
|
||
│ │ ├── th_07_shortcut.js
|
||
│ │ ├── th_08_content.js
|
||
│ │ ├── th_09_animation.js
|
||
│ │ ├── th_10_shell.js
|
||
│ │ ├── th_11_action.js
|
||
│ │ ├── th_12_rebuild.js
|
||
│ │ ├── th_13_panel_ui.js
|
||
│ │ ├── th_14_panels.js
|
||
│ │ ├── th_15_extra.js
|
||
│ │ └── th_16_entry.js
|
||
│ └── logs/
|
||
│ └── init.log
|
||
```
|
||
|
||
### 服务器（项目维护目录）
|
||
```
|
||
ToolHub/
|
||
├── ToolHub.js
|
||
├── README.md
|
||
└── code/
|
||
├── th_01_base.js
|
||
├── th_02_core.js
|
||
├── th_03_icon.js
|
||
├── th_04_theme.js
|
||
├── th_05_persistence.js
|
||
├── th_06_icon_parser.js
|
||
├── th_07_shortcut.js
|
||
├── th_08_content.js
|
||
├── th_09_animation.js
|
||
├── th_10_shell.js
|
||
├── th_11_action.js
|
||
├── th_12_rebuild.js
|
||
├── th_13_panel_ui.js
|
||
├── th_14_panels.js
|
||
├── th_15_extra.js
|
||
└── th_16_entry.js
|
||
```
|
||
|
||
---
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 放置入口文件
|
||
将 `ToolHub.js` 内容粘贴到 ShortX 任务中。
|
||
|
||
### 2. 直接运行
|
||
入口文件会自动：
|
||
1. 检查并创建 `ToolHub/code/`
|
||
2. 修复目录权限（`chmod 700` + `chown 1000:1000`）
|
||
3. 对 16 个子模块做 HEAD 检测
|
||
4. 缺失或有更新时自动下载覆盖
|
||
5. 记录启动日志到 `ToolHub/logs/init.log`
|
||
|
||
---
|
||
|
||
## 返回信息格式
|
||
|
||
成功启动示例：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"started": true,
|
||
"msg": "ToolHub 启动成功：已按 WM 专属 HandlerThread 模型启动",
|
||
"syncMsg": "本次已覆盖更新 2 个子模块（新增 0 / 覆盖 2）：th_14_panels.js、th_16_entry.js",
|
||
"updatedCount": 2,
|
||
"updatedModules": ["th_14_panels.js", "th_16_entry.js"],
|
||
"closeAction": "shortx.wm.floatball.CLOSE",
|
||
"layout": {"cols": 2, "rows": 2}
|
||
}
|
||
```
|
||
|
||
无子模块更新时：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"started": true,
|
||
"msg": "ToolHub 启动成功：已按 WM 专属 HandlerThread 模型启动",
|
||
"syncMsg": "子模块已是最新，本次未覆盖更新。",
|
||
"updatedCount": 0,
|
||
"updatedModules": [],
|
||
"closeAction": "shortx.wm.floatball.CLOSE",
|
||
"layout": {"cols": 2, "rows": 2}
|
||
}
|
||
```
|
||
|
||
如果有非关键模块加载失败，会额外返回：
|
||
- `loadMsg`
|
||
- `loadErrors`
|
||
|
||
如果启动失败，会额外返回：
|
||
- `err`
|
||
|
||
---
|
||
|
||
## 子模块热更新机制
|
||
|
||
当前机制不是版本号比对，而是：
|
||
- 对每个子模块发送 HTTP HEAD 请求
|
||
- 读取远端 `Last-Modified`
|
||
- 与本地 `.lm_模块名` 缓存比较
|
||
- 不一致则重新下载覆盖
|
||
- 网络检查失败时优先回退到本地已有文件
|
||
|
||
因此：
|
||
- **入口文件无需维护 `MODULE_MANIFEST`**
|
||
- 模块里的 `@version` 仅可作为人工注释，不参与程序判断
|
||
|
||
---
|
||
|
||
## ShortX 图标选择器优化
|
||
|
||
按钮编辑页里的 ShortX 图标选择器现已改为：
|
||
- **ShortX 图标名称编辑框已取消**，改为预览卡片 + 图标库点选
|
||
- **图标颜色支持折叠式完整调色板**，支持常用色、最近 5 色、透明度调节、RGB 三色调色器（0-255），并可切回跟随主题
|
||
- **分页模式**，不再一次性塞入大批图标
|
||
- **图标列表按当前可用宽度自动排列列数，并结合可见高度计算每页容量**
|
||
- 保留 **搜索 / 分类 / 上一页 / 下一页**
|
||
- 选中图标后自动回填并收起
|
||
- 收起后再次点击 **展开图标库** 可正常重新打开
|
||
|
||
当前交互要点：
|
||
- 常用颜色会按色相自动排序，主题色固定在最前，并像 ShortX 图标列表一样按当前可用宽度自动排布
|
||
1. 切到 `ShortX图标` 时自动展开图标库
|
||
2. 列数按当前可用宽度自动计算，屏幕更宽时一页可显示更多图标
|
||
3. 每页容量按自动列数 × 当前可见行数实时计算
|
||
4. 搜索、切分类、翻页时都会回到顶部，减少卡顿感和误触
|
||
|
||
---
|
||
|
||
## 日志系统
|
||
|
||
启动日志路径：
|
||
```text
|
||
shortx.getShortXDir() + "/ToolHub/logs/init.log"
|
||
```
|
||
|
||
记录内容包括：
|
||
- 目录创建 / 权限修复
|
||
- 更新检测
|
||
- 下载开始 / 结束 / 异常
|
||
- 模块加载失败
|
||
- 模块体积告警（>200KB）
|
||
|
||
---
|
||
|
||
## 模块职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `th_01_base.js` | 基础工具、日志、配置校验、通用辅助 |
|
||
| `th_02_core.js` | `FloatBallAppWM` 构造、基础状态与核心工具 |
|
||
| `th_03_icon.js` | 图标缓存、Bitmap 管理、悬浮球图标加载 |
|
||
| `th_04_theme.js` | 主题、颜色、样式工具 |
|
||
| `th_05_persistence.js` | 持久化与设置数据层 |
|
||
| `th_06_icon_parser.js` | 图标解析、ShortX 内置图标扫描与回退 |
|
||
| `th_07_shortcut.js` | 快捷方式选择器 |
|
||
| `th_08_content.js` | ContentProvider 读取与通用 query |
|
||
| `th_09_animation.js` | 面板动画、吸边、显示/隐藏管理 |
|
||
| `th_10_shell.js` | Shell 执行层 |
|
||
| `th_11_action.js` | 按钮动作分发与执行 |
|
||
| `th_12_rebuild.js` | 悬浮球重建逻辑 |
|
||
| `th_13_panel_ui.js` | 设置面板通用 UI 组件 |
|
||
| `th_14_panels.js` | 设置面板、按钮编辑器、ShortX 图标分页选择器 |
|
||
| `th_15_extra.js` | 主面板与附加展示层 |
|
||
| `th_16_entry.js` | 生命周期、广播注册、启动与销毁 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- 入口文件只负责加载与汇总返回信息，不承载业务 UI
|
||
- `th_16_entry.js` 属于关键模块，加载失败会直接中止启动
|
||
- 不建议把调试细节直接塞进返回 JSON，优先写日志；返回信息只保留用户判断启动/更新所需的关键信息
|
||
- 若修改了模块结构、返回字段、图标选择器交互，记得同步更新 README 与相关技能说明
|