更新记录

1.1.0（2026-05-08）

1.去除编译时候的警告提示

1.0.0（2026-05-07）

1.实现悬浮窗 2.可以自由拖拽 3.支持html 4.自动吸附左右两边 5.支持点击返回指定目标页面

平台兼容性

uni-app(4.25)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ √ - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

其他

多语言 暗黑模式 宽屏模式
× × √

zf-floating-window

Android 系统悬浮窗 UTS 插件，适用于 uni-app 的 App-Android 场景。

Demo 下载体验

  • APK 下载链接：https://env-00jy62hjm7re.normal.cloudstatic.cn/__UNI__DEBC854__20260507184103.apk?expire_at=1778207006&er_sign=1c8604d7a591331457c69e5b7b46fdcd
  • 手机扫码下载体验：

Demo 下载二维码

支持能力：

  • 检查悬浮窗权限
  • 跳转系统授权页
  • 显示/更新/隐藏系统悬浮窗
  • 支持原生按钮悬浮窗
  • 支持 WebView / HTML 悬浮窗
  • 支持拖动、吸边
  • 点击悬浮窗回到应用
  • 回到应用后跳转指定页面
  • 可扩展视频悬浮按钮、HTML 内容悬浮层

注意事项：

  • 当前主要面向 uni-app 的 App-Android 项目
  • H5、小程序、iOS、Harmony 当前不支持
  • SYSTEM_ALERT_WINDOW 需要用户手动授权
  • WebView 视频悬浮层建议真机测试

兼容说明

  • 运行平台：App-Android
  • 最低 HBuilderX 版本：4.25
  • 插件类型：UTS 原生 API 插件

需要的系统权限

本插件当前使用到以下 Android 权限：

  • android.permission.SYSTEM_ALERT_WINDOW
  • android.permission.FOREGROUND_SERVICE
  • android.permission.REORDER_TASKS

说明：

  • SYSTEM_ALERT_WINDOW：显示系统级悬浮窗
  • FOREGROUND_SERVICE：以前台服务承载悬浮窗
  • REORDER_TASKS：辅助应用任务切回前台

安装方式

将插件安装到项目的 uni_modules/zf-floating-window 目录后，在 manifest.json 中确认 Android 权限配置已存在。

如果你直接使用本插件源码，建议完整重新编译一次自定义基座后再测试原生能力。

对外接口

插件入口：

import {
  hasOverlayPermission,
  openOverlayPermissionPage,
  showFloatingWindow,
  updateFloatingWindow,
  hideFloatingWindow,
  isFloatingWindowShowing,
  getFloatingWindowState,
  consumePendingRoute
} from '@/uni_modules/zf-floating-window'

hasOverlayPermission()

检查当前是否已经获得系统悬浮窗权限。

const granted = hasOverlayPermission()

openOverlayPermissionPage()

打开系统悬浮窗授权页。

openOverlayPermissionPage()

showFloatingWindow(options)

显示悬浮窗。

updateFloatingWindow(options)

更新已显示悬浮窗的配置。

hideFloatingWindow()

隐藏悬浮窗。

isFloatingWindowShowing()

查询悬浮窗当前是否显示。

getFloatingWindowState()

同时获取权限状态与显示状态。

consumePendingRoute()

消费一次由悬浮窗点击后回传的待跳转页面信息。

FloatingWindowOptions

type FloatingWindowOptions = {
  routePath?: string
  openType?: string
  mode?: string
  label?: string
  x?: number
  y?: number
  size?: number
  width?: number
  height?: number
  textColor?: string
  backgroundColor?: string
  htmlContent?: string
  htmlUrl?: string
  draggable?: boolean
  autoSnapToEdge?: boolean
}

字段说明：

  • routePath：点击悬浮窗后要打开的页面路径
  • openType：页面打开方式，可选 navigateTo / redirectTo / reLaunch / switchTab
  • mode：悬浮窗模式，可选 native / webview
  • label：标题或按钮文案
  • x / y：初始显示位置，单位近似 dp
  • size：原生按钮模式下的尺寸
  • width / height：WebView 模式下的宽高
  • textColor：文本颜色
  • backgroundColor：背景色
  • htmlContent：直接传入 HTML 字符串
  • htmlUrl：WebView 直接加载的地址，优先级高于 htmlContent
  • draggable：是否允许拖动
  • autoSnapToEdge：松手后是否自动吸边

