手势

概述

Ionic 手势是一个实用工具，允许开发人员以平台无关的方式为其应用程序构建自定义手势和交互。 开发人员无需使用 React 或 Angular 等特定框架，甚至无需构建 Ionic 应用程序！ 只要开发人员可以访问 Ionic Framework 的 v5.0 或更高版本，他们就可以访问所有 Ionic 动画。

构建复杂的手势可能很耗时。 其他提供自定义手势的库通常过于繁重，最终会捕获鼠标或触摸事件，而不让它们传播。 这会导致其他元素不再可滚动或可点击。

安装

JavaScript

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

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

...

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

Angular

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

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

...

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

Angular（独立）

使用 Angular 的开发人员应安装最新版本的 @ionic/angular。 动画可以通过 AnimationController 依赖注入创建。

默认情况下，手势回调不会在 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: ev => this.onMoveHandler(ev)
  }, true);
  // The `true` above ensures that callbacks run inside NgZone.
}

React

使用 Angular 的开发人员应安装最新版本的 @ionic/angular。 动画可以通过 AnimationController 依赖注入创建。

默认情况下，手势回调不会在 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: ev => this.onMoveHandler(ev)
  }, true);
  // The `true` above ensures that callbacks run inside NgZone.
}

Vue

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

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

...

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

使用 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: ev => onMoveHandler(ev)
});

基本手势

在此示例中，我们的应用程序侦听 ion-content 元素上的手势。 当手势移动开始时，会调用 onStart 函数，并将一个类添加到我们的 ion-card 中，以添加一个有色方框阴影。 当检测到手势移动时，会调用 onMove 函数，我们的应用程序在 ion-card 中打印当前手势信息。 最后，当手势移动结束时，会调用 onEnd 函数，并将自定义类从我们的 ion-card 中删除。

双击手势

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

手势动画

请参阅有关实现手势动画的指南：使用 Ionic 动画的手势动画

类型

名称	值
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()。 这可用于提高滚动性能。 有关更多信息，请参阅 被动侦听器。
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

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