更新记录

1.0.7（2026-06-11）

显示悬浮窗。若已有悬浮窗，会先移除再创建。

平台兼容性

uni-app x(3.7.9)

其他

my-floatwindow

全局悬浮窗插件（Android），基于 WindowManager + TYPE_APPLICATION_OVERLAY 实现系统级悬浮窗。支持文本、图片、视频、网页四种内容模式，支持拖拽、边缘吸附、自定义图标与回调。

平台支持： 仅 Android（iOS 暂未实现）

快速开始

import { showFloatWindow, hideFloatWindow } from '@/uni_modules/my-floatwindow'

// 显示文本悬浮窗
showFloatWindow({
  text: '来电中 00:32',
  width: 280,
  height: 72,
})

// 隐藏悬浮窗
hideFloatWindow()

API

showFloatWindow(options)

显示悬浮窗。若已有悬浮窗，会先移除再创建。

updateFloatWindow(options)

增量更新悬浮窗内容（文本/图片/视频/网页 URL），无需销毁重建。

hideFloatWindow()

隐藏并移除悬浮窗。

checkOverlayPermission(): boolean

检查是否已授予悬浮窗权限。

requestOverlayPermission()

请求悬浮窗权限（跳转系统设置页）。

setOnClickCallback(cb: (() => void) | null)

设置悬浮窗主体区域的点击回调。

setOnReturnCallback(cb: (() => void) | null)

设置点击「全屏图标」返回 App 的回调。

setOnCloseCallback(cb: (() => void) | null)

设置点击「关闭图标」的回调。

setOnPlayPauseCallback(cb: ((playing: boolean) => void) | null)

设置播放/暂停按钮的回调。参数 playing：true 表示当前正在播放，false 表示已暂停。

setOnMuteCallback(cb: ((muted: boolean) => void) | null)

设置静音按钮的回调。参数 muted：true 表示已静音，false 表示已取消静音。

FloatWindowOptions 配置项

基础配置

样式

内边距

图片模式（contentType=image）

视频模式（contentType=video）

WebView 模式（contentType=url）

按钮图标配置

使用示例

文本模式（悬浮窗）

import { checkOverlayPermission, requestOverlayPermission, showFloatWindow, hideFloatWindow, setOnClickCallback, setOnReturnCallback, setOnCloseCallback } from '@/uni_modules/my-floatwindow'

// 检查权限
if (!checkOverlayPermission()) {
  requestOverlayPermission()
  return
}

// 设置回调
setOnClickCallback(() => {
    console.log('点击了浮窗');
});
setOnReturnCallback(() => {
    console.log('点击了全屏图标，返回App');
});
setOnCloseCallback(() => {
    console.log('关闭按钮被点击了');
});

