灵动悬浮球·可拖拽环形菜单

更新记录

1.0.1（2026-05-07）下载此版本

优化初始Y安全
修复 movableAreaTop 不生效问题
修复 movableAreaBottom 不生效问题

1.0.0（2026-05-06）下载此版本

支持自由拖拽，松手自动吸附屏幕边缘
环形菜单展开，可自定义菜单项数量与样式
智能防溢出，菜单自动避开四角边界
支持 emoji 或自定义图片（圆角/不规则原形）
完全兼容微信小程序、H5、App（含鸿蒙）
提供丰富属性调节：大小、颜色、阴影、动画

平台兼容性

uni-app(3.7.8)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
√	√	√	√	√	√	√	√	√

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
√	-	-	-	-	-	-	-	-	-	-	-

📦 UniApp 插件：`sea-float-button`

一个高性能、可自由拖拽、自动边缘吸附的悬浮按钮组件，支持自定义图标（包括不规则 PNG 图片）、展开子菜单，完美兼容微信小程序、H5、App（含鸿蒙）。

⚙️ 属性说明

属性名	类型	默认值	说明
size	Number	52	按钮大小（px）
bgColor	String	'#4A90D9'	背景色，支持 `transparent`
icon	String	'＋'	图标，支持 emoji / 图片路径
round	Boolean	true	是否裁剪为圆形（关闭后可显示不规则图片）
shadow	String	'0 2px 12px...'	按钮阴影 CSS 值
initialX	String\|Number	'right'	初始 X 位置，`'left'`/`'right'`/具体数值(px)
initialY	String\|Number	'middle'	初始 Y 位置，`'top'`/`'middle'`/`'bottom'`/数值(px)
snapToEdge	Boolean	true	松手后是否自动吸附至左右边缘
edgeMargin	Number	12	吸附后距屏幕边缘的距离（px）
movableAreaTop	Number	0	顶部不可拖动区域高度（如导航栏）
movableAreaBottom	Number	0	底部不可拖动区域高度（如 tabBar）
zIndex	Number	999	元素层级
disabled	Boolean	false	是否禁用拖拽
animation	Boolean	true	吸附时是否使用过渡动画
menuItems	Array	[]	子菜单项数组，每项包含 `{ id, icon, text, color }`
menuItemSize	Number	42	子菜单项大小（px）
subMenuColor	String	'#ffffff'	子菜单项默认背景色
menuGap	Number	12	子菜单项之间的间距（px）

📡 事件

事件名	参数	说明
click	-	点击按钮（非拖拽）时触发
change	`{ x, y }`	按钮位置变化时实时触发
menuClick	`{ item, index }`	点击子菜单项时触发
menuOpen	-	菜单展开时触发
menuClose	-	菜单关闭时触发
dragStart	-	开始拖拽时触发
dragEnd	`{ x, y }`	拖拽结束并完成吸附后触发

🧩 插槽

默认插槽可以完全自定义按钮内容（此时 icon 属性会被覆盖）：

<sea-float-button>
  <view class="custom-content">自定义</view>
</sea-float-button>

🛠 外部方法（通过 ref 调用）

<sea-float-button ref="btn" />

this.$refs.btn.setPosition(100, 200);   // 设置位置
const pos = this.$refs.btn.getPosition(); // 获取当前位置
this.$refs.btn.toggleMenu();            // 切换菜单显示

📱 平台支持

平台	拖拽支持	说明
微信小程序	✅ 触摸拖拽	真机测试通过，开发者工具可能不跟手
H5 (移动端)	✅ 触摸拖拽	完全流畅
H5 (PC 端)	⚠️ 需额外适配	本版本仅含触摸事件，PC 拖拽可自行扩展鼠标事件（参考条件编译）
App (Vue)	✅ 触摸拖拽	完全支持，含鸿蒙
支付宝/百度/抖音小程序	✅	逻辑相同，可兼容

❓ 常见问题

1. 微信开发者工具拖不动？
工具内用鼠标模拟触摸有延迟，请用手机扫码真机预览。

2. 按钮有方框/边框？
设置 bg-color="transparent" shadow="none" 并确保图片为透明底 PNG，同时组件内部已强制 border: 0。

3. 如何避开顶部导航栏？
通过 movable-area-top 设置导航栏高度（如 44），按钮将被限制在该区域以下。

4. 不规则图片（如小狗）被裁剪？
将 round 设为 false，按钮将保留图片原始形状。

5. 按钮位置突然跳变？
检查是否有其他元素（如 scroll-view）拦截了触摸事件；确认 snapToEdge 值符合预期，该属性只在松手后执行。

📁 文件结构建议

src/
  components/
    sea-float-button/
      sea-float-button.vue

引入时使用：

import SeaFloatButton from '@/components/sea-float-button/sea-float-button.vue';

现在您可以将 sea-float-button 插件直接用于项目，拖拽功能稳定、细节到位、兼容主流平台，如有任何定制需求，欢迎随时提出！