更新记录

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 仍显示(原生悬浮球 / 内嵌网页,需悬浮窗权限)。
  • 交互逐项可开关:拖拽、贴边吸附、点击展开/收起、震动反馈、半隐藏等都可通过配置开关。
  • 灵活自定义:尺寸、位置、层级、背景色、文字色、活动边界均可配置;也支持插槽自定义任意布局。

安装

  1. 在 HBuilderX 插件市场导入本插件(插件名 dlcx-float-window),插件会放入项目根目录的 uni_modules/dlcx-float-window。
  2. 项目需为 uni-app x 项目(manifest.json 中勾选 uni-app x)。
  3. 使用 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。

隐私、权限声明

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

Android 系统级悬浮窗需 SYSTEM_ALERT_WINDOW

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

无

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

无

暂无用户评论。