更新记录

1.0.0（2026-05-18）

插件发布

平台兼容性

uni-app(4.76)

mj-uts-win-pip

UTS 悬浮窗 / PiP 网页窗口插件。

mj-uts-win-pip 是一个适用于 uni-app 的原生 UTS 插件：

• Android 支持悬浮网页窗口显示
• iOS 支持 Picture in Picture 网页小窗显示

适用于网页悬浮播放器、活动浮窗、助手小窗、应用内悬浮入口等场景。

插件简介

在很多移动应用场景里，开发者需要把一个网页内容以更轻量、更高可见性的方式展示给用户，例如悬浮播放器、悬浮活动页、全局客服入口、应用内工具球、画中画预览窗口等。

mj-uts-win-pip 针对这类需求，封装了 Android 与 iOS 两端原生窗口能力：

• Android 侧提供网页悬浮窗能力，可控制窗口尺寸、显示位置，并支持拖拽移动
• iOS 侧提供基于系统 Picture in Picture 的网页小窗能力，适合需要小窗展示的内容场景
• 使用方式保持简单，前端通过统一实例调用即可按平台分发能力

如果你的项目需要“网页内容脱离常规页面层级进行展示”，这个插件会比自己做原生桥接更省时。

适用场景

• 网页视频悬浮播放
• 活动页或直播页小窗展示
• 客服入口、助手入口、快捷工具窗
• 应用内悬浮操作面板
• 需要在主界面之外持续展示网页内容的业务场景

插件特点

• Android 支持打开、关闭网页悬浮窗
• Android 支持设置窗口宽高、显示位置、对齐方式
• Android 支持悬浮窗拖拽移动
• Android 支持悬浮窗权限检测与申请
• iOS 支持初始化 Picture in Picture 小窗
• iOS 支持打开、关闭 PiP 小窗
• iOS 支持检测当前设备是否可用 PiP

效果说明

• Android：通过系统悬浮窗或应用内窗口方式加载指定网页地址
• iOS：通过系统 Picture in Picture 机制将网页内容放入小窗中显示

注意：本插件核心能力为 App 原生端能力，不适用于 H5 与各类小程序平台。

支持平台

安装方式

将插件安装到项目后，直接在页面中引入并创建实例即可。

import MjUtsWinPip from '@/uni_modules/mj-uts-win-pip'

使用说明

使用前建议

• 建议在 App 端页面中调用，并使用 #ifdef APP-PLUS 做平台包裹
• Android 若使用系统级悬浮窗，请提前考虑权限引导流程
• iOS 建议先判断设备是否支持 PiP，再执行初始化与打开

Android 悬浮网页窗口

Android 侧通过 open 方法打开网页悬浮窗。

import MjUtsWinPip from '@/uni_modules/mj-uts-win-pip'

const winPip = new MjUtsWinPip()

const result = winPip.open({
    url: 'https://www.example.com',
    pattern: 1,
    width: 400,
    height: 240,
    gravity: {
        type: 0,
        x: 12,
        y: 12
    }
})

console.log('open result:', result)

iOS PiP 网页小窗

iOS 侧建议先调用 isPictureInPicturePossible() 检测，再调用 initPiP 初始化，最后再执行 open。

import MjUtsWinPip from '@/uni_modules/mj-uts-win-pip'

const winPip = new MjUtsWinPip()

if (winPip.isPictureInPicturePossible()) {
    winPip.initPiP({
        url: 'https://www.example.com',
        proportion: '16:9'
    })

    winPip.open()
}

uni-app 页面示例

import MjUtsWinPip from '@/uni_modules/mj-uts-win-pip'

export default {
    data() {
        return {
            winPip: null
        }
    },
    methods: {
        openWindow() {
            // #ifdef APP-PLUS
            const platform = (uni.getSystemInfoSync().platform || '').toLowerCase()
            if (this.winPip == null) {
                this.winPip = new MjUtsWinPip()
            }

            if (platform.indexOf('ios') >= 0) {
                this.winPip.initPiP({
                    url: 'https://www.example.com',
                    proportion: '16:9'
                })
                this.winPip.open()
            } else if (platform.indexOf('android') >= 0) {
                this.winPip.open({
                    url: 'https://www.example.com',
                    pattern: 1,
                    width: 400,
                    height: 240,
                    gravity: {
                        type: 0,
                        x: 12,
                        y: 12
                    }
                })
            }
            // #endif
        },
        closeWindow() {
            // #ifdef APP-PLUS
            if (this.winPip != null) {
                this.winPip.close()
            }
            // #endif
        }
    }
}

API 说明

通用 API

new MjUtsWinPip()

创建插件实例。

close()

关闭当前悬浮窗或 PiP 小窗。

checkOverlayPermission()

• Android：检测是否拥有悬浮窗权限
• iOS：固定返回 true

这个方法主要用于统一调用风格，实际权限判断意义主要在 Android 端。

Android API

open(options)

打开 Android 悬浮网页窗口。

返回值：String

• 成功时通常返回：打开成功
• 无权限时通常返回：暂未权限

options 参数说明：

gravity 参数说明：

gravity.type 取值说明：

isShow()

返回当前 Android 悬浮窗是否正在显示。

返回值：Boolean

requestOverlayPermission()

主动拉起 Android 悬浮窗权限申请页面。

convertHtmlPxToAndroidPx(px)

将页面像素值转换为 Android 原生窗口使用的像素值，适合用来计算悬浮窗宽高和偏移。

iOS API

isPictureInPicturePossible()

判断当前设备是否支持 Picture in Picture。

返回值：Boolean

initPiP(params)

初始化 iOS Picture in Picture 容器。

params 参数说明：

proportion 支持值：

• 16:9
• 4:3
• 3:4
• 1:1
• 9:16

open()

打开 iOS Picture in Picture 小窗。建议先调用 initPiP 再调用 open。

open(params)

iOS 也支持直接传入参数调用 open(params)，插件会先执行初始化，再打开小窗。

winPip.open({
    url: 'https://www.example.com',
    proportion: '16:9'
})

接口差异说明

为避免调用误解，建议按平台区分能力使用：

• Android 重点使用：open(options)、close()、isShow()、requestOverlayPermission()、convertHtmlPxToAndroidPx()
• iOS 重点使用：isPictureInPicturePossible()、initPiP(params)、open()、open(params)、close()
• checkOverlayPermission() 在两端都可调用，但真正有权限判断意义的是 Android
• Android open() 与 close() 有字符串返回值，iOS open() 与 close() 主要按过程调用，不依赖返回值

注意事项

Android

• 当 pattern 为 1 时，通常需要悬浮窗权限
• 首次调用时如果没有权限，插件会尝试拉起授权页面
• 悬浮窗加载的是网页内容，请确保 url 可正常访问

iOS

• 依赖系统的 Picture in Picture 能力，并非所有设备都可用
• 建议在打开前先调用 isPictureInPicturePossible() 检测
• 建议先初始化，再延时或按用户操作触发打开
• iOS 当前能力本质上是 PiP 小窗，不等同于 Android 的系统级全局悬浮窗

发布建议

• 插件市场详情页建议明确区分 Android 悬浮窗 与 iOS PiP 两种实现方式
• 如果业务依赖系统级悬浮显示，重点使用 Android 端能力
• 如果业务需要 iOS 小窗承载网页，建议先在真机上验证目标页面表现与系统兼容性

开发文档

• UTS 语法
• UTS API 插件
• UTS uni-app 兼容模式组件
• UTS 标准模式组件
• Hello UTS