更新记录

1.0.18（2026-07-31）

• 修复 HarmonyOS 诊断结果对象使用字面量强转时触发 ArkTS 名义类型编译错误的问题，改为显式具体结果类并保持公开返回结构不变。
• Harmony 真机已验证应用内悬浮窗打开、本地 ArkWeb 内容加载、控制器挂接和关闭链路；Android、iOS 逻辑未改。
• Harmony 原生 UTS 已变化，升级后需要重新构建并安装匹配的 Harmony HAP 或自定义基座。

1.0.17（2026-07-31）

• 强化声网/WebRTC 接入说明：调用 AgoraRTC.getDevices() 或创建音视频轨道前，必须在悬浮窗内容中配置 webMediaPermissions: ['camera', 'microphone']。
• 明确 Android 系统权限弹窗中点击允许不能替代插件的网页媒体白名单，并补充精确 HTTPS Origin、iframe allow 和五步排错清单。
• 优化 uni-app 与 uni-app x 示例界面，按基础开关、尺寸交互、Web 与媒体、JSBridge、PiP、诊断和日志模块紧凑展示。
• 本版本只调整客户文档、示例页面和发布元数据；已使用包含媒体原生能力的自定义基座时，不需要因本次升级重新制作 Android 自定义基座。

1.0.16（2026-07-31）

• 修复 Android WebRTC/声网 Web SDK 创建麦克风轨道时缺少音频模式权限的问题，补充 MODIFY_AUDIO_SETTINGS 清单声明。
• 修复拖拽、点击、内容事件和 H5 消息持续监听回调可能被提前释放的问题。
• 完成 Android 新自定义基座真机回归：百度页面点击、滚动和输入正常，Origin 白名单与 JSBridge 双向连续消息通过。
• 完成声网 Web SDK 摄像头与麦克风轨道真机创建、释放和 H5 → App 结果回传，两次连续测试均通过。
• Android 全局悬浮、尺寸与位置、显隐置顶、权限诊断及 PiP 不支持时的明确降级保持正常。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-float-window

lizhao-float-window 是面向 uni-app / uni-app x 的原生 UTS 悬浮窗与画中画插件。一个插件即可完成应用内悬浮、Android 跨应用全局悬浮、视频系统 PiP、H5 ↔ App 双向通信、自适应全屏、拖拽定位、权限引导和运行诊断。

如果你只需要一个简单悬浮按钮，可以从应用内小窗开始；如果要做客服、直播、业务面板或 H5 交互，再按本文顺序逐步启用增强能力。

功能特色

• 一种 API，多种悬浮形态：支持 Android 全局悬浮，以及 Android、iOS、Harmony 应用内悬浮。
• 内容不受业务页面限制：悬浮窗可承载远程 URL、本地 HTML 和业务 H5 面板。
• 从悬浮球到自适应全屏：支持 small / medium / large / custom / fullscreen，全屏会随横竖屏或窗口尺寸变化自动适配。
• 真实系统画中画：Android、Harmony 可让视频进入系统 PiP；Harmony 还支持网络、本地资源、应用沙箱视频、鉴权头、播放控制和 Home 自动进入。
• H5 ↔ App 安全双向通信：Android WebView 与 Harmony ArkWeb 使用事件消息桥，保留中文、Emoji 和 requestId；远程 H5 使用精确 HTTPS Origin 白名单。
• 远程 H5 媒体采集：Android 可按精确 HTTPS Origin 和资源类型授权摄像头、麦克风，兼容声网 Web SDK 等基于 WebView 媒体采集的页面。
• 交互能力完整：支持拖拽、边缘吸附、位置记忆、坐标管理、显隐、置顶、内容切换和运行时大小切换。
• 权限和故障可诊断：支持 Android 悬浮窗权限检测、系统设置页引导、运行状态和诊断报告，不用让客户盲猜失败原因。
• 平台边界透明：不支持的平台返回明确错误，不伪造成功；业务可先读取能力矩阵再决定是否显示入口。

适用场景

下载与接入

1. 下载插件

在插件市场页面选择“使用 HBuilderX 导入插件”，把插件导入目标项目。也可以下载插件包后，将完整目录放到：

