手势

概述

Ionic Gestures 是一个工具，它允许开发者以平台无关的方式为他们的应用程序构建自定义手势和交互。开发者不需要使用特定的框架，例如 React 或 Angular，甚至不需要构建 Ionic 应用！只要开发者能够使用 Ionic Framework v5.0 或更高版本，他们就可以使用 Ionic Gestures 的全部功能。

构建复杂的手势可能非常耗时。其他提供自定义手势的库通常过于笨重，最终会捕获鼠标或触摸事件并阻止它们传播。这可能导致其他元素无法滚动或点击。

安装

JavaScript

使用 Ionic Core 和 JavaScript 的开发者应安装最新版本的 @ionic/core。

import { createGesture } from 'https://cdn.jsdelivr.net/npm/@ionic/core@latest/dist/esm/index.mjs';

...

const gesture = createGesture({
  el: elementRef,
  threshold: 15,
  gestureName: 'my-gesture',
  onMove: event => onMoveHandler(event)
});

Angular

使用 Ionic Core 和 TypeScript 的开发者应安装最新版本的 @ionic/core。

import { createGesture, Gesture } from '@ionic/core';

...

const gesture: Gesture = createGesture({
  el: elementRef,
  threshold: 15,
  gestureName: 'my-gesture',
  onMove: event => onMoveHandler(event)
});

Angular (Standalone)

使用 Angular 的开发者应安装最新版本的 @ionic/angular。可以通过 GestureController 依赖注入来创建手势。

默认情况下，手势回调不会在 NgZone 内运行。开发者可以在创建手势时将 runInsideAngularZone 参数设置为 true，或者将他们的回调包装在 NgZone.run() 调用中。

import { Gesture, GestureController } from '@ionic/angular';

...

constructor(private gestureCtrl: GestureController) {
  const gesture: Gesture = this.gestureCtrl.create({
    el: this.element.nativeElement,
    threshold: 15,
    gestureName: 'my-gesture',
    onMove: event => this.onMoveHandler(event)
  }, true);
  // 上面的 `true` 确保回调在 NgZone 内运行。
}

React

使用 Angular 的开发者应安装最新版本的 @ionic/angular。可以通过 GestureController 依赖注入来创建手势。

默认情况下，手势回调不会在 NgZone 内运行。开发者可以在创建手势时将 runInsideAngularZone 参数设置为 true，或者将他们的回调包装在 NgZone.run() 调用中。

import { Gesture, GestureController } from '@ionic/angular/standalone';

...

constructor(private gestureCtrl: GestureController) {
  const gesture: Gesture = this.gestureCtrl.create({
    el: this.element.nativeElement,
    threshold: 15,
    gestureName: 'my-gesture',
    onMove: event => this.onMoveHandler(event)
  }, true);
  // 上面的 `true` 确保回调在 NgZone 内运行。
}

Vue

使用 React 的开发者应安装最新版本的 @ionic/react。完整的 React 封装即将推出！

import { createGesture, Gesture } from '@ionic/react';

...

const gesture: Gesture = createGesture({
  el: elementRef,
  threshold: 15,
  gestureName: 'my-gesture',
  onMove: event => onMoveHandler(event)
});

使用 Ionic Vue 的开发者应安装最新版本的 @ionic/vue。

import { createGesture } from '@ionic/vue';
import { ref } from 'vue';

...

const elementRef = ref();

...

const gesture = createGesture({
  el: elementRef.value,
  threshold: 15,
  gestureName: 'my-gesture',
  onMove: event => onMoveHandler(event)
});

基本手势

在这个例子中，我们的应用监听 ion-content 元素上的手势。当手势移动开始时，会调用 onStart 函数，并向我们的 ion-card 添加一个类来添加彩色盒阴影。当检测到手势移动时，会调用 onMove 函数，我们的应用会在 ion-card 中打印当前的手势信息。最后，当手势移动结束时，会调用 onEnd 函数，并从我们的 ion-card 中移除自定义类。

双击手势

在下面的例子中，我们希望能够检测元素上的双击。通过将 threshold 设置为 0，我们可以确保手势对象能够检测点击。此外，我们定义了一个点击阈值，以便只有快速连续发生的两次点击才被算作双击。

手势动画

查看我们关于实现手势动画的指南：使用 Ionic Animations 实现手势动画

类型

名称	值
GestureCallback	(detail: GestureDetail) => boolean | void

接口

GestureConfig

属性	类型	默认值	描述
el	Node	undefined	监听手势的元素。
disableScroll	boolean | undefined	false	如果为 true，则在手势启用时禁用 el 上的滚动。
direction	'x' | 'y' | undefined	'x'	将手势检测限制在特定轴向上的移动。
gestureName	string	undefined	要创建的手势名称。
gesturePriority	number | undefined	0	优先级更高的手势将覆盖优先级更低的手势。这对于确保多个手势不会相互冲突非常有用。
passive	boolean | undefined	true	如果为 true，则表示该手势永远不会调用 preventDefault()。这可用于提高滚动性能。更多信息请参见 Passive Listeners。
maxAngle	number | undefined	40	检测手势时允许的最大角度。
threshold	number | undefined	10	定义指针在手势开始前必须移动多少距离。
blurOnStart	boolean | undefined	undefined	如果为 true，手势将在触发 onStart 回调之前模糊任何活动的可选中元素，例如输入框或文本域。
canStart	GestureCallback | undefined	undefined	一个回调函数，如果允许手势开始则返回 true。
onWillStart	(detail: GestureDetail) => Promise<void>	undefined	手势即将开始时触发的回调。这在 canStart 之后、onStart 之前触发。
onStart	GestureCallback | undefined	undefined	手势开始时触发的回调。
onMove	GestureCallback | undefined	undefined	检测到手势移动时触发的回调。
onEnd	GestureCallback | undefined	undefined	手势结束时触发的回调。这通常发生在指针被释放时。
notCaptured	GestureCallback | undefined	undefined	手势未被捕获时触发的回调。这通常发生在存在优先级更高的冲突手势时。

GestureDetail

属性	类型	描述
type	string	检测到的手势类型。
startX	number	手势的起始 x 坐标。
startY	number	手势的起始 y 坐标。
startTimeStamp	number	手势开始的时间戳。
currentX	number	手势的当前 x 坐标。
currentY	number	手势的当前 y 坐标。
velocityX	number	手势当前在 x 轴上的移动速度。
velocityY	number	手势当前在 y 轴上的移动速度。
deltaX	number	手势开始以来在 x 轴上移动的距离。
deltaY	number	手势开始以来在 y 轴上移动的距离。
timeStamp	number	手势的当前时间戳。
event	UIEvent	浏览器分发的原生事件。更多信息请参见 UIEvent。
data	any | undefined	用户指定的任何数据。这可以在任何回调中设置和读取。

方法

enable(enable: boolean = true) => void

启用或禁用手势。

destroy() => void

销毁手势实例并停止监听目标元素。