更新记录

1.0.0（2026-06-18）

• 首版发布 lizhao-float-window 纯 UTS 悬浮窗与画中画 API 插件。
• Android 支持全局悬浮窗 overlay 与应用内悬浮窗 inApp。
• Android 支持 WebView 自定义内容，可加载远程 URL 与本地 HTML。
• Android 支持拖拽、显示/隐藏、置顶、关闭、坐标查询、坐标设置、预设尺寸和自定义尺寸。
• Android 支持视频流场景进入画中画，非视频内容会返回明确错误。
• Android 支持悬浮窗权限检查、权限设置页引导、运行态快照和诊断报告。
• iOS 支持应用内轻量浮窗和最佳努力 PiP，并明确不支持跨应用全局悬浮。
• iOS 首发已内置 FloatWindowIosViewBridge 兼容处理，收口 CGFloat 坐标读取、可空 UIKit 挂载/置顶和 ?uts-proxy 导出声明问题。
• Harmony、Web、微信小程序、支付宝小程序提供能力矩阵与统一错误语义。
• 提供标准 API 与常用兼容别名：open / close / show / hide / setPosition / getPosition / setContent / setDragEnable / toFront。
• 监听 API 支持不传 options 进行清理，避免客户在页面卸载时因省略参数触发桥接空参数异常。
• 补充从简单到复杂的 README 接入文档，覆盖最小示例、常见增强、API 表、参数表、平台边界、权限与自定义基座说明。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-float-window

lizhao-float-window 是一个面向 uni-app / uni-app x 的纯 UTS 悬浮窗与画中画 API 插件。它把 Android 全局悬浮窗、应用内悬浮窗、WebView 自定义内容、拖拽、大小切换、坐标管理和视频画中画入口封装成统一 API，适合直播小窗、客服浮窗、工具面板、业务公告、悬浮按钮和本地 HTML 面板等场景。

功能特色

• Android 支持全局悬浮窗与应用内悬浮窗，可加载远程 URL 或本地 HTML。
• 支持拖拽、显示/隐藏、置顶、关闭、坐标查询、坐标设置和大小切换。
• 支持 small / medium / large / custom 四类尺寸方案，便于从悬浮球扩展到内容卡片。
• 支持视频流场景进入 Android 画中画模式，普通内容会返回明确错误，避免伪成功。
• 支持 Android 悬浮窗权限检查、权限设置页引导、运行状态查询和诊断报告，便于客户接入和售后定位。
• iOS 提供应用内轻量浮窗与最佳努力 PiP 能力，并明确说明系统不支持跨应用全局悬浮。
• Harmony、Web、微信小程序、支付宝小程序提供能力矩阵和统一错误语义，方便业务做多端兜底。

适用场景

接入前先看

最小可运行示例

1. 读取能力矩阵

import { getCapabilities } from '@/uni_modules/lizhao-float-window'

// 先读取平台能力，业务可据此决定是否展示悬浮窗入口。
getCapabilities({
  success(res) {
    console.log('悬浮窗能力矩阵', res)
  },
  fail(err) {
    console.log('读取能力失败', err)
  }
})

2. 打开 Android 全局悬浮窗

import { openFloatWindow } from '@/uni_modules/lizhao-float-window'

// overlay 是 Android 全局悬浮窗模式，需要系统悬浮窗权限。
openFloatWindow({
  mode: 'overlay',
  content: {
    type: 'url',
    value: 'https://www.dcloud.io',
    isVideoStream: false
  },
  sizePreset: 'medium',
  dragEnabled: true,
  success(res) {
    console.log('打开全局悬浮窗成功', res)
  },
  fail(err) {
    console.log('打开全局悬浮窗失败', err)
  }
})

3. 打开应用内悬浮窗

import { open } from '@/uni_modules/lizhao-float-window'

// inApp 是应用内悬浮模式，适合工具面板、活动提示、客服入口等场景。
open({
  mode: 'inApp',
  content: {
    type: 'localAsset',
    value: 'static/float-window-demo.html',
    isVideoStream: false
  },
  size: {
    width: 360,
    height: 220
  },
  dragEnabled: true,
  success(res) {
    console.log('打开应用内悬浮窗成功', res)
  },
  fail(err) {
    console.log('打开应用内悬浮窗失败', err)
  }
})

常见增强示例

切换浮窗大小

import { setFloatWindowSizePreset, setFloatWindowSize } from '@/uni_modules/lizhao-float-window'

// 使用预设尺寸快速切换为大窗。
setFloatWindowSizePreset({
  preset: 'large',
  success(res) {
    console.log('切换为 large 成功', res)
  }
})

// 使用 custom 尺寸适配自己的业务面板。
setFloatWindowSize({
  size: {
    width: 300,
    height: 180
  },
  success(res) {
    console.log('切换自定义尺寸成功', res)
  }
})