项目根目录/
└─ uni_modules/
   └─ lizhao-float-window/

不要只复制 utssdk，也不要修改插件目录名，否则 import、静态资源和原生配置可能失效。

2. 使用自定义基座

这是 UTS 原生插件。首次安装、版本升级，或插件的 Android/iOS/Harmony 原生文件发生变化后，需要重新制作对应平台的自定义基座或原生包。只更新页面资源、WGT 或 appResource 不能替换已经编译进旧基座的原生逻辑。

如果只使用 Web/小程序降级能力，按平台支持表处理；不支持的能力会返回明确错误。

3. 声网/WebRTC 页面先配置网页媒体权限

声网/WebRTC 必配项： 只要悬浮 WebView 中的页面会调用 await AgoraRTC.getDevices()、创建摄像头轨道或创建麦克风轨道，就必须在本次 openFloatWindow 的 content 中配置 webMediaPermissions。系统权限弹窗中点击“允许”只代表 Android 运行时权限已授予，不能替代插件的网页媒体白名单。

同时获取摄像头和麦克风时，推荐直接使用：

content: {
  type: 'url',
  value: 'https://rtc.example.com/room',
  allowedOrigins: ['https://rtc.example.com'],
  webMediaPermissions: ['camera', 'microphone']
}

• AgoraRTC.getDevices() 默认可能同时触发摄像头和麦克风请求，因此不要只配置其中一项。
• 远程页面必须使用 HTTPS，并把最终页面的精确 Origin 配到 allowedOrigins；这里只写协议、域名和可选端口，不写路径。
• 如果声网页面位于 iframe 中，iframe 还必须配置 allow="camera; microphone"。
• 如果完全不配置 webMediaPermissions，插件会按安全默认值拒绝网页媒体请求，即使用户已经在系统弹窗中允许摄像头和麦克风。

完整代码和排错顺序见下方“远程 H5 使用摄像头和麦克风”。

4. 从插件根目录导入

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

不要直接 import utssdk/index.uts 或某个平台目录。

先选择适合你的接入方式

快速开始：从简单到复杂

第一步：读取当前平台能力

同一份业务可能运行在 Android、iOS、Harmony、Web 或小程序。建议先读取能力矩阵，再决定展示哪些入口：

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

getCapabilities({
  success(res) {
    console.log('当前平台悬浮窗能力', res)
  },
  fail(err) {
    console.log('读取能力失败', err)
  }
})

第二步：打开最简单的应用内悬浮窗

应用内悬浮不要求 Android 系统悬浮窗权限，最适合验证插件是否安装和基座是否匹配：

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

openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'localAsset',
    value: 'static/float-window-demo.html'
  },
  sizePreset: 'small',
  dragEnabled: true,
  edgeSnap: true,
  success(res) {
    console.log('应用内悬浮窗打开成功', res)
  },
  fail(err) {
    console.log('应用内悬浮窗打开失败', err)
  }
})

// 页面离开或业务结束时主动关闭。
// closeFloatWindow({})

第三步：打开 Android 全局悬浮窗

Android 全局悬浮会显示在其他应用上层。先检查权限；未开启时，再由用户点击操作进入系统设置页：

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

checkOverlayPermission({
  success(res) {
    if (!res.granted) {
      // 建议把设置页跳转放在客户明确点击的按钮事件中。
      openOverlayPermissionSettings({})
      return
    }

    openFloatWindow({
      mode: 'overlay',
      content: {
        type: 'url',
        value: 'https://www.dcloud.io'
      },
      sizePreset: 'medium',
      dragEnabled: true,
      edgeSnap: true,
      rememberPosition: true,
      keepInScreen: true,
      success(openRes) {
        console.log('Android 全局悬浮窗打开成功', openRes)
      },
      fail(err) {
        console.log('Android 全局悬浮窗打开失败', err)
      }
    })
  }
})

系统设置页只能由用户完成授权，插件不会静默开启权限。用户返回 App 后应再次调用 checkOverlayPermission，确认 granted=true 再打开全局悬浮窗。

第四步：切换为自适应全屏

自适应全屏已整合为正式的 fullscreen 尺寸预设。客户不需要读取屏幕尺寸或换算平台单位：

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

openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'url',
    value: 'https://www.dcloud.io'
  },
  sizePreset: 'fullscreen',
  success(res) {
    console.log('自适应全屏打开成功', res)
  }
})

fullscreen 表示当前应用的安全可用窗口：Android、iOS、Harmony 会随横竖屏或窗口尺寸变化自动刷新；全屏时位置固定在左上角且不响应拖动。它不是覆盖系统状态栏、导航栏或刘海区域的“物理屏幕全屏”。

进阶使用

自适应全屏

width 和 height 只接受数字，不支持 100%、100vw 或 rpx。自定义尺寸的原生单位因平台而异：

• Android：物理像素 px
• iOS：逻辑点 pt
• Harmony：逻辑单位 vp

客户不需要自行换算这些单位。打开浮窗时使用 fullscreen 预设，插件会读取当前应用可用窗口，并避开系统安全区域：

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

openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'localAsset',
    value: 'static/float-window-demo.html'
  },
  sizePreset: 'fullscreen',
  success(res) {
    console.log('自适应全屏浮窗打开成功', res)
  }
})

// 已打开的浮窗也可以直接切换；改回 medium 等普通预设即可退出全屏。
setFloatWindowSizePreset({
  preset: 'fullscreen',
  success(res) {
    console.log('已切换为自适应全屏', res)
  }
})

fullscreen 表示当前应用可用窗口，不承诺跨应用覆盖状态栏、导航栏或刘海区域。PiP 大小仍由操作系统管理，不受该预设影响。

切换浮窗大小

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 { openFloatWindow, updateFloatWindow } from '@/uni_modules/lizhao-float-window'

// 打开时启用吸附和会话内位置记忆；用户拖动后关闭再打开，会优先恢复上次坐标。
openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'localAsset',
    value: 'static/float-window-demo.html',
    isVideoStream: false
  },
  sizePreset: 'small',
  edgeSnap: true,
  rememberPosition: true,
  keepInScreen: true,
  edgePadding: 16,
  success(res) {
    console.log('增强悬浮窗打开成功', res)
  }
})

// 已打开后也可以动态切换行为配置，适合在设置页里控制用户偏好。
updateFloatWindow({
  edgeSnap: true,
  rememberPosition: true,
  keepInScreen: true,
  edgePadding: 16
})

监听拖拽与点击

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)
  }
})

H5 ↔ App 双向通信

当悬浮内容不仅要展示，还要提交订单、打开业务页、同步播放器状态或接收 App 数据时，可以启用消息桥。推荐先使用随插件提供的本地 H5 验证：

import {
  openFloatWindow,
  onH5Message,
  offH5Message,
  sendMessageToH5
} from '@/uni_modules/lizhao-float-window'

// 先订阅，再打开 H5，避免漏掉页面初始化消息。
onH5Message({
  listener(message) {
    console.log('App 收到 H5 消息', message)
  }
})

openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'localAsset',
    value: 'uni_modules/lizhao-float-window/static/bridge-demo.html',
    bridgeName: 'LizhaoFloatWindow'
  },
  success() {
    sendMessageToH5({
      event: 'appGreeting',
      data: { text: '你好，H5' },
      requestId: 'req-app-001'
    })
  }
})

// 页面卸载时取消监听，避免重复订阅。
// offH5Message({})

H5 侧发送 JSON 字符串，并通过固定事件接收 App 消息：

window.LizhaoFloatWindow.postMessage(JSON.stringify({
  event: 'submitOrder',
  data: { orderNo: 'DEMO-001' },
  requestId: 'req-h5-001'
}))

window.addEventListener('lizhaoFloatWindowMessage', function (event) {
  console.log('H5 收到 App 消息', event.detail)
})

远程 H5 必须使用 HTTPS，并配置精确 Origin，例如 allowedOrigins: ['https://example.com']。不要使用通配符，不要把路径、Token 或账号写入 Origin 白名单。Android 与 Harmony 支持该消息桥；其他平台会返回明确不支持。

远程 H5 使用摄像头和麦克风

声网 Web SDK 最终仍通过 WebView 的网页媒体权限请求获取设备。只在项目 manifest.json 声明权限不够：Android 还需要 WebView 处理媒体请求、校验页面 Origin，并在运行时向用户申请摄像头或麦克风权限。本插件已在 Android 原生层完成这条链路。