原生按钮模式示例

showFloatingWindow({
  routePath: '/pages/overlay-target/overlay-target?from=overlay&scene=blue',
  openType: 'navigateTo',
  mode: 'native',
  label: '悬浮',
  x: 24,
  y: 180,
  size: 76,
  textColor: '#FFF8E7',
  backgroundColor: '#1F3A5F',
  draggable: true,
  autoSnapToEdge: true
})

WebView / HTML 悬浮窗示例

showFloatingWindow({
  routePath: '/pages/overlay-target/overlay-target?from=overlay&scene=webview',
  openType: 'navigateTo',
  mode: 'webview',
  label: 'HTML窗',
  x: 20,
  y: 120,
  width: 260,
  height: 300,
  textColor: '#FFF8E7',
  backgroundColor: '#1F3A5F',
  htmlContent: '<html><body><h3>自定义 HTML</h3><p>这里是悬浮内容</p></body></html>',
  draggable: true,
  autoSnapToEdge: true
})

如果你希望直接加载网页：

showFloatingWindow({
  routePath: '/pages/overlay-target/overlay-target?from=overlay&scene=url',
  openType: 'navigateTo',
  mode: 'webview',
  label: '网页窗',
  x: 16,
  y: 100,
  width: 300,
  height: 360,
  htmlUrl: 'https://example.com',
  draggable: true,
  autoSnapToEdge: true
})

视频悬浮按钮示例

如果你要做悬浮视频按钮，可以把一个视频控制 HTML 塞进 htmlContent，例如：

showFloatingWindow({
  routePath: '/pages/overlay-target/overlay-target?from=overlay&scene=video',
  openType: 'navigateTo',
  mode: 'webview',
  label: '视频悬浮',
  x: 16,
  y: 110,
  width: 280,
  height: 356,
  textColor: '#FFF8E7',
  backgroundColor: '#17304C',
  htmlContent: '<html>...</html>',
  draggable: true,
  autoSnapToEdge: true
})

你也可以在 HTML 中接入如下视频地址：

https://play.hhuus.com/play/dNkL6BKe/index.m3u8

如果 WebView 对 m3u8 原生支持不足，可在 HTML 中引入 hls.js。

点击悬浮窗跳转指定页面

推荐做法：

  1. 悬浮窗点击后由原生层回到应用
  2. 原生层缓存待跳转路由
  3. 应用前台页面在 onShow 中消费待跳转路由并执行页面跳转

本插件已经提供 consumePendingRoute() 用于消费这类信息。

demo 页面说明

当前 demo 页面中包含以下演示入口：

  • 检查权限
  • 前往授权
  • 显示悬浮窗
  • 更新悬浮窗
  • 视频悬浮
  • 隐藏悬浮窗

其中：

  • 第一组预设为 WebView / HTML 悬浮窗演示
  • “视频悬浮”按钮演示 WebView 视频悬浮窗的用法

使用建议

  • 涉及原生 Service、Activity、AndroidManifest.xml 变更时，建议完整重建自定义基座
  • WebView 模式下如需加载外链资源，请确认设备网络可访问
  • m3u8 视频建议真机验证
  • 上架生产环境前，请自行检查 ROM 兼容性和权限引导文案

已知限制

  • 当前主要面向 uni-app App-Android
  • uni-app x、nvue、iOS、Harmony 暂未完整验证
  • WebView 模式内容复杂时，拖动区域建议限制在标题栏，不要直接覆盖整个网页内容区

更新建议

你可以继续扩展：

  • 悬浮窗关闭按钮
  • 多悬浮入口
  • 悬浮视频最小化/展开切换
  • WebView 与页面 JS 通信
  • 指定业务页面参数跳转

隐私、权限声明

1. 本插件需要申请的系统权限列表：

android.permission.SYSTEM_ALERT_WINDOW android.permission.FOREGROUND_SERVICE android.permission.REORDER_TASKS

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉
加载更多...