更新记录

1.0.0（2026-08-15）

首个 UTS 正式版本：系统级悬浮球，可拖动、自动吸附（阈值可配置并记忆）、位置/颜色/大小/吸附全记忆、调色盘选色、点击动作自定义、参数即时刷新、权限一键引导，支持 Android 14。

平台兼容性

uni-app(3.8.2)

uni-app x(3.91)

其他

ZXB-FloatBall 悬浮球（UTS 插件）

让 uni-app App 显示一个系统层悬浮球（可拖动 + 点击回调），悬浮在所有 App 之上。

基于 uni-app x UTS 技术实现，功能与原原生 aar 插件完全等价。

功能

• ✅ 系统层悬浮（WindowManager TYPE_APPLICATION_OVERLAY，悬浮在所有 App 之上）
• ✅ 可拖动（拖动超过 10px 判定为拖动）
• ✅ 自动吸附（拖动结束时距四边 <阈值自动贴边，阈值可配置并记忆）
• ✅ 位置记忆（SharedPreferences 持久化，重启后显示在上次位置）
• ✅ 颜色记忆（选色后持久化，重启后保持上次颜色）
• ✅ 位置即时刷新（再次调用时传 x/y 立即移动悬浮球）
• ✅ 边界渐变（半透明灰描边 + 阴影过渡）
• ✅ 点击回调（未拖动且 <300ms 判定为点击 → 回调 JS { action: 'click', x, y }，含点击坐标）
• ✅ 点击动作可配置（回调自由实现：打开页面/弹窗/任意业务逻辑）
• ✅ 前台 Service + 常驻通知（悬浮球持续显示）
• ✅ 参数可配：球大小(dp) / 颜色 / 初始位置 / 吸附阈值
• ✅ 支持 Android 14（前台服务 specialUse 声明）

快速使用

import { showFloatBall, hideFloatBall, onClick } from '@/uni_modules/ZXB-FloatBall'

// 1. 显示悬浮球
//    color 不传 = 使用记忆颜色；x/y 传 0 = 使用记忆位置；snap 传 0 = 使用记忆吸附阈值
showFloatBall({ size: 60, color: '#5B9BFF', x: 0, y: 0, snap: 60 })

// 2. 注册点击回调（点击时收到 { action: 'click', x, y } 坐标，可自由配置动作）
onClick((res) => {
  console.log('悬浮球被点击', res)   // { action: 'click', x: 980, y: 1500 }
  if (res && res.x > 500) {
    uni.navigateTo({ url: '/pages/xxx/xxx' })   // 示例：点击打开页面
  } else {
    uni.showToast({ title: '点击', icon: 'none' })
  }
})

// 3. 隐藏悬浮球
hideFloatBall({})

参数说明

★记忆机制：位置/颜色/吸附阈值均持久化保存，设置后自动记忆，下次启动自动恢复。

重要：悬浮窗权限

Android 6+ 需要用户授权 "显示在其他应用上层"（SYSTEM_ALERT_WINDOW），否则悬浮球不显示。 调用前建议先检查并引导授权：

// 检查是否已授权悬浮窗权限
if (!plus.android.invoke('android.provider.Settings.canDrawOverlays', plus.android.runtime.startActivity)) {
  // 未授权 → 跳转悬浮窗权限设置页
  const Intent = plus.android.importClass('android.content.Intent')
  const Settings = plus.android.importClass('android.provider.Settings')
  const intent = new Intent(Settings.ACTION_MANAGE_OVERLAY_PERMISSION)
  plus.android.runtime.startActivity(intent)
}

使用步骤

1. 将 uni_modules/ZXB-FloatBall 复制到你的 uni-app 项目 uni_modules/ 目录
2. 制作自定义基座（插件注册了 Service/权限，标准基座跑不了）
3. 页面中 import 后调用（见上方示例）

常见问题

Q1：悬浮球不显示？

• 确认用户已授权"显示在其他应用上层"
• 查看日志：HBuilderX 控制台 Logcat 过滤 ZXBFloatBall，看是否有 "addView 失败"

Q2：点击没反应？

• 确认先调用了 onClick() 注册回调

Q3：iOS 能用吗？

• 不能。iOS 无系统层悬浮窗机制，iOS 平台调用为空实现（不报错、无效果）