如果页面会执行 await AgoraRTC.getDevices()，请直接按下面的完整配置打开悬浮窗。客户实测表明：系统摄像头、麦克风权限已经显示“允许”时，如果缺少 webMediaPermissions: ['camera', 'microphone']，网页设备枚举仍可能失败。

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

openFloatWindow({
  mode: 'inApp',
  content: {
    type: 'url',
    // 替换成你自己的声网 H5 页面，必须为 HTTPS。
    value: 'https://rtc.example.com/room',
    // 这里只写 scheme + host + 可选端口，不能写路径、查询、通配符或 Token。
    allowedOrigins: ['https://rtc.example.com'],
    webMediaPermissions: ['camera', 'microphone']
  },
  success(res) {
    console.log('音视频 H5 已打开', res)
  },
  fail(err) {
    console.log('音视频 H5 打开失败', err)
  }
})

• webMediaPermissions 未配置或为空时，网页摄像头和麦克风请求全部拒绝；按最小权限原则也可以只配置 ['camera'] 或 ['microphone']。
• AgoraRTC.getDevices()、同时创建摄像头和麦克风轨道时，应配置 ['camera', 'microphone']；只使用单一设备时才建议缩小为单项权限。
• allowedOrigins 是正确字段名，不是 allowedOriginsz。https://example.com/ 会规范化为 https://example.com，普通路径、HTTP、通配符、查询或片段会返回配置错误 9015011。
• 媒体采集不要求配置 bridgeName；bridgeName 仅在 H5 还需要与 App 收发业务消息时添加。两项能力共享同一份可信 Origin。
• Android System WebView 不支持消息桥或消息桥运行时注册失败时，插件会继续加载页面并在诊断中记录降级原因；非法 bridgeName 或非法 Origin 仍会明确失败，避免静默放宽安全边界。
• H5 首次真正请求设备时，Android 会显示系统权限弹窗。用户拒绝、页面请求未知资源、Origin 不匹配或页面不是安全上下文时，插件不会伪造成功。
• 页面嵌在 iframe 时，除了插件配置外，还要由父页面为 iframe 增加 allow="camera; microphone"；否则浏览器策略仍可能阻止设备访问。
• 当前只处理 WebView 的摄像头与麦克风媒体请求，不扩展 <input capture> 文件选择、屏幕共享或任意网页权限。
• 修改插件原生文件或权限清单后必须重新制作并安装 Android 自定义基座。旧基座只更新 WGT/appResource 不会获得这项能力。

排错时按以下顺序检查：

1. 本次 openFloatWindow 的 content.webMediaPermissions 是否包含页面实际请求的 camera、microphone。
2. allowedOrigins 是否与跳转后的最终 HTTPS Origin 完全一致。
3. Android 项目权限和当前自定义基座是否已包含摄像头、录音及音频模式权限。
4. 用户是否在系统权限管理中真正允许摄像头和麦克风；部分 Android 定制系统还需检查隐私保护开关。
5. 页面是否处于安全上下文，以及 iframe 是否声明对应的 allow。

视频进入系统画中画

网络 MP4 或 m3u8 可以使用同一入口。调用前建议先通过 getCapabilities 确认当前设备返回 pip: true：

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

enterPictureInPicture({
  content: {
    type: 'url',
    value: 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/wap2appvsnative.mp4',
    isVideoStream: true
  },
  success(res) {
    console.log('进入系统画中画成功', res)
  },
  fail(err) {
    console.log('进入系统画中画失败', err)
  }
})

Android PiP 需要 Android 8.0 及以上，并且设备和宿主 Activity 都支持画中画。Harmony 使用系统 PiPWindow、XComponent Surface 和 AVPlayer，还支持本地 MP4、鉴权请求头、播放控制和 Home 自动进入。普通网页或非视频内容不会伪装成 PiP 成功。

Harmony 本地视频

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

