更新记录

2.0.0（2026-04-01）

Android 悬浮窗增强插件

插件简介

面向 Android 场景的高阶悬浮窗增强插件，支持 WebView 自定义内容承载、自由拖拽与吸边停靠、尺寸切换、系统级悬浮、画中画联动及一像素保活能力，适用于工具面板、识别辅助、消息提示与轻量工作台等复杂交互场景。

更新说明

1.0.0

初始版本发布
支持应用内悬浮窗与系统悬浮窗
支持 H5 内容承载与 HTML 字符串直接渲染
支持自由拖拽、吸边拖拽、浮窗球、大小切换
支持向悬浮窗发送数据、注入 JS、注入 CSS
支持网页地址切换、位置调整、尺寸调整
支持画中画与一像素保活

使用前说明

插件类型：API 插件
适用平台：Android
建议使用自定义基座、离线打包或云打包方式验证原生能力
标准调试基座下，涉及原生配置或系统能力的功能可能无法正常生效

权限说明

插件涉及的主要权限如下：

android.permission.SYSTEM_ALERT_WINDOW
android.permission.INTERNET

说明：

SYSTEM_ALERT_WINDOW 用于系统悬浮窗模式
INTERNET 用于加载远程网页内容

基本接入

1. 引入插件

import {
  showH5Window,
  hideWindow,
  checkPermission,
  requestPermission
} from '@/uni_modules/jplayer-floatwindow'

如果你希望保留旧原生插件的回调风格，也可以自行封装一层对象式调用。

2. 检查悬浮窗权限

checkPermission({
  success(res) {
    console.log('checkPermission', res)
  }
})

3. 申请悬浮窗权限

requestPermission({
  success(res) {
    console.log('requestPermission', res)
  }
})

4. 显示默认 H5 悬浮窗

showH5Window({
  mode: 'app',
  url: 'file:///android_asset/floatwindow/demo.html',
  width: 320,
  height: 220,
  x: 18,
  y: 150,
  draggable: true,
  dragMode: 1,
  success(res) {
    console.log('showH5Window', res)
  }
})

5. 使用 HTML 字符串直接渲染

showWindow({
  mode: 'app',
  html: `
    <html>
      <body style="margin:0;background:#0f172a;color:#fff;">
        <div style="padding:20px;">自定义悬浮内容</div>
      </body>
    </html>
  `,
  width: 320,
  height: 220
})

6. 隐藏悬浮窗

hideWindow({
  success(res) {
    console.log('hideWindow', res)
  }
})

常用 API

`checkPermission(options)`

检查系统悬浮窗权限状态。

`requestPermission(options)`

拉起系统悬浮窗授权页面。

`showWindow(options)`

显示悬浮窗，支持 url 或 html 两种内容来源。

常用参数：

mode: app 或 system
url: 网页地址或本地资源地址
html: 直接传入 HTML 字符串
width
height
x
y
draggable
dragMode

`showH5Window(options)`

显示 H5 悬浮窗。未传 url/html 时，将使用插件内置默认内容。

`hideWindow(options)`

隐藏当前悬浮窗。

`showBall(options)`

以小窗模式显示悬浮窗球。

`toggleSize(options)`

切换大窗/小窗状态。

`setMini(options)`

手动指定是否切换到小窗。

`sendToWeb(options)`

向悬浮窗内的 WebView 发送消息。

参数示例：

sendToWeb({
  type: 'callback',
  data: {
    scene: 'ocr',
    text: '识别成功'
  }
})

`sendDataToJs(options)`

sendToWeb 的同义方法，便于旧调用方式迁移。

`injectJavaScript(options)`

向当前悬浮窗 WebView 注入 JS 代码。

`injectCss(options)`

向当前悬浮窗 WebView 注入 CSS 样式。

`openPage(options)`

切换当前悬浮窗加载的网页地址。

openPage({
  url: 'https://m.baidu.com'
})

