更新记录

1.0.0（2026-06-15）

• 首发：uni-app x 应用内悬浮窗组件 ba-float-u（Android / iOS / Harmony）
• 页面内悬浮：slot 自定义、拖拽、贴边吸附、遮罩弹层（placement=center）
• 全局跨页悬浮：showGlobalFloat / updateGlobalFloat / hideGlobalFloat + ba-float-global-host
• 内置 ba-float-global-shell（ball / bar）及 6 个独立预设组件 ba-float-preset-*
• 手势：原生 longpress + touch 拖动 + tap 守卫，区分单击/长按/拖动
• 全局 slot 自定义 UI；预设按需 import，业务侧自由组合
• 全局 content 仅 type / icon / text / backgroundColor，角标由 preset 或自定义 UI 自行扩展

平台兼容性

uni-app(3.7.12)

uni-app x(3.7.12)

ba-float-u 应用内悬浮窗

简介

ba-float-u 是面向 uni-app x App 端（Android / iOS / Harmony）的应用内悬浮窗组件。

• 页面内悬浮：写在当前页 template，随页面销毁
• 全局跨页悬浮：showGlobalFloat() + 各页 <ba-float-global-host />，切换页面仍显示
• slot 自定义 UI：任意布局；内置 shell 与 6 个经典预设皮肤
• 动态更新：updateGlobalFloat() 不关闭悬浮即可更新 icon / text / backgroundColor 等
• 手势：拖动、单击、长按统一识别，减少误触

安装

1. 在 HBuilderX 插件市场导入 ba-float-u，或
2. 将 uni_modules/ba-float-u 目录拷贝到项目的 uni_modules/ 下

组件通过 easycom 自动引入，一般无需手动 import 组件标签。

平台与限制

不要用 dialogPage 做全局悬浮：dialogPage 在 App 端为全屏层，会挡住下层页面所有点击。

一、全局悬浮（跨页面）

1. 页面根级放置宿主

<template>
  <view class="page">
    <!-- 页面内容 -->
    <ba-float-global-host />
  </view>
</template>

2. 显示 / 隐藏

import { showGlobalFloat, hideGlobalFloat, updateGlobalFloat } from '@/uni_modules/ba-float-u'

// 显示
showGlobalFloat({
  x: 20,
  y: 180,
  snap: 'edge',
  content: {
    type: 'ball',
    icon: '◎',
    backgroundColor: '#ff5722'
  }
})

// 动态更新（无需关闭）
updateGlobalFloat({
  content: {
    text: '正在播放',
    backgroundColor: '#1db954'
  }
})

hideGlobalFloat()

切换页面后，只要目标页也有 <ba-float-global-host />，悬浮会继续显示，且页面可正常点击。

3. 全局 API

导出类型（TypeScript / UTS）：

showGlobalFloat / updateGlobalFloat 参数：

content 字段：

全局 content 不包含角标。红点/数字角标请在 slot 自定义 UI 或复制 preset 后自行扩展。

4. 自定义全局 UI（slot）

方式 A：直接传 slot

<ba-float-global-host>
  <view class="my-global-ball">
    <text>拖我</text>
  </view>
</ba-float-global-host>

未传 slot 时，使用内置 ba-float-global-shell（content.type 为 ball / bar）。

方式 B：按需引入预设组件

预设为独立组件，在 slot 中按需组合，只 import 用到的 preset：

<ba-float-global-host>
  <ba-float-preset-capsule />
</ba-float-global-host>

方式 C：运行时切换多种预设（业务侧封装）

在工程中自建宿主，只 import 需要的 preset：

<template>
  <ba-float-global-host>
    <ba-float-preset-capsule v-if="presetType == 'capsule'" />
    <ba-float-preset-fab v-else-if="presetType == 'fab'" />
    <ba-float-global-shell v-else />
  </ba-float-global-host>
</template>

<script lang="uts">
import BaFloatGlobalHost from '@/uni_modules/ba-float-u/components/ba-float-global-host/ba-float-global-host.uvue'
import BaFloatPresetCapsule from '@/uni_modules/ba-float-u/components/ba-float-preset-capsule/ba-float-preset-capsule.uvue'
import BaFloatPresetFab from '@/uni_modules/ba-float-u/components/ba-float-preset-fab/ba-float-preset-fab.uvue'
import BaFloatGlobalShell from '@/uni_modules/ba-float-u/components/ba-float-global-shell/ba-float-global-shell.uvue'
import { floatGlobalState } from '@/uni_modules/ba-float-u'