// 播放随应用发布的 MP4；路径由 DCloud 运行时解析为 Harmony rawfile 资源。
enterPictureInPicture({
  content: {
    type: 'localAsset',
    value: 'uni_modules/lizhao-float-window/static/pip-test.mp4',
    isVideoStream: true
  },
  success(res) {
    console.log('本地资源进入画中画成功', res)
  },
  fail(err) {
    console.log('本地资源进入画中画失败', err)
  }
})

// 下载完成后的 tempFilePath 位于应用沙箱，可直接作为 localFile 播放。
uni.downloadFile({
  url: 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/wap2appvsnative.mp4',
  success(downloadRes) {
    if (downloadRes.statusCode !== 200) return
    enterPictureInPicture({
      content: {
        type: 'localFile',
        value: downloadRes.tempFilePath,
        isVideoStream: true
      },
      fail(err) {
        console.log('沙箱视频进入画中画失败', err)
      }
    })
  }
})

localFile 仅支持当前应用 files/cache/temp 沙箱内的普通 MP4 文件，不接受任意系统绝对路径、目录、符号链接或跨应用文件。随包视频应优先使用 localAsset。

Harmony 鉴权网络媒体

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

// 请求头只交给原生 MediaSource，不会写入插件日志、事件或播放状态。
enterPictureInPicture({
  content: {
    type: 'url',
    value: 'https://example.com/protected.mp4',
    headers: {
      Authorization: 'Bearer <由业务安全获取的临时凭据>'
    },
    isVideoStream: true
  },
  fail(err) {
    console.log('鉴权媒体进入画中画失败', err)
  }
})

不要把长期 Token、密钥或生产凭据写死在页面、README 或仓库中。业务应从安全服务动态获取短期凭据，并在失效后重新请求。

uni-app 页面可直接传普通对象，uni-app x 可传 UTSJSONObject；插件会在 Harmony 层统一读取并校验请求头。网络媒体首帧受地址、CDN 和设备网络影响，随插件提供的两套示例会等待最多 120 秒再解除按钮锁定，但插件仍以真实 success / fail / complete 回调作为最终结果。

Home 自动进入系统 PiP

import {
  preparePictureInPicture,
  cancelPictureInPicturePreparation
} from '@/uni_modules/lizhao-float-window'

// 先准备媒体但不立即弹出 PiP；用户按 Home 后由 Harmony 系统自动进入。
preparePictureInPicture({
  content: {
    type: 'localAsset',
    value: 'uni_modules/lizhao-float-window/static/pip-test.mp4',
    isVideoStream: true
  },
  startPositionMs: 1000,
  loop: true,
  progressIntervalMs: 500,
  autoEnterOnHome: true,
  success(state) {
    console.log('PiP 已准备，可按 Home 验证', state)
  },
  fail(err) {
    console.log('准备 PiP 失败', err)
  }
})

// 页面离开或业务取消时，释放尚未进入 PiP 的准备态。
cancelPictureInPicturePreparation({
  success(state) {
    console.log('已取消 PiP 准备', state)
  }
})

播放控制、跳转和状态查询

import {
  playPictureInPicture,
  pausePictureInPicture,
  seekPictureInPicture,
  getPictureInPicturePlaybackState,
  exitPictureInPicture
} from '@/uni_modules/lizhao-float-window'

// 恢复播放。
playPictureInPicture({ success: state => console.log('播放状态', state) })

// 暂停播放。
pausePictureInPicture({ success: state => console.log('暂停状态', state) })

// 点播媒体跳转到 10 秒；直播流 seekable=false 时会返回明确失败。
seekPictureInPicture({
  positionMs: 10000,
  success: state => console.log('跳转后状态', state),
  fail: err => console.log('跳转失败', err)
})

// 查询统一播放快照，返回值不包含完整媒体地址或请求头。
getPictureInPicturePlaybackState({
  success: state => console.log('当前播放状态', state)
})

// 退出时统一释放播放器、PiPController、Surface 和媒体文件描述符。
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 列表

sendMessageToH5(options)

说明 向已启用桥、已完成页面加载且仍处于白名单范围的 H5 页面发送事件消息。单条序列化后消息最大 256 KB。

支持平台 App-Android / App-Harmony；其他平台返回明确不支持。

参数

返回值

onH5Message(options)

说明 订阅 H5 通过 window.<bridgeName>.postMessage(JSON字符串) 发来的合法业务消息。重复订阅会替换旧监听器。

