floaty 悬浮窗

约 3662 字大约 12 分钟道无涯i

floaty 悬浮窗

floaty 是 ScriptX 里的悬浮窗模块。它现在既支持系统级悬浮窗，也支持挂在无障碍服务上的无障碍悬浮窗。你可以直接用和 ui 类似的 XML 去创建窗口，然后在脚本里继续改位置、改尺寸、找子控件、绑定点击事件。

如果你用过 Auto.js，那你可以把它先理解成：

floaty.window(xml)：可调节版本
floaty.rawWindow(xml)：不带调节拖拽层的版本
floaty.accessibilityWindow(xml)：无障碍悬浮窗里的可调节版本
floaty.accessibilityRawWindow(xml)：无障碍悬浮窗里的原始版本

但当前实现细节还是以本地源码为准，不是照搬别家的。

先记住这 16 条

floaty 依赖系统悬浮窗权限，没有权限会直接抛错或返回 false。
floaty.window(xml) 返回的是一个悬浮窗对象，不是普通 View。
floaty.rawWindow(xml) 和 window(xml) 的最大区别是默认不支持“调整模式拖拽 / 拉伸”。
floaty.accessibilityWindow(xml) / floaty.accessibilityRawWindow(xml) 不走系统悬浮窗权限，它们走的是无障碍服务的 TYPE_ACCESSIBILITY_OVERLAY 能力。
floaty.checkAccessibilityPermission() 检查的是“系统里有没有启用 ScriptX 这项无障碍服务”，不是“当前这一刻服务对象一定已经连上”。
floaty.requestAccessibilityPermission() 只是拉起系统无障碍设置页，不会自动替你打开开关。
真正创建无障碍悬浮窗时，除了服务已启用，还要求服务对象已经连上；否则会直接抛错。
floaty.window(xml) / floaty.accessibilityWindow(xml) 默认都允许后续进入调整模式；rawWindow(...) / accessibilityRawWindow(...) 默认都不允许。
floaty.window(xml) 里返回对象上的 x、y 是暴露给脚本的正常坐标，不用自己减状态栏。
window.setPosition(x, y) 和直接写 window.x = x 是等价思路。
window.setSize(width, height) 支持普通数字，也支持 -1 / -2 这种 Android MATCH_PARENT / WRAP_CONTENT。
window.getWidth() / getHeight() 返回的是“当前实际尺寸”，不是你上次传进去的原始 spec。
window.requestFocus() 适合需要输入框抢焦点、弹软键盘的场景。
window.disableFocus() 会清焦点，并尝试收起软键盘。
window.setTouchable(false) 后，这个悬浮窗会变成不可触摸穿透态。
window.exitOnClose(true) 后，手动 close() 这个窗口会顺手把当前脚本停掉。

系统悬浮窗 vs 无障碍悬浮窗

如果你第一眼还没决定该用哪组 API，先看这个对照：

目标	更适合选哪组
你已经有系统悬浮窗权限，想按最常见方式创建窗口	`floaty.window(...)` / `floaty.rawWindow(...)`
你不想依赖系统悬浮窗权限，而是准备走无障碍能力	`floaty.accessibilityWindow(...)` / `floaty.accessibilityRawWindow(...)`
你需要后面手动开调整模式	`floaty.window(...)` 或 `floaty.accessibilityWindow(...)`
你明确不希望窗口进入调整模式	`floaty.rawWindow(...)` 或 `floaty.accessibilityRawWindow(...)`
你只想先判断系统悬浮窗权限	`floaty.checkPermission()`
你只想先判断无障碍服务有没有启用	`floaty.checkAccessibilityPermission()`

直接做决定时最该看的 4 点

对比项	系统悬浮窗	无障碍悬浮窗
创建入口	`floaty.window(...)` / `floaty.rawWindow(...)`	`floaty.accessibilityWindow(...)` / `floaty.accessibilityRawWindow(...)`
前提	系统悬浮窗权限	无障碍服务启用并连上
窗口类型	`TYPE_APPLICATION_OVERLAY` / `TYPE_PHONE`	`TYPE_ACCESSIBILITY_OVERLAY`
权限引导	`floaty.requestPermission()`	`floaty.requestAccessibilityPermission()`

最直接的判断方法

如果你满足下面这条，优先走系统悬浮窗：

只是想做普通悬浮按钮、工具面板、调试窗

如果你满足下面这条，优先走无障碍悬浮窗：

脚本本来就依赖无障碍，而且你希望整套窗口能力都挂在无障碍链路上

两套最常见模板

系统悬浮窗：

if (!floaty.checkPermission()) {
  floaty.requestPermission();
  throw new Error("请先授予悬浮窗权限");
}

const win = floaty.window(
  <frame>
    <text text="system floaty" />
  </frame>
);

无障碍悬浮窗：

if (!floaty.checkAccessibilityPermission()) {
  floaty.requestAccessibilityPermission();
  throw new Error("请先启用无障碍服务");
}

const win = floaty.accessibilityWindow(
  <frame>
    <text text="accessibility floaty" />
  </frame>
);

`floaty.checkPermission()`

作用

检查当前是否已经有悬浮窗权限。

场景	返回值
已有权限	`true`
成功拉起系统设置页	`true`
拉起失败	`false`

场景	返回值
无障碍服务没启用	`false`
无障碍服务已启用，但当前服务对象还没连上	`true`
无障碍服务已启用，且当前已经连上	`true`

参数	类型	说明
`width`	`number`	普通像素值，或 Android 宽度 spec
`height`	`number`	普通像素值，或 Android 高度 spec

值	效果
`true`	正常可点、可交互
`false`	窗口不可触摸，事件会穿透

传法	说明
字符串 id 名称	例如 `"closeBtn"`
数字 id	原生 Android view id 数值

值	含义
`-1`	`MATCH_PARENT`
`-2`	`WRAP_CONTENT`
`> 0`	固定像素