更新记录
1.0.0(2026-11-18)
首个版本。
- 新增应用内全局悬浮小窗组件
<dlcx-float-window>:- 组件内直接写内容(插槽)即可,内置
ball/card外观; - 支持拖拽移动、贴边吸附(左/右/就近)、点击展开收起;
- 交互逐项可开关:
draggable、snap、snapThreshold、edgeHide、expandable、vibrate; - 可自定义尺寸、位置、层级、背景色、文字色与活动边界;
- 提供
click / dragstart / dragmove / dragend / snap / expand / collapse / change事件回调。
- 组件内直接写内容(插槽)即可,内置
- 新增全局宿主组件
<dlcx-float-host>:每页放置一次即可实现应用内跨页悬浮。 - 新增全局 API:
showFloat / hideFloat / toggleFloat / updateFloat / getFloatState / setFloatPosition / resetFloat / onFloatChange / offFloatChange。 - 新增 Android 系统级悬浮窗(原生
WindowManager+TYPE_APPLICATION_OVERLAY,退到桌面/切到其它 App 仍显示):isSystemOverlaySupported / isSystemOverlayGranted / requestSystemOverlayPermission;showSystemOverlay / hideSystemOverlay / isSystemOverlayShowing;onSystemOverlayEvent / offSystemOverlayEvent(点击 / 拖拽 / 吸附 / 网页回调事件);- 内容三种写法:A 内置模板(
preset:'ball'|'card'|'menu'|'notice'+title/message/items);B 内联html+css(插件自动补全 HTML 外壳与基础样式,无需单独建文件);C 完整 HTML 或网页地址(page); - 网页内注入全局函数
dlcx(action, data?)/dlcxClose(),通过 URL Scheme 拦截回传为type:'action'事件; - 支持拖拽与松手自动贴边(
draggable/autoSnap);需SYSTEM_ALERT_WINDOW权限。 - 尺寸与位置统一使用逻辑像素(与 uvue 的
px一致),插件按设备像素比自动换算,保证网页内容不被裁剪; - 网页加载后自动测量内容高度并调整窗口高度(
height仅为初始值),内容再多也能完整显示,按钮不会被截断; - 内置模板采用内联样式并重新设计(列表卡片 / 九宫格 / 通知),开箱即用、显示完整。
- 平台支持:App-Android / App-iOS / App-Harmony / Web。
平台兼容性
uni-app x(4.71)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | √ | √ | √ | √ | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | √ | × | √ |
全局悬浮小窗(dlcx-float-window)
uni-app x 全端(App-Android / App-iOS / App-Harmony / Web)全局悬浮小窗插件。
- 组件内直接写内容:把
<dlcx-float-window>放进页面,标签内写任意 uvue 内容即可。 - 应用内跨页悬浮:在每个页面根节点放一次
<dlcx-float-host>,配合showFloat()/hideFloat()等 API,实现「一次开启、全应用可见、跨页保持」。 - Android 系统级悬浮窗:退到桌面、切到其它 App 仍显示(原生悬浮球 / 内嵌网页,需悬浮窗权限)。
- 交互逐项可开关:拖拽、贴边吸附、点击展开/收起、震动反馈、半隐藏等都可通过配置开关。
- 灵活自定义:尺寸、位置、层级、背景色、文字色、活动边界均可配置;也支持插槽自定义任意布局。
安装
- 在 HBuilderX 插件市场导入本插件(插件名
dlcx-float-window),插件会放入项目根目录的uni_modules/dlcx-float-window。 - 项目需为 uni-app x 项目(
manifest.json中勾选 uni-app x)。 - 使用
uni_modules组件规范,无需额外配置,直接在页面中引用组件或 API 即可。
运行环境
| 项 | 要求 |
|---|---|
| HBuilderX | ≥ 4.71(uni-app x) |
| 应用内悬浮(组件 / 宿主) | 全端可用:App-Android / App-iOS / App-Harmony / Web |
| Android 系统级悬浮窗 | Android 6.0+(API 23+),需 SYSTEM_ALERT_WINDOW 权限,必须打包自定义基座调试 |
未打包自定义基座时,系统级悬浮窗的原生代码不会生效(应用内悬浮不受影响)。
一、快速开始
1. 页面内直接使用(应用内悬浮,全端)
在任意页面的根节点放一个悬浮窗组件,标签内写内容:
<template>
<view>
<!-- 页面内容 -->
<text>Hello</text>
<!-- 悬浮窗:内容直接写在标签里 -->
<dlcx-float-window
:x="24" :y="200"
:width="64" :height="64"
draggable
snap="both"
expandable
:expanded-width="200" :expanded-height="120"
@click="onClick"
@snap="onSnap">
<view class="my-fw">
<text>+</text>
</view>
</dlcx-float-window>
</view>
</template>
组件默认使用插槽内容(
preset为空)。若想用内置外观,把preset设为'ball'(圆球)或'card'(卡片),并配合icon/title/text显示文字。
2. 应用内跨页全局悬浮(推荐)
想做到「任意页面都显示、切页不丢失」,采用「全局宿主」模式:
第一步:在每个页面的根节点放一次宿主组件(可写内容):
<template>
<view>
<!-- 页面内容 -->
<dlcx-float-host @click="onFloatClick">
<view class="my-fw"><text>+</text></view>
</dlcx-float-host>
</view>
</template>
第二步:在任意地方用 API 控制它(例如首页 onLoad):
import { showFloat, hideFloat, updateFloat } from '@/uni_modules/dlcx-float-window'
showFloat({
visible: true,
x: 24, y: 200,
width: 64, height: 64,
draggable: true,
snap: 'both',
expandable: true,
expandedWidth: 200, expandedHeight: 120,
icon: '+', text: '快捷'
})
之后无论切到哪个页面,只要该页放了 <dlcx-float-host>,悬浮窗都会以相同的位置与状态显示。
3. Android 系统级悬浮窗(可退到桌面 / 悬浮在其它 App 之上)
系统级悬浮窗由原生 WindowManager 绘制(TYPE_APPLICATION_OVERLAY),无法承载 uvue 组件,所以内容用「原生悬浮球」或「内嵌网页」两种形态承载。共支持三种写法,按需选择。
权限与基础调用:
import {
isSystemOverlaySupported,
isSystemOverlayGranted,
requestSystemOverlayPermission,
showSystemOverlay,
hideSystemOverlay,
onSystemOverlayEvent
} from '@/uni_modules/dlcx-float-window'
// 1) 申请权限(会跳转到系统的「显示在其他应用上层」授权页)
if (isSystemOverlaySupported() && !isSystemOverlayGranted()) {
requestSystemOverlayPermission()
}
写法 A:内置模板(最省事,无需写 HTML)
用 preset 选模板,配合 title / message / items 填数据:
preset: 'ball':原生圆形悬浮球(最轻量,只能显示文字/Emoji)preset: 'card':竖列表卡片(title+items)preset: 'menu':九宫格菜单(items)preset: 'notice':通知弹窗(title+message+ 一个按钮)
showSystemOverlay({
x: 24, y: 320, autoSnap: true,
preset: 'card',
title: '客服中心',
items: [
{ icon: '💬', text: '在线咨询', action: 'chat' },
{ icon: '📞', text: '电话咨询', action: 'call' }
]
})
items[].action为点击后回传的动作名,省略时用text。
写法 B:内联 HTML + CSS(插件自动补全外壳)
只写 <body> 里的片段即可,插件会自动补上 <!DOCTYPE html>、viewport、基础样式,并注入回调函数,不必单独建 HTML 文件。
showSystemOverlay({
x: 24, y: 320, width: 280, height: 200, autoSnap: true,
html: `<div class="dlcx-notice">
<h3>今日待办</h3>
<p>有 3 个任务待处理</p>
<button class="dlcx-btn" onclick="dlcx('goTodo')">去看看</button>
</div>`,
css: `.dlcx-btn{background:#ff9500;}`
})
内置基础样式类(可直接用):.dlcx-title / .dlcx-list / .dlcx-item / .dlcx-ico / .dlcx-txt / .dlcx-menu / .dlcx-cell / .dlcx-notice / .dlcx-btn。
写法 A / B / C1 的窗口高度会随内容自动适配,内容再多都会完整显示;C2(加载网页地址)无法测量内容,请自行设置合适的
width/height。css与html里的<style>/style均生效,需要覆盖内联样式时在css里加!important。
写法 C:完整 HTML / 网页地址
page 传完整 HTML 字符串;或以 http://、https://、file://、/ 开头时按网页地址直接加载。
// C1:完整 HTML 字符串
showSystemOverlay({ x: 24, y: 320, width: 300, height: 220, page: '<html>...</html>' })
// C2:加载网页地址(本地静态文件也可,用 file:// 或绝对路径)
showSystemOverlay({ x: 24, y: 320, width: 300, height: 220, page: 'https://example.com/panel.html' })
网页内回调 App
网页里调用注入的全局函数即可把动作回传给宿主:
<button onclick="dlcx('openChat')">打开会话</button>
<button onclick="dlcx('submit', { id: 1, name: 'dlcx' })">提交</button>
<button onclick="dlcxClose()">关闭悬浮窗</button>
宿主侧监听:
const id = onSystemOverlayEvent((e) => {
if (e.type == 'action') {
console.log('action:', e.action) // 网页里 dlcx('xxx') 传来的动作名
} else if (e.type == 'click') {
// 悬浮球被点击
}
})
dlcx(action, data?)的第二个参数可传任意数据(对象会自动 JSON 序列化);dlcxClose()会关闭并移除悬浮窗。 系统级悬浮需 Android 6.0+,且必须打包自定义基座才能调试。 iOS / HarmonyOS / Web 上isSystemOverlaySupported()返回false,相关 API 为空实现(不报错),可放心跨端调用。
二、组件:<dlcx-float-window>
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
visible |
boolean |
true |
是否显示 |
x / y |
number |
24 / 180 |
初始位置(px,相对屏幕) |
width / height |
number |
72 / 72 |
尺寸(px) |
draggable |
boolean |
true |
是否允许拖拽 |
snap |
string |
'none' |
贴边吸附:'none' / 'left' / 'right' / 'both' |
snapThreshold |
number |
0 |
距边缘多少 px 内才吸附;0 表示松手始终吸附 |
edgeHide |
boolean |
false |
吸附后是否半隐藏(露出半边) |
expandable |
boolean |
false |
是否允许点击展开/收起 |
expandedWidth / expandedHeight |
number |
0 |
展开后的尺寸;0 表示沿用原尺寸 |
vibrate |
boolean |
false |
拖拽/吸附是否震动反馈 |
zIndex |
number |
9999 |
层级 |
preset |
string |
'' |
内置外观:'' 用插槽 / 'ball' 圆球 / 'card' 卡片 |
icon / title / text |
string |
'' |
内置外观的文字/图标 |
backgroundColor / textColor |
string |
'#007AFF' / '#FFFFFF' |
内置外观配色 |
boundsTop/Bottom/Left/Right |
number |
0 |
活动边界(px),限制拖拽范围;0 表示贴屏幕边缘 |
事件
| 事件 | 说明 |
|---|---|
@click |
点击(未发生拖拽时触发) |
@dragstart / @dragmove / @dragend |
拖拽开始 / 移动 / 结束 |
@snap |
触发贴边吸附 |
@expand / @collapse |
展开 / 收起 |
@change |
位置或尺寸变化 |
事件参数:
type FloatEventPayload = {
type: string // 事件类型
x: number
y: number
width: number
height: number
expanded: boolean
}
组件方法(通过 ref 调用)
const fw = ref(null)
// fw.value.expand() 展开
// fw.value.collapse() 收起
// fw.value.moveTo(x,y) 移动到指定位置
// fw.value.getPosition() 读取当前位置
// fw.value.isExpanded() 是否已展开
三、组件:<dlcx-float-host>(应用内跨页宿主)
宿主组件本身不含样式,它把全局状态映射到内部的 <dlcx-float-window>,用于「多页面共享同一个悬浮窗」。
- 用法:在每个页面的根节点放置一次,标签内写内容(作为插槽传给内部悬浮窗)。
- 无需传 Props:位置、尺寸、显隐等全部由全局 API(
showFloat / updateFloat等)驱动。 - 事件:与
<dlcx-float-window>相同,即click / dragstart / dragmove / dragend / snap / expand / collapse / change;其中拖拽/吸附结束时会把新位置写回全局状态,保证跨页一致。 - 方法:
getState()读取当前全局状态。
<dlcx-float-host @click="onFloatClick">
<view class="my-fw"><text>+</text></view>
</dlcx-float-host>
四、全局 API(@/uni_modules/dlcx-float-window)
| API | 说明 |
|---|---|
showFloat(options?) |
显示悬浮窗(可同时更新配置) |
hideFloat() |
隐藏悬浮窗 |
toggleFloat() |
显示/隐藏切换 |
updateFloat(options) |
仅更新配置,不改变显示状态 |
getFloatState() |
读取当前全局状态 |
setFloatPosition(x, y) |
直接设置位置 |
resetFloat() |
恢复默认状态 |
onFloatChange(cb): number |
订阅状态变更,返回订阅 id |
offFloatChange(id) |
取消订阅 |
FloatOptions(配置项,字段均可选)与组件 Props 一一对应,另含 icon / title / text 等内置外观内容。
系统级悬浮窗 API(Android)
| API | 说明 |
|---|---|
isSystemOverlaySupported() |
当前平台是否支持系统级悬浮窗 |
isSystemOverlayGranted() |
是否已获得悬浮窗权限 |
requestSystemOverlayPermission() |
跳转系统授权页申请权限 |
showSystemOverlay(options?) |
显示系统级悬浮窗 |
hideSystemOverlay() |
隐藏并移除 |
isSystemOverlayShowing() |
是否正在显示 |
onSystemOverlayEvent(cb): number |
订阅点击/拖拽/网页回调事件 |
offSystemOverlayEvent(id) |
取消订阅 |
SystemOverlayOptions(字段均可选):
| 字段 | 类型 | 说明 |
|---|---|---|
x / y |
number |
初始位置(逻辑 px,与 uvue 一致),默认 24 / 320 |
preset |
string |
'ball' / 'card' / 'menu' / 'notice'(写法 A) |
html / css |
string |
内联片段与附加样式(写法 B) |
page |
string |
完整 HTML 或网页地址(写法 C) |
title / message |
string |
模板标题 / 正文 |
items |
SystemOverlayItem[] |
模板列表项 { icon?, text?, action? } |
width / height |
number |
网页模式尺寸(逻辑 px),默认 260 / 200;height 仅为初始值,加载后会自动适配内容高度 |
size |
number |
悬浮球直径(逻辑 px,preset:'ball' 时用),默认 56 |
icon / text |
string |
球内文字 / Emoji |
backgroundColor / textColor |
string |
窗口背景色('' 为透明)/ 球内文字色 |
draggable |
boolean |
是否可拖动(网页模式顶部显示拖拽条),默认 true |
autoSnap |
boolean |
松手自动贴边,默认 true |
vibrate |
boolean |
震动反馈 |
SystemOverlayEvent:{ type, x, y, action },其中 type 为 'click' / 'dragstart' / 'dragmove' / 'dragend' / 'snap' / 'action';网页内 dlcx('xxx') 触发 type:'action' 且 action='xxx'。
五、平台支持与注意
| 能力 | Android | iOS | HarmonyOS | Web |
|---|---|---|---|---|
| 应用内悬浮(组件 / 宿主) | √ | √ | √ | √ |
| 系统级悬浮窗(悬浮球 / 网页) | √ | — | — | — |
- 应用内悬浮是全端能力,任何平台都可用。
- 系统级悬浮目前仅 Android 实现(原生
TYPE_APPLICATION_OVERLAY)。 - 声音/震动:
vibrate仅在 App 端生效。 - Android 系统级悬浮需
SYSTEM_ALERT_WINDOW权限,且需使用自定义基座运行。
六、常见问题
Q:切页面后悬浮窗消失了?
A:请确认目标页面也放了 <dlcx-float-host>。uni-app x 无法「放一次全页生效」,需每页各放一次(内容可不同)。状态由全局单例维护,所以位置与开关是共享的。
Q:悬浮窗被页面内容盖住?
A:调大 zIndex,并确认页面没有使用会裁剪子节点的容器。
Q:系统级悬浮窗能放自己的 uvue 组件吗? A:不能直接放 uvue 组件。系统级悬浮在 App 窗口之外,只能用原生绘制,因此内容用「原生悬浮球」或「内嵌 WebView 承载 HTML/CSS」承载。需要复杂界面可用写法 B(内联 HTML)或写法 C(完整 HTML / 网页地址)。
Q:点击没反应?
A:当 draggable=true 时,手指移动超过阈值会被判定为拖拽而非点击。可调小阈值判断或关闭拖拽。
七、更新日志
见 changelog.md。

收藏人数:
购买普通授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 0
赞赏 0
下载 12773692
赞赏 1960
赞赏
京公网安备:11010802035340号