移动与查询位置

import { setPosition, getPosition } from '@/uni_modules/lizhao-float-window'

// 将悬浮窗移动到左上方业务安全区域。
setPosition({
  position: {
    x: 20,
    y: 120
  },
  success(res) {
    console.log('移动悬浮窗成功', res)
  }
})

// 查询当前位置，适合保存用户拖拽后的坐标。
getPosition({
  success(res) {
    console.log('当前悬浮窗坐标', res)
  }
})

监听拖拽与点击

import { onMove, onClick, offMove, offClick } from '@/uni_modules/lizhao-float-window'

// 监听拖拽坐标，业务可用于位置记忆或吸附逻辑。
onMove({
  listener(event) {
    console.log('悬浮窗移动', event.x, event.y)
  }
})

// 监听悬浮窗点击，适合打开业务页或展开面板。
onClick({
  listener(event) {
    console.log('悬浮窗点击', event)
  }
})

// 页面卸载时建议主动取消监听。
offMove({})
offClick({})

动态切换内容

import { setContent } from '@/uni_modules/lizhao-float-window'

// 将悬浮窗内容切换为本地 HTML。
setContent({
  content: {
    type: 'localAsset',
    value: 'static/float-window-demo.html',
    isVideoStream: false
  },
  success(res) {
    console.log('切换本地内容成功', res)
  }
})

视频流进入画中画

import { enterPictureInPicture, exitPictureInPicture } from '@/uni_modules/lizhao-float-window'

// PiP 只面向视频流场景，普通网页内容会返回明确错误。
enterPictureInPicture({
  content: {
    type: 'url',
    value: 'https://example.com/live.m3u8',
    isVideoStream: true
  },
  success(res) {
    console.log('进入画中画成功', res)
  },
  fail(err) {
    console.log('进入画中画失败', err)
  }
})

// 需要恢复主应用时调用退出逻辑。
exitPictureInPicture({
  success(res) {
    console.log('退出画中画成功', res)
  }
})

权限与诊断

import {
  checkOverlayPermission,
  openOverlayPermissionSettings,
  getFloatWindowState,
  getFloatWindowDiagnostics
} from '@/uni_modules/lizhao-float-window'

// Android 全局悬浮前建议先检查权限，未授权时再引导用户打开设置页。
checkOverlayPermission({
  success(res) {
    console.log('悬浮窗权限状态', res)
    if (res.requiresOverlayPermission && !res.granted && res.canOpenSettings) {
      openOverlayPermissionSettings({})
    }
  }
})

// 查询当前运行态，适合保存位置或判断是否需要重复打开。
getFloatWindowState({
  success(res) {
    console.log('悬浮窗运行状态', res)
  }
})

// 导出诊断报告，适合售后排查权限、WebView、窗口附着和监听器状态。
getFloatWindowDiagnostics({
  success(res) {
    console.log('悬浮窗诊断报告', res)
  }
})

完整示例

API 列表

openFloatWindow(options)

说明 打开悬浮窗。Android 可使用 overlay 全局悬浮或 inApp 应用内悬浮；iOS 仅支持 inApp 和最佳努力 PiP。

支持平台 Android / iOS

参数

返回值

getCapabilities(options)

说明 获取当前平台支持情况。建议业务在展示入口前先调用该 API。

参数

返回值

checkOverlayPermission(options)

说明 检查 Android 系统悬浮窗权限。非 Android 平台会返回明确平台边界，业务可据此隐藏全局悬浮入口。

参数

返回值

getFloatWindowState(options)

说明 获取当前悬浮窗运行态快照，适合判断是否已打开、是否可见、当前尺寸和坐标。

参数

返回值

getFloatWindowDiagnostics(options)

说明 获取运行诊断报告，便于客户接入、插件市场演示和售后排查。

参数

返回值

通用参数类型

FloatWindowContent

FloatWindowPosition

FloatWindowSize

平台支持

错误码

权限与自定义基座

Android

插件声明了以下权限：

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.INTERNET" />

iOS

iOS 系统不允许普通应用创建跨应用全局悬浮窗。本插件首版提供应用内轻量浮窗和最佳努力 PiP，不承诺跨应用悬浮。

注意事项

• Android 全局悬浮窗需要用户在系统设置中授权；未授权时会返回 9015003。
• PiP 只建议用于视频流场景，普通网页或业务卡片请使用悬浮窗模式。
• 当前 Android 自定义内容使用 WebView 承载，适合远程运营页和本地 HTML；后续版本计划补充原生悬浮球和 JSBridge 增强。
• iOS 受系统策略限制，不支持跨应用全局悬浮，发布说明中请勿承诺该能力。
• Harmony/Web/小程序首版以能力矩阵和明确错误为主，业务应先调用 getCapabilities 做入口控制。

版本规划

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。