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.stoponTouchStart touchmove.stop.preventonTouchMove touchend.stoponTouchEnd /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)用生活例子类比这就像拉着一条狗绳你只关心狗一开始站在哪、你现在走到哪至于中间它绕了多远都不影响最终的位置计算。基于起点的算法每次都是从起始位置推导新位置丢帧无非是中间少渲染几帧最终位置依然精确。判断是否真的开始拖动不能在手一碰就触发。手指刚按下时可能只是轻微抖动要是直接进入拖动态点击就永远没机会触发了。所以通常设一个阈值比如 6pxif (Math.abs(dx) this.threshold || Math.abs(dy) this.threshold) { this.moved true }超过这个阈值才认为是一次拖动否则就按点击处理。这个阈值可以在组件里做成 prop方便不同业务按需调整。2.3 别让按钮飞出屏幕边界约束与安全区没有边界约束的话按钮可以被拖到屏幕外一半用户拖回来都不方便。因此每次计算完newX和newY都要做一次夹取clampthis.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 classfd-float :class{ fd-float--active: dragging } :stylefloatStyle touchstart.stoponTouchStart touchmove.stop.preventonTouchMove touchend.stoponTouchEnd click.stoponClick 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 langscss .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 classproduct-page !-- 页面内容 -- floating-button text客服 :edge-snaptrue :size80 clickopenCustomerService dragEndsaveButtonPos / /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微信小程序Appwebview 渲染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 到 transformleft和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 里实现类似功能可以先把能拖跑通再照着这篇文章补上吸附、安全区、性能优化这些环节——做完之后你会明显感觉到它已经不是一个小按钮而是一个让用户下意识觉得顺手的组件了。
uniapp可拖动悬浮按钮组件实现：触摸事件、边界吸附与多端兼容
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.stoponTouchStart touchmove.stop.preventonTouchMove touchend.stoponTouchEnd /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)用生活例子类比这就像拉着一条狗绳你只关心狗一开始站在哪、你现在走到哪至于中间它绕了多远都不影响最终的位置计算。基于起点的算法每次都是从起始位置推导新位置丢帧无非是中间少渲染几帧最终位置依然精确。判断是否真的开始拖动不能在手一碰就触发。手指刚按下时可能只是轻微抖动要是直接进入拖动态点击就永远没机会触发了。所以通常设一个阈值比如 6pxif (Math.abs(dx) this.threshold || Math.abs(dy) this.threshold) { this.moved true }超过这个阈值才认为是一次拖动否则就按点击处理。这个阈值可以在组件里做成 prop方便不同业务按需调整。2.3 别让按钮飞出屏幕边界约束与安全区没有边界约束的话按钮可以被拖到屏幕外一半用户拖回来都不方便。因此每次计算完newX和newY都要做一次夹取clampthis.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 classfd-float :class{ fd-float--active: dragging } :stylefloatStyle touchstart.stoponTouchStart touchmove.stop.preventonTouchMove touchend.stoponTouchEnd click.stoponClick 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 langscss .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 classproduct-page !-- 页面内容 -- floating-button text客服 :edge-snaptrue :size80 clickopenCustomerService dragEndsaveButtonPos / /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微信小程序Appwebview 渲染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 到 transformleft和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 里实现类似功能可以先把能拖跑通再照着这篇文章补上吸附、安全区、性能优化这些环节——做完之后你会明显感觉到它已经不是一个小按钮而是一个让用户下意识觉得顺手的组件了。
