1. 这个需求为什么值得单独写一个组件
1.1 "能点"和"好用"之间隔着一大截
做过 uniapp 项目的朋友应该都有印象：产品经理口中的"悬浮按钮"，和开发者理解的那个"固定圆球"，经常是两回事。普通的position: fixed按钮只能固定在一个位置，但真实业务里，用户可能正在浏览商品详情、看长文章、填表单，固定的悬浮球很容易挡住关键内容。于是"可拖动浮动按钮"就成了一个高频但官方又没有原生支持的需求——很多 uniapp 项目里都能看到"在线客服""返回顶部""购物车""提问入口"这类悬浮球，几乎每个都要塞进一个能拖动的交互。
我第一次接到类似需求时，第一反应是去插件市场找现成库。翻了几个之后发现，绝大多数悬浮组件要么包的体积偏大，把一堆用不上的动画也带进来了，要么源码是给 React Native 或纯小程序写的，迁移到 uniapp 里各种报错，改起来比直接写还费劲。最后决定自己动手，花了小半天写了一个 FloatingButton 组件，不到两百行代码，H5、微信小程序、App 三端都能跑，后续还逐渐加上了边缘吸附、记住用户位置这些增强功能。这篇文章就把整个实现过程拆开讲清楚，包括拖动交互的核心原理、边界处理、多端兼容这些容易出坑的细节。
1.2 自研 vs 引入第三方库，我为什么选前者
先明确一点：不是所有场景都要自研。如果你的产品只是需要一个静态入口，比如固定在右下角的"意见反馈"，那 uniapp 自带的view加几个样式就搞定了，连组件都不用封装。真正需要自研的判断标准有两个：一是对交互有要求（可拖动、贴边、记忆位置），二是对包体积和代码可控性有要求。
第三方库的痛点，用下来基本集中在三个地方。第一，维护状态堪忧：插件市场很多组件两年不更新了，uniapp 每次升级编译器的版本，旧组件的兼容问题就暴露一次。第二，样式覆盖成本高：很多悬浮球组件内部自定义了图标、配色、角标逻辑，为了改成自己项目的视觉风格，得一层层深挖源码去覆盖样式，那过程比直接写一个还痛苦。第三，跨端表现不可预测：同一个第三方组件，在 H5 上拖动流畅，到了微信小程序里就出现抖动或 touch 事件失效，排查成本非常高。
自研的好处在于，核心代码完全掌握在自己手里，想加什么功能、修什么 bug，改起来都很快。其实一个可拖动浮动按钮的核心逻辑很简单，就是触摸事件加位移计算。只要理解了这套东西，后续不只是悬浮按钮，任何需要 Drag 交互的组件（比如可拖动的底部弹层、自定义页面的悬浮工具栏）都能复用同一套思路。
2. 可拖动交互背后的三件事：触摸事件、坐标换算、边界约束
2.1 触摸事件三件套的正确打开方式
在移动端实现拖动的核心，是监听三个事件：touchstart、touchmove、touchend。它们分别对应手指按下、手指移动、手指抬起三个阶段，和我们平时用鼠标拖动时监听mousedown、mousemove、mouseup的思路完全一致，只是移动端的坐标系、手势判定都要围绕触摸点来展开。
在 uniapp 的模板里，三个事件直接绑定到视图上：
<view @touchstart.stop="onTouchStart" @touchmove.stop.prevent="onTouchMove" @touchend.stop="onTouchEnd" > </view>这里有个非常关键的小细节：.stop修饰符。它的作用是阻止事件向父组件冒泡。因为悬浮按钮通常覆盖在页面内容之上，如果不阻止冒泡，触摸按钮时会同时触发它下面 ScrollView 的滚动事件，导致页面跟着上下滚，体验非常糟糕。在微信小程序端，.stop会被编译成catchtouchmove，这是唯一能有效阻止页面滚动的方案；在 H5 端，.stop相当于调用了event.stopPropagation()，配合.prevent阻止默认行为，也能起到类似效果。
事件回调里拿到的event.touches[0]是第一个触摸点，包含clientX和clientY，这两个值是相对于当前屏幕可视区域的坐标，也是我们做拖动计算的基础。要注意，在微信小程序里模拟器上滑动鼠标和真机手指触摸时，这两个值的来源不太一样，真机上还可能出现多点触控的情况，如果第二根手指也占了touches[0]，会导致坐标漂移。对于按钮拖动这种简单场景，通常只取第一个触摸点就够了，但心里要有这个意识。
2.2 从手指位移到按钮位移：坐标换算
可能有人会想：是不是每次touchmove时，把这次的位置和上一次的位置做个差值，然后累加到按钮的left和top上就行了？这种做法确实能动，但有一个隐患——连续的事件回调之间如果产生丢帧，累加式算法会慢慢积累误差，按钮轨迹就会和手指轨迹偏离，拖得越久偏得越离谱。
我用的方法是：记录起点，计算全程位移。在touchstart时，同时记录手指的起始坐标（startTouchX、startTouchY）和按钮的起始坐标（startPosX、startPosY）。然后在touchmove里算出手指移动的距离，加上按钮的起始坐标，就是按钮应该去的位置：
newX = startPosX + (currentTouchX - startTouchX) newY = startPosY + (currentTouchY - startTouchY)用生活例子类比：这就像拉着一条狗绳，你只关心狗一开始站在哪、你现在走到哪，至于中间它绕了多远，都不影响最终的位置计算。基于起点的算法每次都是从起始位置推导新位置，丢帧无非是中间少渲染几帧，最终位置依然精确。
判断是否真的开始拖动，不能在手一碰就触发。手指刚按下时可能只是轻微抖动，要是直接进入拖动态，点击就永远没机会触发了。所以通常设一个阈值，比如 6px：
if (Math.abs(dx) > this.threshold || Math.abs(dy) > this.threshold) { this.moved = true }超过这个阈值才认为是一次拖动，否则就按"点击"处理。这个阈值可以在组件里做成 prop，方便不同业务按需调整。
2.3 别让按钮飞出屏幕：边界约束与安全区
没有边界约束的话，按钮可以被拖到屏幕外一半，用户拖回来都不方便。因此每次计算完newX和newY，都要做一次夹取（clamp）：
this.posX = Math.max(0, Math.min(newX, this.winW - this.size)) this.posY = Math.max(this.safeTop, Math.min(newY, this.winH - this.size - this.safeBottom))这里的winW和winH是屏幕宽度和高度，通过uni.getSystemInfoSync()获取。很多人会忽略一个问题：windowWidth是逻辑像素还是物理像素？在 uniapp 中getSystemInfoSync()返回的是 rpx 转换后的逻辑像素值，也就是我们写 CSSpx时用的单位，所以直接用它来约束posX、posY没有问题。
但边界不只是屏幕边缘。iPhone 的刘海区域和底部 Home Indicator 区域，如果按钮拖到这些地方，会被遮挡或者触发系统误操作，所以在垂直方向还要额外考虑安全区。在 uniapp 中可以通过systemInfo.safeAreaInsets拿到四个方向的安全距离，把它作为上下边界的偏移量：
this.safeBottom = (sys.safeAreaInsets && sys.safeAreaInsets.bottom) || 0 this.safeTop = (sys.safeAreaInsets && sys.safeAreaInsets.top) || 0这样按钮在底部拖动时，最多只到 Home Indicator 上方；在顶部也不会钻进状态栏里。小程序和 App 端都支持这个字段，但个别低版本安卓机上safeAreaInsets可能是undefined，必须做兜底，用|| 0保证不报错。
3. 完整实现：一个零依赖的 FloatingButton 组件
3.1 先定组件的对外接口
写组件前先想清楚别人（包括未来的自己）怎么用它。我设计的接口有三个层次：
| 接口类型 | 名称 | 说明 |
|---|---|---|
| 属性 | initialX/initialY | 初始位置，默认右上角或右下角 |
| 属性 | size | 按钮直径，默认 88px |
| 属性 | text | 默认文案，用了插槽后会被覆盖 |
| 属性 | edgeSnap | 是否开启边缘吸附，默认开启 |
| 属性 | threshold | 点击和拖动的判定阈值，默认 6px |
| 事件 | click | 用户轻点按钮时触发 |
| 事件 | dragEnd | 拖动结束（松手后）触发，回传坐标 |
| 插槽 | 默认插槽 | 自定义按钮内部内容，适合放图标 |
把threshold暴露出来，是因为不同场景对拖动手感的敏感度不同。比如按钮很小、用户希望快速拖动时，阈值设小一点；按钮大、怕误操作时，阈值设大一点。很多现成组件把这些全部写死在内部，改起来很麻烦，不如一开始就设计成可配置项。
3.2 组件代码逐段拆解
直接给出完整组件，基于 vue2 语法，因为 uniapp 项目里 vue2 还是不少见的，vue3 的选项式 API 也基本兼容：
<template> <view class="fd-float" :class="{ 'fd-float--active': dragging }" :style="floatStyle" @touchstart.stop="onTouchStart" @touchmove.stop.prevent="onTouchMove" @touchend.stop="onTouchEnd" @click.stop="onClick" > <slot>{{ text }}</slot> </view> </template> <script> export default { name: 'FloatingButton', props: { initialX: { type: Number, default: 0 }, initialY: { type: Number, default: 0 }, size: { type: Number, default: 88 }, text: { type: String, default: '悬浮' }, edgeSnap: { type: Boolean, default: true }, threshold: { type: Number, default: 6 } }, data() { const sys = uni.getSystemInfoSync() const winW = sys.windowWidth const winH = sys.windowHeight return { posX: this.initialX || winW - this.size - 20, posY: this.initialY || winH - this.size - 100, startPosX: 0, startPosY: 0, startTouchX: 0, startTouchY: 0, dragging: false, moved: false, winW, winH, safeBottom: (sys.safeAreaInsets && sys.safeAreaInsets.bottom) || 0, safeTop: (sys.safeAreaInsets && sys.safeAreaInsets.top) || 0 } }, computed: { floatStyle() { return { left: this.posX + 'px', top: this.posY + 'px', width: this.size + 'px', height: this.size + 'px' } } }, methods: { onTouchStart(e) { const touch = e.touches[0] this.startTouchX = touch.clientX this.startTouchY = touch.clientY this.startPosX = this.posX this.startPosY = this.posY this.moved = false this.dragging = false }, onTouchMove(e) { if (this.startTouchX === null) return const touch = e.touches[0] const dx = touch.clientX - this.startTouchX const dy = touch.clientY - this.startTouchY if (!this.moved && (Math.abs(dx) > this.threshold || Math.abs(dy) > this.threshold)) { this.moved = true this.dragging = true } if (this.moved) { const newX = this.startPosX + dx const newY = this.startPosY + dy this.posX = Math.max(0, Math.min(newX, this.winW - this.size)) this.posY = Math.max( this.safeTop, Math.min(newY, this.winH - this.size - this.safeBottom) ) } }, onTouchEnd() { if (this.moved && this.edgeSnap) { const centerX = this.posX + this.size / 2 const targetX = centerX < this.winW / 2 ? 0 : this.winW - this.size this.posX = targetX this.$emit('dragEnd', { x: this.posX, y: this.posY }) } this.dragging = false this.startTouchX = null this.startTouchY = null }, onClick() { if (this.moved) { this.moved = false return } this.$emit('click') } } } </script> <style scoped lang="scss"> .fd-float { position: fixed; z-index: 9999; display: flex; align-items: center; justify-content: center; border-radius: 50%; background: linear-gradient(135deg, #2979ff, #1c6bff); color: #fff; font-size: 28rpx; box-shadow: 0 8rpx 20rpx rgba(41, 121, 255, 0.35); box-sizing: border-box; user-select: none; } .fd-float--active { box-shadow: 0 12rpx 32rpx rgba(41, 121, 255, 0.5); } </style>这段代码的核心逻辑集中在onTouchMove中：先判断是否真正进入拖动状态，再用"起点坐标 + 位移增量"的方式算出新位置，最后夹取边界。吸附逻辑放在onTouchEnd里，通过按钮中心点与屏幕中心点的比较，决定吸到左边还是右边。
有一点要特别说明：e.touches在touchend事件触发时已经被清空了，所以不要试图在onTouchEnd里读取e.touches[0]，拿到的会是undefined。如果需要手指的终点坐标，应该在touchmove里提前保存，或者用changedTouches。我在上面代码里onTouchEnd没有直接读终点坐标，而是基于posX做吸附判断，避开了这个坑。
3.3 页面接入与事件处理
组件封装完之后，在业务页面里的使用方式很简单：
<template> <view class="product-page"> <!-- 页面内容 --> <floating-button text="客服" :edge-snap="true" :size="80" @click="openCustomerService" @dragEnd="saveButtonPos" /> </view> </template> <script> import FloatingButton from '@/components/floating-button/index.vue' export default { components: { FloatingButton }, methods: { openCustomerService() { uni.navigateTo({ url: '/pages/customer-service/index' }) }, saveButtonPos(pos) { uni.setStorageSync('floatBtnPos', pos) } } } </script>如果你用的是 easycom 规则，组件放在components/floating-button/floating-button.vue路径下，连import和components注册都可以省掉，直接写<floating-button>标签就能用，这也是我非常推荐的方式，页面代码干净很多。
4. 从"能拖"到"好拖"：边缘吸附、点击判定与多端适配
4.1 松手自动吸附的算法选择
很多按钮拖动完之后，用户期望它自动贴到屏幕边缘，而不是停在屏幕中间挡内容。吸附的算法不复杂，核心是"判定按钮最终该靠左还是靠右"。
最简单有效的判定方式是看按钮中心点。如果按钮中心点位于屏幕中心线的左侧，就吸附到最左边；如果位于右侧，就吸附到最右边：
const centerX = this.posX + this.size / 2 const targetX = centerX < this.winW / 2 ? 0 : this.winW - this.size this.posX = targetX这个逻辑直白、性能好，不需要复杂的距离对比。如果你希望按钮吸附时同时保留一部分在屏幕外（常见的"半隐藏式悬浮球"），可以把0和winW - size改成-size * 0.3和winW - size * 0.7，效果类似抖音里那种拖到边缘只露一截的入口，点一下再弹出来。
吸附那一下的动画问题，也是从"能用"到"好用"的分水岭。直接用上面的代码赋值，按钮会瞬间跳过去，视觉上比较生硬。可以考虑加一个 transition：
.fd-float--snap { transition: left 0.25s ease, top 0.25s ease; }然后在touchstart时把snap类移除，touchend吸附时把snap类加上。这样既保证了拖动过程跟手（没有 transition 延迟），又让吸附动作变得顺滑。需要提醒的是，不要在拖动过程中一直开着transition: left，否则按钮会一直有一种"追不上手指"的滞后感，体验很糟糕。
4.2 区分单击与拖动：一个很容易翻车的细节
新手最容易踩的坑是：拖动结束松手后，系统又触发了一次click事件，导致按钮一边被拖动到新位置，一边执行了点击回调（比如弹出了客服窗口），用户直接看懵。
原因在于移动端的click事件并不是独立存在的，它是由touchstart、touchend合成出来的。所以哪怕你拖动了很远，只要手指没有滑出按钮的命中区域（或者浏览器判定条件不同），松开后依然可能触发click。
解决办法就是我代码里那个moved标志位。整个流程是：
touchstart时把moved置为false。touchmove中一旦位移超过阈值，把moved置为true。click回调里先检查moved，如果为true说明刚才是一次拖动，直接忽略并重置moved。
这个方案在微信小程序、H5、App 的 webview 渲染里都是有效的。但如果你在 nvue 页面里用了原生的渲染方式，还需要测试一下click事件的触发时序，因为在原生组件里 click 合成逻辑和 webview 不完全一样。稳妥起见，也可以在touchend里根据moved直接决定要不要派发点击事件，并主动preventDefault，双保险。
4.3 H5 / 微信小程序 / App 三端实测差异
三端都跑通之后，我把遇到的差异整理成一张表，可以给后面接手维护的人省不少事：
| 场景 | H5 | 微信小程序 | App（webview 渲染） |
|---|---|---|---|
| touch 事件可用性 | 支持，但要注意 passive 监听器 | 支持 | 支持 |
| 阻止页面滚动 | @touchmove.stop.prevent | 会被编译成 catchtouchmove，有效 | 视系统 webview 版本而定 |
| safeAreaInsets 支持 | 部分浏览器可返回 0 | 支持 | 部分安卓机型不支持 |
| dynamic left/top 更新 | 流畅 | 流畅 | 在低端安卓上可能轻微卡顿 |
| fixed 定位兼容性 | 正常 | 正常 | 正常 |
这里有一个 H5 端的坑要特别提醒：如果项目里给body或根节点绑定了touchmove监听器，并且没有设置{ passive: false }，那么浏览器的默认行为是禁止在touchmove里调用preventDefault的，导致页面滚动无法被阻止。在 uniapp 里，如果只是依赖.prevent修饰符，在某些浏览器下可能拦不住上下滑动，需要用事件监听重写的方式去处理，或者在页面根容器上也加一层滚动拦截。
微信小程序端还有一个容易出现的问题：自定义组件内部使用position: fixed没问题，但如果悬浮按钮组件被放在某个overflow: hidden的容器里，fixed 定位可能基于最近的 transform 容器而不是视口，造成位置偏移。我的经验是，尽量把 FloatingButton 放在页面最外层，避免嵌套在带transform、filter、perspective属性的父级里。
App 端在低版本安卓机上的表现，主要体现在性能。webview 渲染时，CSS 动画和频繁改left/top可能会触发大量重排，感觉就是按钮跟手度不够。这个问题在下一节会专门讲优化方案。
5. 上线前必做的几项优化
5.1 拖动性能：从 left/top 到 transform
left和top的改动会触发布局（reflow）和重绘（repaint），每帧做一次代价很高。尤其低端安卓机上，webview 的性能本来就有限，高频改变left/top很容易出现掉帧和卡顿。
业内标准的优化方案是用transform: translate3d(x, y, 0)代替left/top。transform不会触发布局相关流程，而是直接在合成器阶段处理，有 GPU 加速，动画性能和流畅度明显更好。
具体做法是：按钮始终固定在屏幕左上角（left: 0; top: 0），然后所有位置变化都通过transform来实现：
floatStyle() { return { transform: `translate3d(${this.posX}px, ${this.posY}px, 0)`, width: this.size + 'px', height: this.size + 'px' } }吸附动画的transition也只需要写成transform 0.25s ease，效果比过渡left/top更平滑。我之前在魅族 Note 这类低端机上做过对比，改成transform后触摸跟手度能明显提升，肉眼可见地从"纸片拖动"变成"实体物体移动"。
5.2 记住用户位置：本地存储小技巧
很多用户喜欢把悬浮球拖到自己顺手的拇指区域，如果每次进入页面按钮都默认回到右下角，用户得再拖一次，体验是打折扣的。所以在dragEnd时把位置存下来，下次进入页面直接读取，这个小功能成本很低、感知很强。
存和取的操作要放在组件内部还是业务页面里？我的建议是：组件内部做存取，对业务方完全透明。组件创建时读取存储：
const saved = uni.getStorageSync('floatBtnPos') const defaultX = this.initialX || (winW - this.size - 20) const defaultY = this.initialY || (winH - this.size - 100) data() { return { posX: saved ? saved.x : defaultX, posY: saved ? saved.y : defaultY, // ... } },dragEnd时写入：
this.$emit('dragEnd', { x: this.posX, y: this.posY }) uni.setStorageSync('floatBtnPos', { x: this.posX, y: this.posY })注意 localStorage 在 H5 端持久化没问题，但小程序端uni.setStorageSync有容量限制，单条数据通常限制在 1MB 以内，存一组坐标完全不用担心。还有就是不同页面如果用了同一个组件，位置是全局共享的，如果某个页面希望独立记忆，可以在组件 props 里加一个storageKey，有值就按 key 存，没有就不存。
5.3 无障碍与误触的补充处理
这块很容易被忽略，但真实用户场景里很影响体验。悬浮按钮是全局可点的入口，如果不做处理，在 iOS 的"辅助触控"开启时，系统自带的小球会和它打架，两个悬浮球叠在一起非常混乱。
另外还要注意：按钮钻到屏幕边缘时，用户点的时候可能因为目标太小误触旁边的内容。建议在按钮命中区域上做一些冗余设计，比如把可点击区域从视觉上的 88px 扩大到 100px，通过 padding 或者透明的伪元素实现，实际点击率会提升很多。拖动时也可以给按钮加一点 scale 变化，手指按下后有一个轻微放大的反馈，用户能明确感知到"这个球现在被我抓住了"。
还有一个细节是 Android 物理返回键。如果你的悬浮按钮承载的是"返回顶部"功能，应该监听onBackPress或者页面生命周期，在页面销毁时把事件清理干净，避免悬浮球还在但页面已经不在，点击回调报错。
我在实际项目里的体会是，浮动按钮这种小功能，写出来容易，写好却要过一遍边界、性能、跨端、交互反馈这些关。但正因为它是全局性的入口，几乎每个页面都会出现，所以花一两个小时打磨细节，后面省下来的维护时间绝对是值得的。如果你也打算在 uniapp 里实现类似功能，可以先把"能拖"跑通，再照着这篇文章补上吸附、安全区、性能优化这些环节——做完之后你会明显感觉到，它已经不是一个小按钮，而是一个让用户下意识觉得"顺手"的组件了。
