ToolHub 悬浮球 v2.0 – Android 全局效率工具集-阿然

🎯 ToolHub 悬浮球 v2.0

基于 ShortX 与 Rhino JS 的 Android System Server 级悬浮窗工具集

✨ 核心功能

智能吸附

自动贴边，闲置半隐藏，防误触设计

一键执行

Shell/App/广播/Content 六种按钮类型

可视化配置

JSON Schema 自动生成设置界面

主题切换

白天/黑夜/跟随系统三模式

异常恢复

完善的 try-catch，崩溃自动恢复

性能优化

LRU 缓存、防抖节流、资源自动清理

📖 使用指南

悬浮球操作

按钮编辑

配置修改

操作	触发方式	功能
单击	点击悬浮球	打开/关闭主面板
长按	按住 600ms	打开设置面板
拖拽	按住并移动	调整悬浮球位置
释放	拖拽后松手	自动吸附到边缘

① 长按悬浮球 → ② 点击「按钮管理」 → ③ 选择「添加按钮」

④ 填写信息（标题/图标/类型/参数）

⑤ 点击「暂存修改」 → ⑥ 点击「保存生效」

① 长按悬浮球打开设置面板

② 修改配置（实时预览效果）

③ 点击「确认」保存配置

⚙️ 配置说明

悬浮球外观

BALL_SIZE_DP	int	45	悬浮球大小（dp）
BALL_ICON_TYPE	enum	app	图标类型
BALL_IDLE_ALPHA	float	0.6	闲置时不透明度
BALL_TEXT	string	–	悬浮球文字

面板布局

PANEL_ROWS	int	6	面板行数
PANEL_COLS	int	1	面板列数
PANEL_ITEM_SIZE_DP	int	64	按钮尺寸（dp）
PANEL_GAP_DP	int	8	按钮间距（dp）

交互设置

LONG_PRESS_MS	int	600	长按触发时间（ms）
CLICK_COOLDOWN_MS	int	280	点击冷却时间（ms）
ENABLE_SNAP_TO_EDGE	bool	true	启用边缘吸附
EDGE_VISIBLE_RATIO	float	0.7	吸附后露出比例

主题配置

THEME_MODE	enum	1	0=跟随系统, 1=白天, 2=黑夜
THEME_ACCENT_LIGHT	string	#FF3A86FF	白天强调色
THEME_ACCENT_DARK	string	#FF90CAF9	黑夜强调色

🔘 按钮类型

🐚 Shell 按钮 – 执行 Shell 命令

{
  "type": "shell",
  "title": "重启系统",
  "cmd": "reboot",
  "iconResName": "refresh_line"
}

通过广播桥执行 Shell 命令，支持明文或 Base64

📱 App 按钮 – 启动指定应用

{
  "type": "app",
  "title": "微信",
  "pkg": "com.tencent.mm",
  "launchUserId": 0,
  "iconResName": "wechat_fill"
}

启动指定应用，支持多用户（0=主用户，10/999=分身）

📡 Broadcast 按钮 – 发送广播

{
  "type": "broadcast",
  "title": "发送测试广播",
  "action": "com.example.TEST",
  "extras": {"key": "value"}
}

🔗 Intent 按钮 – 启动任意 Intent

{
  "type": "intent",
  "title": "打开设置",
  "uri": "intent:#Intent;action=android.settings.SETTINGS;end"
}

🗄️ Content 按钮 – 操作 ContentProvider

{
  "type": "content",
  "title": "读取亮度",
  "mode": "get",
  "uri": "content://settings/system/screen_brightness"
}

模式: get(读取) / put(写入) / query(查询) / view(查看)

⚡ Shortcut 按钮 – 系统快捷方式

{
  "type": "shortcut",
  "title": "创建闹钟",
  "pkg": "com.android.deskclock",
  "shortcutId": "new_alarm",
  "userId": 0
}

🏗️ 技术架构

┌─────────────────────────────────────────────────────┐
│                    UI 层                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │  悬浮球   │ │  面板    │ │  设置    │            │
│  └──────────┘ └──────────┘ └──────────┘            │
├─────────────────────────────────────────────────────┤
│                核心控制层 (FloatBallAppWM)           │
├─────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │Shell执行 │ │ App启动  │ │广播发送  │            │
│  └──────────┘ └──────────┘ └──────────┘            │
├─────────────────────────────────────────────────────┤
│              基础设施层                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │WindowMgr │ │ Handler  │ │  Cache   │            │
│  └──────────┘ └──────────┘ └──────────┘            │
└─────────────────────────────────────────────────────┘

独立线程

HandlerThread 托管窗口操作，避免 ANR

输入法兼容

完美适配软键盘弹出

资源缓存

LRU 机制，最大 120 项

异常恢复

完善保护，崩溃自动恢复

防抖节流

配置保存 250ms 去抖

🔧 故障排查

Q1: 悬浮球不显示？

检查日志 start ok 是否出现
确认 ShortX 有悬浮窗权限
检查 LOG_ENABLE 是否为 true

Q2: Shell 命令不执行？

检查日志 shell via broadcast ok 是否出现
确认 ShortX 广播接收器正常工作
检查按钮 cmd 或 cmd_b64 字段

Q3: 图标加载失败？

检查 iconPath 是否为绝对路径
检查文件是否存在且有读取权限
查看日志中的加载错误

Q4: 配置不生效？

检查 settings.json 格式
查看日志中的校验错误
确保点击「保存生效」而非仅「暂存」

📝 更新日志

v2.0.0 – 2026-03-19 ⭐ 最新
✅ 新增 Content 类型按钮、ShortX 内置图标支持、配置校验层（59项规则）
✅ 修复 Timer 泄漏、HandlerThread 泄漏、优化日志与资源清理
v1.0.0 – 2025-12-23
🎉 初始版本发布：悬浮球基础功能、Shell/App/Broadcast/Intent 支持

作者：阿然 (xin-blog.com) | 维护：AI Assistant
许可证：MIT License | 致谢：ShortX 平台、Remix Icon
文档版本：v2.0.0 | 最后更新：2026-03-19

文章版权归作者所有，未经允许请勿转载。

THE END

ShortX