export default {
  components: { BaFloatGlobalHost, BaFloatPresetCapsule, BaFloatPresetFab, BaFloatGlobalShell },
  computed: {
    presetType(): string {
      return floatGlobalState.content.type
    }
  }
}
</script>

切换预设时调用 updateGlobalFloat({ content: { type: 'capsule', ... } }) 即可。

方式 D：封装固定 UI 各页复用（跨页一致，强烈推荐）

各页面必须使用同一个宿主，否则切换页面后 slot / 交互会不一致：

<!-- components/ba-app-global-float-host/ba-app-global-float-host.uvue -->
<template>
  <ba-float-global-host>
    <!-- 按 floatGlobalState.content.type 渲染 preset / 自定义 UI -->
    <ba-float-preset-capsule v-if="presetType == 'capsule'" />
    <ba-float-global-shell v-else />
  </ba-float-global-host>
</template>

各页面根级统一：

<ba-app-global-float-host />

跳转、多按钮等交互应在 App 级单例 或业务宿主内注册 uni.$on（演示见 utils/baFloatGlobalEvents.uts + App.uvue），切勿在页面 onUnload 里无参调用 uni.$off('ba-float-global-tap')，否则会清掉其它页的监听。

方式 E：slot 内自行加角标/扩展 UI

<ba-float-global-host>
  <view class="my-ball">
    <text>{{ floatGlobalState.content.icon }}</text>
    <view v-if="unread > 0" class="my-badge">
      <text>{{ unread }}</text>
    </view>
  </view>
</ba-float-global-host>

unread 绑定业务 store / data，与 updateGlobalFloat 更新的 content 字段互不冲突。

slot 内 不要 绑 @tap / @longpress，请监听组件 @tap / @long-press 或全局 uni.$on。

5. 全局事件

uni.$on('ba-float-global-tap', (content) => {})
uni.$on('ba-float-global-long-press', (content) => {})
uni.$on('ba-float-global-drag-end', (e) => {})

// 页面卸载时记得 $off

二、页面内悬浮

无遮罩（悬浮球）：只渲染 fixed 悬浮体，不铺全屏，页面可正常点击。

<ba-float-u v-model:visible="show" draggable snap="edge">
  <view class="my-float">...</view>
</ba-float-u>

带遮罩（弹层卡片）：

<ba-float-u
  v-model:visible="showCard"
  mask
  placement="center"
  :draggable="false"
  @close="showCard = false"
>
  <view class="card">...</view>
</ba-float-u>

ba-float-u Props

ba-float-u 事件

四、交互示例

单击跳转页面（可拖动悬浮）

监听全局 uni.$on('ba-float-global-tap')，在回调里 uni.navigateTo：

uni.$on('ba-float-global-tap', () => {
  uni.navigateTo({ url: '/pages/detail/detail' })
})

slot 内不要绑 @tap，统一走组件 / 全局事件。

slot 内多按钮（不可拖动）

设置 draggable: false 后，slot 内各按钮可独立 @click：

showGlobalFloat({ draggable: false, snap: 'none' })

<ba-float-global-host>
  <view class="toolbar">
    <view @click="onHome">首页</view>
    <view @click="onNotify">通知</view>
  </view>
</ba-float-global-host>

五、手势说明

六、常见问题

Q：切换页面后悬浮 UI 变了 / 不能点击？
A：常见原因：① 各页 host 不一致（演示页有 preset slot，其它页只有默认 shell）；② 单击/跳转的 uni.$on 只写在某一页，离开该页后失效；③ 多按钮模式须 draggable: false，但其它页 host 未渲染按钮 slot。
解决：封装统一业务宿主 + 在 App.onLaunch 注册全局 uni.$on（演示工程 initBaFloatGlobalEvents()）。页面卸载时 $off 必须传入同一函数引用，禁止无参 $off 清空全部监听。

Q：全局悬浮切页面后消失了？
A：目标页面根级缺少 <ba-float-global-host />。

Q：拖动时触发了点击？
A：slot 内不要绑 @tap；监听组件的 @tap 事件。若仍不满意，可考虑业务侧分区 UI（见 split 预设）。

Q：能否悬浮在其它 App 上方？
A：不能。本插件为应用内悬浮，非系统级悬浮窗。

Q：能否同时显示多个全局悬浮？
A：全局模式仅支持 1 个实例。页面内可同时使用多个 <ba-float-u>。

Q：如何加角标/红点？
A：在 slot 自定义 UI 或复制 preset 到业务目录后自行布局，绑定业务数据即可（见上文「方式 E」）。

Q：是否支持微信小程序？
A：不支持。仅 uni-app x App 端（Android / iOS / Harmony）。

更新日志

见 changelog.md