更新记录

1.0.3（2026-04-14）

更新插件名字报错

1.0.2（2026-04-14）

新增体验版本

1.0.1（2026-04-14）

更新引用命名和路径

平台兼容性

uni-app x(5.06)

其他

floating-plus-hzs

Android 系统级全局悬浮窗插件。核心能力：

• 系统级浮窗（使用 TYPE_APPLICATION_OVERLAY，可在退出 App 后保持显示）
• WebView 自定义内容，支持加载本地 HTML 或远程 URL
• 双向 JS 通信（H5 ↔ uni-app）
• 可拖拽（智能触摸拦截，WebView 内点击事件正常传递）
• 九宫格定位、绝对坐标定位、拖拽边界限制
• 一像素保活 Activity（防止后台被系统杀死）
• 内置 ASR（语音识别）WebSocket 客户端，可对接语音识别服务

平台支持

权限

AndroidManifest.xml 中已自动声明，无需手动添加：

<!-- 系统级悬浮窗权限（Android 6.0+ 需动态申请） -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<!-- 前台 Service 权限（后台保活） -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Android 6.0+：showPattern >= 1 时需要用户在「设置 → 应用 → 允许显示在其他应用上层」手动授权，使用 requestPermission 可自动跳转该设置页。

快速开始

uni-app x（uvue）

import { FloatWindow } from "@/uni_modules/floating-plus-hzs";

const fw = new FloatWindow();

// 1. 检查 / 申请权限
if (!fw.checkPermission()) {
  fw.requestPermission((granted) => {
    if (granted) showFloat();
  });
} else {
  showFloat();
}

function showFloat() {
  // 加载内置卡片模板
  fw.loadUrl("file:///android_asset/uni_modules/floating-plus-hzs/float_window.html");
  // 固定宽高（设计稿 px → Android px）
  fw.setFixedWidthHeight(true, fw.convertHtmlPxToAndroidPx(300), fw.convertHtmlPxToAndroidPx(200));
  // 居中显示
  fw.setGravity(4);
  // 允许拖拽
  fw.setDragEnable(true);
  // 始终显示（含退出 App 后）
  fw.setShowPattern(3);
  // 监听 H5 消息（type=0 为内置关闭按钮）
  fw.onListenerWebData((type, data) => {
    if (type === 0) fw.dismiss();
  });
  fw.createAndShow();
}

uni-app（vue2/vue3）

import { FloatWindow } from "@/uni_modules/floating-plus-hzs";
const fw = new FloatWindow();
// 调用方式同上，去掉 TypeScript 类型注解即可

API 文档

权限管理

checkPermission(): boolean

检查是否已拥有悬浮窗权限（SYSTEM_ALERT_WINDOW）。Android 6.0 以下始终返回 true。

requestPermission(callback: (granted: boolean) => void): void

跳转系统「允许显示在其他应用上层」设置页，用户返回后回调授权结果。若已有权限则直接回调 true。

内容加载

loadUrl(url: string): void

加载 WebView 内容。支持：

• http:// / https:// 远程地址
• file:///android_asset/uni_modules/floating-plus-hzs/xxx.html 本地 Assets

浮窗创建后也可调用，实时更新内容。

尺寸与位置

setFixedWidthHeight(fixed: boolean, width: number, height: number): void

设置是否固定宽高（Android px）。fixed=false 时使用 WRAP_CONTENT。

setLocation(x: number, y: number): void

设置浮窗绝对坐标（Android px），与 setGravity 互斥，后调用的生效。

setGravity(gravity: FloatWindowGravity): void

九宫格定位，gravity 取值 0–8：

setGravityOffset(gravity: FloatWindowGravity, offsetX: number, offsetY: number): void

九宫格定位 + 额外偏移（Android px）。

setBorder(left: number, top: number, right: number, bottom: number): void

拖拽边界限制（Android px）。拖拽时超出边界会自动截断。默认值为 0 / 0 / -1 / -1（-1 表示不限）。

显示行为

setShowPattern(pattern: FloatWindowShowPattern): void

setDragEnable(enable: boolean): void

是否允许拖拽，默认 true。浮窗创建后调用同样生效。
底层使用 DragFrameLayout 实现智能触摸拦截：移动距离 < 15px 时事件透传给 WebView，超过后才进入拖拽模式。

setImmersionStatusBar(enable: boolean): void

设为 true 时浮窗可穿透状态栏区域显示（FLAG_LAYOUT_NO_LIMITS）。

setSidePattern(pattern: number): void

