更新记录

1.0.0（2025-09-17） 下载此版本

## [1.0.0] - 2025-09-17
### Added
-   初次发布。
-   实现单点手势：点击、双击、长按、拖拽、滑动。
-   实现多点触控手势：双指缩放、旋转。
-   提供丰富的手势数据（位移、速度、方向、比例、角度、中心点等）。
-   支持高度自定义配置（开关、阈值、时间间隔）。
-   提供作用域插槽用于响应式 UI 更新。
-   完善的事件系统。

平台兼容性

uni-app(3.6.9)

uni-app x(3.6.9)

其他

hy-gesture-recognizer 增强型手势识别器

一个功能强大、配置灵活的 uni-app 手势识别组件，支持单点与多点触控。

特性

• 👆 丰富的手势支持: 点击、双击、长按、拖拽、滑动、缩放、旋转。
• ⚙️ 高度可配置: 可自定义各种手势的阈值和参数。
• 🚀 高性能: 优化算法，流畅识别。
• 🌐 多端兼容: 支持 App、H5、各大小程序平台。
• 🔒 无权限依赖: 纯前端交互组件。

安装

通过 HBuilderX 的 uni_modules 导入本插件，或手动将本插件放入你项目的 uni_modules 目录下。

使用方法

基本使用

包裹你的组件，并监听需要的手势事件。

<template>
  <view>
    <hy-gesture-recognizer
      :enable-tap="true"
      :enable-double-tap="true"
      :enable-long-press="true"
      :enable-pan="true"
      :enable-swipe="true"
      :enable-pinch="true"
      :enable-rotate="true"
      @tap="onTap"
      @doubletap="onDoubleTap"
      @longpress="onLongPress"
      @pan="onPan"
      @swipe="onSwipe"
      @pinch="onPinch"
      @rotate="onRotate"
      @gesturestart="onGestureStart"
      @gesturechange="onGestureChange"
      @gestureend="onGestureEnd"
    >
      <!-- 你的可交互组件内容，例如一张图片、一个地图或一个自定义视图 -->
      <view class="gesture-target">在此区域进行手势操作</view>
    </hy-gesture-recognizer>
  </view>
</template>

<script>
export default {
  methods: {
    onTap(e) {
      console.log('Tap:', e);
      uni.showToast({ title: '点击了', icon: 'none' });
    },
    onDoubleTap(e) {
      console.log('Double Tap:', e);
      uni.showToast({ title: '双击了', icon: 'none' });
    },
    onLongPress(e) {
      console.log('Long Press:', e);
      uni.showToast({ title: '长按了', icon: 'none' });
    },
    onPan(e) {
      console.log('Pan - deltaX:', e.deltaX, 'deltaY:', e.deltaY);
      // 通常用于移动元素
    },
    onSwipe(e) {
      console.log('Swipe - direction:', e.direction);
      uni.showToast({ title: `向${e.direction}滑动`, icon: 'none' });
    },
    onPinch(e) {
      console.log('Pinch - scale:', e.scale);
      // 通常用于缩放元素
    },
    onRotate(e) {
      console.log('Rotate - rotation:', e.rotation);
      // 通常用于旋转元素
    },
    onGestureStart(e) {
      console.log('Gesture Started:', e.type);
    },
    onGestureChange(e) {
      // 实时更新
    },
    onGestureEnd(e) {
      console.log('Gesture Ended:', e.type);
    }
  }
};
</script>

<style>
.gesture-target {
  width: 300px;
  height: 300px;
  background-color: #f0f0f0;
  display: flex;
  justify-content: center;
  align-items: center;
  border: 1px dashed #ccc;
}
</style>

配置属性 (Props)

属性                  类型      默认值 说明
enable-tap          Boolean true    是否启用点击手势
enable-double-tap   Boolean false   是否启用双击手势
double-tap-interval Number  300     双击时间间隔（毫秒）
enable-long-press   Boolean false   是否启用长按手势
long-press-time     Number  500     长按触发时间（毫秒）
enable-pan          Boolean false   是否启用拖拽手势
enable-swipe        Boolean false   是否启用滑动手势
swipe-threshold     Number  10      滑动最小距离阈值（单位px）
enable-pinch        Boolean false   是否启用缩放手势
enable-rotate       Boolean false   是否启用手势
prevent-default     Boolean false   是否阻止默认事件

事件 (Events)

事件名          说明             回调参数
@tap            点击时触发           GestureEvent
@doubletap      双击时触发           GestureEvent
@longpress      长按时触发           GestureEvent
@pan            拖拽过程中持续触发   GestureEvent
@swipe          滑动结束时触发     GestureEvent
@pinch          缩放过程中持续触发   GestureEvent
@rotate         旋转过程中持续触发   GestureEvent
@gesturestart   任何手势开始时触发   GestureEvent
@gesturechange  任何手势变化时触发   GestureEvent
@gestureend     任何手势结束时触发   GestureEvent

GestureEvent 对象结构:

{
  type: string, // 手势类型 ('tap', 'swipe', 'pinch'等)
  state: string, // 状态 ('start', 'move', 'end')
  pointers: Array<{ identifier: number, x: number, y: number }>, // 当前触点
  startPointers: Array<{ identifier: number, x: number, y: number }>, // 起始触点
  scale: number, // 缩放比例
  rotation: number, // 旋转角度（度数）
  deltaX: number, // X轴位移
  deltaY: number, // Y轴位移
  velocityX: number, // X轴速度
  velocityY: number, // Y轴速度
  direction: string, // 方向 ('left', 'right', 'up', 'down', 'none')
  center: { x: number, y: number }, // 手势中心点
  timeStamp: number, // 时间戳
  nativeEvent: TouchEvent // 原生事件对象
}

作用域插槽 (Scoped Slot)

组件提供了作用域插槽，可将手势数据传递给子组件，实现更灵活的响应式交互。

<hy-gesture-recognizer :enable-pinch="true" :enable-rotate="true">
  <template #default="{ gestureData }">
    <view
      class="transformable-element"
      :style="{
        transform: `scale(${gestureData.scale}) rotate(${gestureData.rotation}deg)`
      }"
    >
      根据手势数据实时变换的元素
    </view>
  </template>
</hy-gesture-recognizer>

注意事项

1.手势冲突: 如果父容器有滚动条，某些拖拽或滑动手势可能会触发页面滚动。可以通过 prevent-default 属性尝试阻止默认行为，或在特定条件下手动控制。
2.性能考虑: 高频触发的事件（如 pan, pinch, rotate）中不要执行过于复杂的逻辑，以免造成页面卡顿。
3.平台差异: 虽然组件已处理多端兼容性，但不同平台底层 Touch 事件的细微差异仍可能存在。