参数

监听事件包含 event、data、requestId、sourceOrigin、isMainFrame 和 timestamp。Harmony 的 isMainFrame 为 null。

offH5Message(options)

说明 取消 H5 业务消息监听；未监听时重复调用也会安全完成。

参数

preparePictureInPicture(options)

说明 在 Harmony 预准备媒体和 PiPController。autoEnterOnHome 为 true 时，用户按 Home 后由系统自动进入 PiP；该方法本身不会立即弹出 PiP。

支持平台 App-Harmony；Android、iOS、Web 和小程序返回明确不支持。

参数

返回值 无同步返回值；success 返回 PictureInPicturePlaybackState。

cancelPictureInPicturePreparation(options)

说明 取消尚未进入系统 PiP 的准备态并释放媒体资源。PiP 已活动时应调用 exitPictureInPicture。

支持平台 App-Harmony；其他平台返回明确不支持。

参数

返回值 无同步返回值；success 返回 PictureInPicturePlaybackState。

playPictureInPicture(options)

说明 播放或恢复已经准备的 Harmony PiP 媒体。

参数

返回值 无同步返回值；success 返回 PictureInPicturePlaybackState。仅 App-Harmony 支持真实控制。

pausePictureInPicture(options)

说明 暂停已经准备的 Harmony PiP 媒体。

参数

返回值 无同步返回值；success 返回 PictureInPicturePlaybackState。仅 App-Harmony 支持真实控制。

seekPictureInPicture(options)

说明 跳转 Harmony PiP 点播媒体。直播流或不可跳转媒体会通过 fail 返回明确错误。

参数

返回值 无同步返回值；success 返回 PictureInPicturePlaybackState。仅 App-Harmony 支持真实控制。

getPictureInPicturePlaybackState(options)

说明 获取统一的 Harmony PiP 播放快照。结果不会包含完整媒体 URL、请求头或本地绝对路径。

参数

返回值

openFloatWindow(options)

说明 打开悬浮窗。Android 可使用 overlay 全局悬浮或 inApp 应用内悬浮；Harmony 支持 inApp 应用内浮窗，以及网络、本地资源和应用沙箱 MP4 的 pip，overlay 返回明确受限原因；iOS 支持 inApp 和最佳努力 PiP。

支持平台 Android / iOS / Harmony

参数

返回值

getCapabilities(options)

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

参数

返回值

checkOverlayPermission(options)

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

参数

返回值

getFloatWindowState(options)

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

参数

返回值

getFloatWindowDiagnostics(options)

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

参数

返回值

通用参数类型

FloatWindowContent

FloatWindowPosition

FloatWindowSize

内容事件

Harmony ArkWeb 内容事件

Harmony 系统 PiP 事件

错误码

平台支持

权限与自定义基座

Android

插件声明了以下权限：

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

Harmony

Harmony 应用内浮窗、ArkWeb、H5 双向通信与系统 PiP 都依赖原生 UTS/ETS。首次接入或升级原生实现后，必须重新构建并安装 Harmony 原生包；只替换 appResource/wgt 无法更新 ArkWeb WebMessagePort 桥、PiP 或媒体实现。

iOS

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

注意事项

• Android 全局悬浮窗需要用户在系统设置中授权；未授权时会返回 9015003。
• PiP 只建议用于视频流场景，普通网页或业务卡片请使用悬浮窗模式。
• Android 与 Harmony 的远程 H5 桥只接受精确 HTTPS Origin，禁止使用通配符；页面离开白名单后桥会立即失效。
• 单条 H5 ↔ App 消息最大 256 KB，消息必须是带非空 event 的 JSON 对象；插件不提供任意 JavaScript 执行 API。
• iOS 受系统策略限制，不支持跨应用全局悬浮，发布说明中请勿承诺该能力。
• Harmony 已支持应用内浮窗、ArkWeb URL/本地 HTML 和网络视频系统 PiP；远程内容需要 ohos.permission.INTERNET，ArkWeb 加载结果应监听 pageEnd/pageError，PiP 应先调用 getCapabilities 判断设备能力；跨应用全局悬浮仍不支持。

作者系列UTS插件

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