// 显示文字悬浮窗（
showTextFloat() {
    this.callSeconds = 0;
    /*各个模式通用
        // x: 100,浮窗的坐标
        // y: 200,浮窗的坐标
        // width: 200,浮窗的尺寸
        // height: 200,浮窗的尺寸
        // cornerRadius: 32,    浮窗圆角
        // padding:12;  内容区域内边距（像素），默认 12
        // paddingTop   上内边距
        // paddingBottom下内边距
        // paddingLeft  左内边距
        // paddingRight 右内边距
        // backgroundColor: 0xFF1A6DE6,//浮窗背景颜色
        // 左右两边小图标
        // iconSize             默认36    图标大小（像素）
        // fullscreenIcon   全屏图标本地自定义图片
        //fullscreenIconCornerRadius全屏图标背景圆角（像素），默认 8
        // fullscreenIconBgColor 全屏图标背景
        // fullscreenIconTintColor 全屏图标颜色
        // fullscreenIconPadding 全屏图标内边距（像素），默认 4
        // fullscreenIconPosition   全屏图标默认'topRight'    全屏图标位置: 'topLeft'/'topRight'/'bottomLeft'/'bottomRight'
        // closeIcon 关闭图标本地自定义图片
        //closeIconCornerRadius关闭图标背景圆角（像素），默认 8
        // closeIconBgColor 关闭图标图标背景
        // closeIconTintColor 关闭图标图标颜色
        // closeIconPadding 关闭图标内边距（像素），默认 4
        // closeIconPosition    默认'topLeft' 关闭图标位置
    */
    const now = new Date();
    const hour = this.padZero(now.getHours());
    const minute = this.padZero(now.getMinutes());
    const second = this.padZero(now.getSeconds());
    this.currentTime = `${hour}:${minute}:${second}`;
    showFloatWindow({
        contentType: 'text',
        text: '时间：' + this.currentTime,
        x: 100,//浮窗的坐标
        y: 200,//浮窗的坐标
        width: 200,//浮窗的尺寸
        height: 200,//浮窗的尺寸
        cornerRadius: 32,//浮窗圆角
        backgroundColor: 0xFF1A6DE6,//浮窗背景颜色
        textColor: 0xFFFFFFFF,//字体颜色
        textSize: 12,//字体大小
        padding: 6,
        // paddingTop: 20,
        // paddingBottom: 20,
        // paddingLeft: 16,
        // paddingRight: 16,
        iconSize: 40,
        fullscreenIcon: '/static/ic_menu_fullscreen.png',
        fullscreenIconBgColor: 0x88000000,
        fullscreenIconTintColor: 0xFFFFFFFF,
        fullscreenIconCornerRadius:8,//全屏图标背景圆角（像素），默认 8
        fullscreenIconPadding: 6,
        fullscreenIconPosition: 'topRight',
        closeIcon: '/static/ic_menu_close.png',
        closeIconBgColor: 0x88FFFFFF,
        closeIconTintColor: 0xFF333333,
        closeIconCornerRadius:8,//关闭图标背景圆角（像素），默认 8
        closeIconPadding: 6,
        closeIconPosition: 'topLeft',
    });
}

视频模式（画中画悬浮窗）

import { showFloatWindow, hideFloatWindow, setOnPlayPauseCallback, setOnMuteCallback } from '@/uni_modules/my-floatwindow'

setOnPlayPauseCallback((playing: boolean) => {
  console.log(playing ? '开始播放' : '已暂停')
})
setOnMuteCallback((muted: boolean) => {
  console.log(muted ? '已静音' : '取消静音')
})

showVideoFloat() {
    // videoMarginTop   默认0 上外边距
    // videoMarginBottom    默认0 下外边距
    // videoMarginLeft  默认0 左外边距
    // videoMarginRight 默认0 右外边距
    showFloatWindow({
        contentType: 'video',
        contentUrl: 'https://web-ext-storage.dcloud.net.cn/video/sample/2minute-demo.mp4',//视频地址，本地或网络地址
        videoPoster: 'https://hellouniappx.dcloud.net.cn/web/static/test-image/logo.png',//视频封面，本地或网络地址
        width: 320,
        height: 200,
        cornerRadius: 12,
        backgroundColor: 0xFF000000,
        videoWidth: 320,
        videoHeight: 200,
        padding: 0,
        videoMarginTop: 0,
        videoMarginBottom: 0,
        videoMarginLeft: 0,
        videoMarginRight: 0,
        videoAutoplay: true,
        videoLoop: true,
        videoMuted: false,
        videoInitialTime: 5,
        videoShowPlayBtn: true,//是否显示播放按钮，默认 true
        videoPlayBtnPosition: 'left',//播放按钮位置：'center' | 'left'，默认 'center'
        videoPlayBtnSize: 50,//播放按钮大小（像素），默认 44
        videoPlayBtnIconSize: 10,//播放按钮图标大小（sp），默认 20
        videoPlayBtnColor: 0xFFFFFFFF,//播放按钮颜色，默认 0xFFFFFFFF
        videoPlayBtnBgColor: 0xFFFF0000,//播放按钮背景色，默认 0x66000000
        videoShowMuteBtn: true,//是否显示静音按钮，默认 false
        videoMuteBtnSize: 50,//静音按钮大小（像素），默认 32
        videoMuteBtnIconSize: 10,//静音按钮图标大小（sp），默认 16
        videoMuteBtnColor:0xFFFFFFFF,//静音按钮颜色，默认 0xFFFFFFFF
        videoMuteBtnBgColor:0x66000000,//静音按钮背景色，默认 0x66000000
        videoMuteBtnCornerRadius:8,//静音按钮背景圆角（像素），默认 8
        iconSize: 36,
        fullscreenIconPosition: 'topRight',
        closeIconPosition: 'topLeft',
    });
}

