更新记录

1.0.0(2026-11-19)

首次发布:完成 Android / HarmonyOS 双端实现与真机验证。


平台兼容性

uni-app x(4.25)

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

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

uni-float-window · 悬浮窗

开箱即用的悬浮窗插件:悬浮球 / 胶囊 / 卡片 三种形态,拖拽吸附、角标、动态样式、权限状态检测与引导。纯系统 API,无三方 SDK。

它解决什么问题

uni-app x 没有悬浮窗能力,但客服入口、返回顶部、录屏按钮、活动角标这类需求很常见。自己写要处理:

  • WindowManager 加窗口、SYSTEM_ALERT_WINDOW 特殊权限(不能弹窗申请,只能跳设置页)
  • 拖拽与边缘吸附的触摸判定
  • 三种形态的自绘与角标绘制
  • 鸿蒙端根本没有跨应用悬浮窗(受限权限仅 PC/2in1 可申请)

这个插件把这些都封装成一行 show()。

能力

能力 说明
三种形态 ball 圆形悬浮球、capsule 胶囊、card 圆角卡片
拖拽吸附 拖动跟手,松手自动吸附到最近的左右边缘
角标 数字角标,超过 99 显示 99+
动态样式 尺寸、透明度、配色、文字、图标随时改,不用先隐藏
交互回调 点击、长按、拖拽结束(带最终坐标)
双层级 app 应用内悬浮(免权限) / system 系统级(可浮在其它应用之上)
权限引导 检测 + 一键跳系统设置页,回前台自动刷新

快速上手

import { show, hide, setBadge } from '@/uni_modules/uni-float-window'

// 显示一个绿色悬浮球,右下角
show({
  style: { shape: 'ball', text: '客服', size: 56, badge: 3 },
  onTap: () => console.log('点了悬浮球'),
  End: (e) => console.log('停在', e.x, e.y, e.snapped ? '已吸边' : ''),
})

// 改角标
setBadge({ count: 8 })

// 隐藏
hide({})

系统级悬浮(可浮在微信、桌面之上):

import { checkPermission, requestPermission, show } from '@/uni_modules/uni-float-window'

checkPermission({
  success: (res) => {
    if (!res.granted) {
      // Android 特殊权限无法弹窗申请,必须跳系统设置页
      requestPermission({ success: () => console.log('已跳转设置') })
      return
    }
    show({ style: { level: 'system', shape: 'capsule', text: '进入店铺' } })
  }
})

API

方法 参数 说明
show(options) {style, onTap, onLongPress, End} 显示或更新悬浮窗
hide(options?) — 隐藏并移除
updateStyle(options) {style} 只改传入的字段,其余保持不变
moveTo(options) {x, y, animated?} 移动到指定坐标(dp)
setBadge(options) {count} 设置角标,<=0 清除
getState(options) — 查询显示状态、坐标、尺寸、渲染方式
checkPermission(options) — 检测系统级悬浮权限
requestPermission(options) — 跳系统设置页申请权限
dispatchEvent(options) {code, x, y, snapped?} 手动派发事件(页面自绘浮层时用)

样式字段

字段 类型 默认 说明
shape string ball ball / capsule / card
text string '' 显示文字,ball 建议 4 字内
icon string '' 图标本地路径,与 text 同时存在时图标在左
backgroundColor string #07C160 支持 #RRGGBB 与 #AARRGGBB
textColor string #FFFFFF 文字颜色
size number 56 dp,ball 为直径,其余为高度
opacity number 1 0~1
badge number 0 <=0 不显示
position string bottomRight topLeft/topRight/bottomLeft/bottomRight/center
margin number 16 贴边距(dp)
draggable boolean true 是否可拖拽
snapToEdge boolean true 松手是否吸附边缘
level string app app 应用内 / system 系统级

平台差异(重要)

能力 Android 鸿蒙
应用内悬浮(level: 'app') 支持,免权限 支持(页面内浮层,见下)
系统级悬浮(level: 'system') 支持,需用户手动授权 不支持
原生窗口渲染 支持 不支持

鸿蒙端为什么返回 renderMode: 'page'

ohos.permission.SYSTEM_FLOAT_WINDOW 是受限权限,AGC 文档明确:仅 PC/2in1 设备可申请,手机上的三方应用无法创建跨应用悬浮窗。而应用内子窗口(createSubWindow)需要 setUIContent 加载页面,UTS 插件无法向宿主工程注册页面。

所以鸿蒙端插件承担状态机 + 布局计算:维护样式与位置、处理拖动位移与边缘吸附,show() 返回 renderMode: 'page' 和建议的 x/y/width/height(dp),由页面用 Stack + 绝对定位渲染。API 语义与 Android 完全一致,业务代码不用分叉:

show({
  style: { shape: 'ball', text: '客服' },
  success: (res) => {
    if (res.renderMode === 'page') {
      // 鸿蒙:按 res.x / res.y / res.width / res.height 在页面里渲染浮层
      posX.value = res.x
      posY.value = res.y
    }
  }
})

// 页面里浮层被点击时,回传给插件
dispatchEvent({ code: 1, x: posX.value, y: posY.value })

Demo 页 pages/float-window/float-window.uvue 里有完整的浮层渲染示例。

注意事项

  1. 不能把 uvue 组件放进悬浮窗。悬浮窗是原生窗口,插件用 Canvas 自绘球/胶囊/卡片。需要复杂 UI 请用 app 层级并在页面内用绝对定位实现(鸿蒙端就是这么做的)。
  2. Android 特殊权限没有弹窗。SYSTEM_ALERT_WINDOW 只能通过 ACTION_MANAGE_OVERLAY_PERMISSION 跳系统设置页,用户回来后要重新 checkPermission(插件在 onShow 里做了)。
  3. app 层级随应用前后台显隐,切到后台会消失,这是系统行为,不是 bug。
  4. 坐标单位是 dp,moveTo 与 getState 都是屏幕左上角为原点。

错误码

错误码 说明
9090001 参数错误
9090002 悬浮窗权限被拒绝,请在系统设置中开启
9090003 悬浮窗未显示
9090004 当前平台不支持该能力
9090005 悬浮窗内部错误

兼容性

  • Android 5.0+(API 21)
  • HarmonyOS NEXT(app 层级 / 页面内浮层)
  • uni-app x(HBuilderX 4.25+)
  • 无需自定义基座,标准基座即可运行

隐私、权限声明

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

Android 跨应用悬浮需 SYSTEM_ALERT_WINDOW 特殊权限,由用户在系统设置中手动开启;应用内悬浮无需额外权限

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

插件不采集、不上传任何数据

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

无

暂无用户评论。