移动端 H5 页面与桌面端开发最大的不同在于，视口尺寸、像素密度和交互方式都呈现出碎片化特征。Vue 3 提供了灵活的组合式 API，但框架本身并不解决终端适配和手势交互问题。如果只是简单写死 px 或依赖浏览器默认行为，上线后很可能会遇到元素过大、点击延迟、滑动不跟手等情况。因此从项目搭建阶段就规划好适配策略，并把手势逻辑抽离成可复用模块，能显著减少后期返工。
这里先厘清一个基本事实：移动端 H5 的布局单位选择与手势事件处理是两条相对独立的链路。适配方案主要解决视觉呈现的一致性问题，而手势封装则解决交互行为的一致性与健壮性。两者可以并行设计，但需要在组件层做好衔接。下面先看适配方案如何落地。
一、移动端适配方案选型与项目配置
目前主流的移动端适配思路大体分为三种：纯 vw/vh 方案、rem 动态方案以及基于 PostCSS 的 px 转 viewport 方案。纯 vw/vh 写法比较直观，但在有些设计稿中需要频繁进行百分比换算，开发效率一般。rem 方案通过动态设置 html 的 font-size 来实现等比缩放，曾经是兼容性最好的选择，但需要引入 flexible 脚本，并且在 Vue 3 项目中与组件库的默认单位可能产生冲突。
在 Vue 3 工程中，更推荐使用 postcss-px-to-viewport 插件。它允许开发者在样式表中继续使用 px 书写，构建阶段自动转换为 vw 单位，既能保持设计稿的还原度，又避免了手动换算。以 Vite 项目为例，可以在 vite.config.ts 中配置 PostCSS：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import pxToViewport from 'postcss-px-to-viewport'
export default defineConfig({
plugins: [vue()],
css: {
postcss: {
plugins: [
pxToViewport({
viewportWidth: 375,
unitPrecision: 5,
viewportUnit: 'vw',
selectorBlackList: ['.ignore', '.hairlines'],
minPixelValue: 1,
mediaQuery: false,
exclude: /node_modules/i
})
]
}
}
})
其中 viewportWidth 通常设置成设计稿宽度，375 是多数移动端设计稿的标准尺寸。selectorBlackList 用来排除不需要转换的类名，比如某些第三方组件的样式或需要保持 px 的边框。exclude 规则可以跳过 node_modules，避免组件库样式被二次转换导致样式错乱。这种方案的优点很明显：代码可读性强，设计稿中的 px 值可以直接照搬，构建后的页面在不同宽度设备上自动按比例缩放。
不过仅靠 px 转 vw 还不够，还需要处理两个细节。第一是高清屏下的 1px 边框问题。由于物理像素与逻辑像素的比例关系，直接写 1px 在某些 dpr 为 2 或 3 的设备上可能显得偏粗或发虚。实践中通常会结合伪元素加 transform: scale(0.5) 的方式实现细边框，或者使用插件提供的 hairlines 功能。第二是安全区域，尤其是 iPhone 的刘海屏和底部横条区域。可以在 CSS 中使用 env(safe-area-inset-bottom) 给固定底栏增加内边距，配合 viewport-fit=cover 让页面在全面屏上充分利用空间。
二、移动端手势事件模型与 Vue 3 组合式封装
浏览器原生提供了 touch 系列事件，包括 touchstart、touchmove 和 touchend，此外还有用于多点触控的 touches 列表。不过 touch 事件存在一些天然短板：不同浏览器对事件的实现细节不一致，iOS 和 Android 在滚动、事件取消等行为上也可能有差异。后来 W3C 又推出了 Pointer Events，将鼠标、触摸和触控笔统一到同一套模型中，pointerdown、pointermove、pointerup 逐渐成为更现代的选择。但对移动端 H5 而言，如果只需要支持主流移动浏览器，touch 事件的兼容性和可控性仍然足够。
封装手势逻辑的最佳方式是利用 Vue 3 的组合式函数。一个典型的使用场景是滑动切换卡片或轮播图。我们把 touchstart 时记录的坐标与 touchmove 过程中的实时坐标进行比较，当位移超过阈值时判定为有效滑动，并在 touchend 时根据方向触发回调。以下是一个基础的 useSwipe 组合式函数：
import { ref, onMounted, onBeforeUnmount } from 'vue'
export function useSwipe(targetRef, options = {}) {
const threshold = options.threshold || 50
const direction = ref('')
const distance = ref({ x: 0, y: 0 })
let startX = 0
let startY = 0
let isSwiping = false
function handleStart(e) {
const touch = e.touches[0]
startX = touch.clientX
startY = touch.clientY
isSwiping = true
direction.value = ''
}
function handleMove(e) {
if (!isSwiping) return
const touch = e.touches[0]
const deltaX = touch.clientX - startX
const deltaY = touch.clientY - startY
distance.value = { x: deltaX, y: deltaY }
if (Math.abs(deltaX) > threshold || Math.abs(deltaY) > threshold) {
direction.value = Math.abs(deltaX) > Math.abs(deltaY)
? (deltaX > 0 ? 'right' : 'left')
: (deltaY > 0 ? 'down' : 'up')
}
}
function handleEnd(e) {
isSwiping = false
if (options.onSwipe && direction.value) {
options.onSwipe(direction.value, distance.value)
}
direction.value = ''
distance.value = { x: 0, y: 0 }
}
onMounted(() => {
const el = targetRef.value
if (!el) return
el.addEventListener('touchstart', handleStart, { passive: true })
el.addEventListener('touchmove', handleMove, { passive: true })
el.addEventListener('touchend', handleEnd)
el.addEventListener('touchcancel', handleEnd)
})
onBeforeUnmount(() => {
const el = targetRef.value
if (!el) return
el.removeEventListener('touchstart', handleStart)
el.removeEventListener('touchmove', handleMove)
el.removeEventListener('touchend', handleEnd)
el.removeEventListener('touchcancel', handleEnd)
})
return { direction, distance }
}
这里将 touchmove 和 touchstart 注册为 passive 模式，主要是为了避免浏览器在滚动容器中对 touchmove 的默认行为产生警告，同时也提升了滚动性能。但被动模式意味着无法在事件回调中调用 preventDefault 来阻止页面滚动。如果业务需要完全接管手势，比如自定义滑动组件要阻止页面跟随滚动，可以改为非 passive 模式，并在组件外层设置 touch-action: none。另外在判断方向时存在一个细节：只有位移超过阈值才设置 direction，否则轻微的点击或抖动也可能被误判为滑动。
这套组合式函数可以直接在组件中复用。Vue 3 的响应式变量 direction 和 distance 会驱动模板更新，开发者无需手动管理事件绑定与解绑的生命周期。当需要在多个组件中使用手势时，抽离成 useSwipe 能显著降低重复代码。如果还要支持双指缩放，可以进一步扩展，利用 touches 列表计算两个触点之间的距离变化，并在缩放过程中实时返回 scale 值。
三、把手势逻辑封装成可交互的 Vue 3 组件
仅有组合式函数还不够，很多场景下希望直接拿到一个具备手势能力的组件，比如可拖拽的抽屉、可滑动删除的列表项或可缩放预览的图片容器。我们可以基于前面的 useSwipe 再封装一层模板和样式，形成真正意义上的手势组件。以一个支持左右滑动切换的卡片组件为例：
<template>
<div ref="cardRef" class="swipe-card">
<div class="swipe-track" :style="trackStyle">
<div v-for="item in items" :key="item.id" class="swipe-item">
{{ item.text }}
</div>
</div>
</div>
</template>
<script setup>
import { ref, computed } from 'vue'
import { useSwipe } from './useSwipe'
const props = defineProps({
items: { type: Array, required: true }
})
const cardRef = ref(null)
const currentIndex = ref(0)
const offsetX = ref(0)
const trackStyle = computed(() => ({
transform: `translateX(calc(-${currentIndex.value * 100}% + ${offsetX.value}px))`,
transition: offsetX.value === 0 ? 'transform 0.25s ease' : 'none'
}))
useSwipe(cardRef, {
threshold: 40,
onSwipe: (direction) => {
if (direction === 'left' && currentIndex.value < props.items.length - 1) {
currentIndex.value++
} else if (direction === 'right' && currentIndex.value > 0) {
currentIndex.value--
}
offsetX.value = 0
}
})
</script>
这个组件将 touch 事件绑定在根元素上，通过 transform 实现轨道位移。需要注意代码中使用了 Vue 模板语法，在实际的 .vue 文件里不需要做 HTML 转义。这里因为放在 pre 代码块中展示，所以将 < 和 > 转义成了 < 和 >。在开发环境中你应该看到的是正常的尖括号。
另一个高频需求是图片预览中的双指缩放。实现思路是在 touchstart 中记录两个触点的初始距离，在 touchmove 中计算当前距离与初始距离的比值，并把这个比值映射到 CSS transform: scale 上。同时还需要处理缩放中心，否则图片会从左上角缩放而不是围绕手势中心。Vue 3 中可以借助 computed 把 scale 和 translate 组合成一个 transform 字符串，配合 transition 在 touchend 时回弹到合理范围。
手势组件封装过程中最容易踩的坑是手势冲突。比如在一个可滑动的卡片内部又嵌套了一个可纵向滚动的列表，浏览器需要判断用户到底是想横向切换还是纵向滚动。通常的解决办法是引入方向锁定机制：在手势开始的前几十毫秒内，先收集位移增量，一旦判断出主要方向，就禁用另一个方向的滚动。具体可以通过动态设置 touch-action 或调用 preventDefault 来控制。Vue 3 的指令系统也很适合做这类低层交互封装，比如 v-swipe、v-longpress 等，能让模板中的手势声明更简洁。
四、性能优化与真机调试建议
移动端手势交互对性能非常敏感。touchmove 事件触发频率很高，如果回调中执行大量计算或直接修改响应式状态，可能导致页面掉帧。Vue 3 的响应式更新本身有一定开销，合理做法是在 move 过程中只更新必要的轻量 ref，不触发大型 computed 或强制重排。也可以使用 requestAnimationFrame 合并多次状态更新，避免在一次事件循环中重复渲染。unref 和 shallowRef 在频繁更新的场景下可能比 ref 更合适，因为 shallowRef 不会做深层代理，能减少响应式追踪成本。
在真实设备上调试时还要注意浏览器的差异。iOS Safari 的手势事件在页面有弹性滚动时可能触发 touchcancel，如果不处理会导致手势状态一直停留在进行中。Android 浏览器则可能由于厂商定制出现 touch 事件延迟或重复触发。建议在 touchend 和 touchcancel 中都执行清理逻辑，保证状态机收敛。另外，测试时关闭浏览器的双击缩放和文本选择，给容器设置 user-select: none 和 -webkit-touch-callout: none，可以避免长按图片弹出系统菜单干扰自定义手势。
最后，适配方案和手势封装都不是一次性工作。随着设备形态变化，比如折叠屏、大屏手机以及桌面端触摸屏的普及，viewport 和交互策略需要持续调整。Vue 3 的组合式 API 为这些逻辑的复用和替换提供了很好的基础，把适配参数和手势行为抽离到统一的 composable 中，后续无论是切换单位方案还是新增手势类型，都能在不破坏组件结构的前提下完成。把基础打牢，移动端 H5 的体验才能稳定可靠。