边缘吸附效果（0–14），具体表现效果请自行测试。

生命周期

createAndShow(): void

创建浮窗并显示。同一实例只能创建一次，之后调用无效。

show(): void

显示浮窗（已创建但被 hide() 隐藏时使用）。若尚未创建则等同于 createAndShow()。

hide(): void

隐藏浮窗（GONE），不销毁 WebView。

dismiss(): void

销毁浮窗并释放 WebView 资源，之后需重新 createAndShow()。

isShow(): boolean

返回浮窗当前是否处于显示状态。

updateWindow(): void

将调用 setFixedWidthHeight / setLocation / setGravity 等修改的参数应用到已显示的窗口。

H5 双向通信

onListenerWebData(callback: (type: number, data: string) => void): void

注册回调，监听 H5 通过 uniapp.sendDataToUni(type, data) 发来的消息。

sendDataToJs(type: number, data: string): void

向 WebView 内的 H5 发送消息，H5 需实现全局函数 dataFromUniapp(type, data)。

onSetWebViewConsole(callback: (msg: string) => void): void

拦截 WebView 的 console.log 等输出，用于调试。

ASR 语音识别（WebSocket）

插件内置了与语音识别服务对接的 WebSocket 客户端，支持断线自动重连（退避重连，最长 30 秒）和心跳保活（60 秒超时触发重连）。

setAsrUrl(url: string): void

设置 ASR WebSocket 服务地址，如 ws://192.168.1.100:8080/asr。

startAsr(): void

连接 ASR 服务并开始会话。需先调用 setAsrUrl。

stopAsr(): void

向服务端发送 {"cmd":"stop"} 指令，500ms 后关闭连接。

sendPcmToAsr(buffer: Int8Array, size: number): void

发送 PCM 音频数据到 ASR 服务（配合录音插件使用）。

onAsrResult(callback: (type: string, text: string) => void): void

注册 ASR 结果回调：

工具方法

convertHtmlPxToAndroidPx(htmlPx: number): number

将设计稿 px 转换为 Android 实际像素（基于屏幕密度 density）。
公式：result = htmlPx × density + 0.5

showOnePxWindow(show: boolean): void

显示/隐藏一像素保活窗口（OnePxActivity）。屏幕关闭后显示 1×1px 的透明 Activity，防止应用被系统杀死。

getPkgName(): string

获取当前应用包名。

startApp(pkgName: string): void

通过包名启动其他应用（目标应用需存在且可启动，否则静默失败）。

H5 与 uni-app 通信协议

H5 → uni-app

// 在 H5 中调用（uniapp 对象由插件注入）
uniapp.sendDataToUni(type, data); // type: 整数，data: 字符串

uni-app → H5

fw.sendDataToJs(1, "Hello from uni-app");

H5 必须实现全局函数：

function dataFromUniapp(type, data) {
  console.log("收到消息:", type, data);
}

内置 HTML 模板

float_window.html — 卡片浮窗（默认）

渐变色卡片，带标题、副标题和关闭按钮。

内置消息协议：

fw.loadUrl("file:///android_asset/uni_modules/floating-plus-hzs/float_window.html");
// 更新标题
fw.sendDataToJs(1, "新标题");
fw.sendDataToJs(2, "新副标题");

float_mic.html — 麦克风悬浮球

圆形悬浮球，长按（600ms）开始录音，松开停止，录音中有脉冲动画。

内置消息协议：

fw.loadUrl("file:///android_asset/uni_modules/floating-plus-hzs/float_mic.html");
fw.onListenerWebData((type, data) => {
  if (type === 10) {
    // 开始录音，配合 sendPcmToAsr 发送音频数据
  } else if (type === 11) {
    // 停止录音
    fw.stopAsr();
  }
});

错误码

注意事项

1. 需要打自定义基座后才能测试系统级浮窗（showPattern >= 1）。标准基座只能测试 showPattern = 0。
2. showPattern = 0 使用 TYPE_APPLICATION，无需权限，但浮窗随 Activity 销毁而消失。
3. 调用顺序：先配置（loadUrl、setGravity 等），最后调用 createAndShow()。配置在创建后调用时需额外调用 updateWindow() 生效（loadUrl、setDragEnable 除外，它们会立即生效）。
4. dismiss() 后 WebView 已销毁，如需重新显示须重新调用 createAndShow()。
5. iOS 平台所有 API 均为空实现，不会报错但无任何效果。

开发参考

• UTS 语法
• UTS API 插件开发
• UTS 标准模式组件
• Hello UTS