更新记录
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 里有完整的浮层渲染示例。
注意事项
- 不能把 uvue 组件放进悬浮窗。悬浮窗是原生窗口,插件用 Canvas 自绘球/胶囊/卡片。需要复杂 UI 请用
app层级并在页面内用绝对定位实现(鸿蒙端就是这么做的)。 - Android 特殊权限没有弹窗。
SYSTEM_ALERT_WINDOW只能通过ACTION_MANAGE_OVERLAY_PERMISSION跳系统设置页,用户回来后要重新checkPermission(插件在onShow里做了)。 app层级随应用前后台显隐,切到后台会消失,这是系统行为,不是 bug。- 坐标单位是 dp,
moveTo与getState都是屏幕左上角为原点。
错误码
| 错误码 | 说明 |
|---|---|
| 9090001 | 参数错误 |
| 9090002 | 悬浮窗权限被拒绝,请在系统设置中开启 |
| 9090003 | 悬浮窗未显示 |
| 9090004 | 当前平台不支持该能力 |
| 9090005 | 悬浮窗内部错误 |
兼容性
- Android 5.0+(API 21)
- HarmonyOS NEXT(
app层级 / 页面内浮层) - uni-app x(HBuilderX 4.25+)
- 无需自定义基座,标准基座即可运行

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 69
赞赏 0
下载 12776255
赞赏 1960
赞赏
京公网安备:11010802035340号