`setDragMode(options)`

设置拖拽模式。

0：不可拖拽
1：自由拖拽
2：吸边拖拽

`setWindowSize(options)`

修改悬浮窗尺寸。

`setWindowPosition(options)`

修改悬浮窗位置。

`getState(options)`

获取当前悬浮窗状态。

`enterPictureInPicture(options)`

进入画中画模式。

`showOnePxWindow(options)`

显示或隐藏一像素保活页面。

WebView 消息通信

uni 侧向 WebView 发送消息

sendDataToJs({
  type: 'business',
  data: {
    title: '消息标题',
    content: '这里是传入悬浮窗的数据'
  }
})

WebView 侧接收消息

<script>
window.onUniFloatWindowMessage = function(payload) {
  console.log('收到原生消息', payload)
}
</script>

WebView 侧向原生发送消息

<script>
function postToNative() {
  if (window.FloatWindowBridge && window.FloatWindowBridge.postMessage) {
    window.FloatWindowBridge.postMessage('ping', 'from-webview')
  }
}
</script>

uni 侧监听 WebView 回传

onWebMessage((res) => {
  console.log('onWebMessage', res)
})

返回结果说明

常见返回字段如下：

code
message
showing
mini
mode
width
height
x
y
dragMode

调试建议

如果页面按钮点击后无效果，建议先在页面日志中输出当前调用的方法名和参数
如果悬浮窗容器出现但内容为空，优先检查 url/html 是否传入了空值或 null
如果标准基座下调用失败，请改用自定义基座、离线打包或云打包验证
如果远程网页无法正常显示，建议先使用内置默认内容或本地 HTML 字符串排查 WebView 加载链路

注意事项

本插件当前以 Android 平台为主
系统悬浮窗首次使用前必须完成授权
不同 ROM 对系统悬浮、一像素保活、画中画的兼容表现可能存在差异

平台兼容性

uni-app(4.57)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
-	-	-	-	-	-	5.0	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-	-

uni-app x(4.57)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	5.0	-	-	-

Android 悬浮窗增强插件 floatwindow overlay webview android uts

更新记录

2.0.0（2026-04-01）

Android 悬浮窗增强插件

插件简介

更新说明

1.0.0

使用前说明

权限说明

基本接入

1. 引入插件

2. 检查悬浮窗权限

3. 申请悬浮窗权限

4. 显示默认 H5 悬浮窗

5. 使用 HTML 字符串直接渲染

6. 隐藏悬浮窗

常用 API

checkPermission(options)

requestPermission(options)

showWindow(options)

showH5Window(options)

hideWindow(options)

showBall(options)

toggleSize(options)

setMini(options)

sendToWeb(options)

sendDataToJs(options)

injectJavaScript(options)

injectCss(options)

openPage(options)

setDragMode(options)

setWindowSize(options)

setWindowPosition(options)

getState(options)

enterPictureInPicture(options)

showOnePxWindow(options)

WebView 消息通信

uni 侧向 WebView 发送消息

WebView 侧接收消息

WebView 侧向原生发送消息

uni 侧监听 WebView 回传

返回结果说明

调试建议

注意事项

平台兼容性

uni-app(4.57)

uni-app x(4.57)

隐私、权限声明

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

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

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

获取短信列表，获取前N条，监听实时短信，通知验证码，获取短信权限

Android 悬浮窗增强插件

Modal title

`checkPermission(options)`

`requestPermission(options)`

`showWindow(options)`

`showH5Window(options)`

`hideWindow(options)`

`showBall(options)`

`toggleSize(options)`

`setMini(options)`

`sendToWeb(options)`

`sendDataToJs(options)`

`injectJavaScript(options)`

`injectCss(options)`

`openPage(options)`

`setDragMode(options)`

`setWindowSize(options)`

`setWindowPosition(options)`

`getState(options)`

`enterPictureInPicture(options)`

`showOnePxWindow(options)`