图片模式

showImageFloat() {
    // imgMarginTop 默认0 图片上外边距
    // imgMarginBottom  默认0 图片下外边距
    // imgMarginLeft    默认0 图片左外边距
    // imgMarginRight   默认0 图片右外边距
    // imgScaleType 图片缩放类型，默认 'centerCrop' 可选值：'center' | 'centerCrop' | 'centerInside' | 'fitCenter' | 'fitEnd' | 'fitStart' | 'fitXY' | 'matrix'
    // imgCornerRadius 图片圆角（像素），默认 0

    showFloatWindow({
        contentType: 'image',
        // contentUrl: 'https://hellouniappx.dcloud.net.cn/web/static/test-image/logo.png', // 网络图
        contentUrl: '/static/logo.png', // 本地图（/static/ → 插件 assets 目录）
        width: 220,
        height: 220,
        cornerRadius: 16,
        backgroundColor: 0xFF000000,
        imgWidth: 200,
        imgHeight: 200,
        imgScaleType: 'centerCrop',
        imgCornerRadius: 12,
        imgMarginTop: 10,
        imgMarginBottom: 10,
        imgMarginLeft: 10,
        imgMarginRight: 10,
        iconSize: 36,
        fullscreenIconPosition: 'topRight',
        closeIconPosition: 'topLeft',
    });
}

WebView 模式

showWebFloat() {
    // webMarginTop 默认0 上外边距
    // webMarginBottom  默认0 下外边距
    // webMarginLeft    默认0 左外边距
    // webMarginRight   默认0 右外边距
    showFloatWindow({
        contentType: 'url',
        contentUrl: 'https://www.baidu.com',
        width: 360,
        height: 520,
        cornerRadius: 12,
        backgroundColor: 0xFFFFFFFF,
        webWidth: 340,
        webHeight: 480,
        webJavascript: true,
        webDomStorage: true,
        webFullscreen: true,
        webMarginTop: 6,
        webMarginBottom: 6,
        webMarginLeft: 6,
        webMarginRight: 6,
        iconSize: 36,
        fullscreenIconPosition: 'topRight',
        closeIconPosition: 'topLeft',
    });
}

增量更新内容

import { updateFloatWindow } from '@/uni_modules/my-floatwindow'

// 更新文本
updateFloatWindow({ text: '时间 01:05' })

// 切换图片
updateFloatWindow({ contentType: 'image', contentUrl: 'https://example.com/new-photo.jpg' })

注意事项

• 权限：使用前必须检查并请求 SYSTEM_ALERT_WINDOW 悬浮窗权限
• 自定义基座：本插件为原生 UTS 插件，需使用自定义基座运行
• 图标传入：fullscreenIcon / closeIcon
• 触摸交互：触摸悬浮窗区域时全屏/关闭/播放/静音图标会显示，2.5 秒无操作后自动隐藏
• 拖拽吸附：悬浮窗支持拖拽，松手后距离屏幕边缘 60px 以内会自动吸附
• 预留字段：videoControls、videoObjectFit、videoShowFullscreenBtn、videoShowProgress 为预留配置，当前版本不生效