手势

概述

¥Overview

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

¥Ionic Gestures is a utility that allows developers to build custom gestures and interactions for their application in a platform agnostic manner. Developers do not need to be using a particular framework such as React or Angular, nor do they even need to be building an Ionic app! As long as developers have access to v5.0 or greater of Ionic Framework, they will have access to all of Ionic Animations.

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

¥Building complex gestures can be time consuming. Other libraries that provide custom gestures are often times too heavy handed and end up capturing mouse or touch events and not letting them propagate. This can result in other elements no longer being scrollable or clickable.

安装

¥Installation

JavaScript

Developers using Ionic Core and JavaScript should install the latest version of @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: ev => onMoveHandler(ev)
});

Angular

Developers using Ionic Core and TypeScript should install the latest version of @ionic/core.

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



...

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

Angular (Standalone)

Developers using Angular should install the latest version of @ionic/angular. Animations can be created via the AnimationController dependency injection.

By default, gesture callbacks do not run inside of NgZone. Developers can either set the runInsideAngularZone parameter to true when creating a gesture, or they can wrap their callbacks in an NgZone.run() call.

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

Developers using Angular should install the latest version of @ionic/angular. Animations can be created via the AnimationController dependency injection.

By default, gesture callbacks do not run inside of NgZone. Developers can either set the runInsideAngularZone parameter to true when creating a gesture, or they can wrap their callbacks in an NgZone.run() call.

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

Developers using React should install the latest version of @ionic/react. Full React wrappers are coming soon!

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



...

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

Developers using Ionic Vue should install the latest version of @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)
});

基本手势

¥Basic Gestures

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

¥In this example, our app listens for gestures on the ion-content element. When a gesture movement has started, the onStart function is called and a class is added to our ion-card to add a colored box shadow. When a gesture movement was detected, the onMove function is called and our app prints the current gesture information within the ion-card. Finally, when a gesture movement has ended, the onEnd function is called and the custom class is removed from our ion-card.

双击手势

¥Double Click Gesture

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

¥In the example below, we want to be able to detect double clicks on an element. By setting our threshold to 0, we can ensure our gesture object can detect clicks. Additionally, we define a click threshold so that only 2 clicks that occur in quick succession count as a double click.

手势动画

¥Gesture Animations

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

¥See our guide on implementing gesture animations: Gesture Animations with Ionic Animations

类型

¥Types

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

接口

¥Interfaces

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	检测到的手势类型。
开始 X	number	手势的起始 x 坐标。
启动 Y	number	手势的起始 y 坐标。
startTimeStamp	number	手势开始的时间戳。
当前 X	number	手势的当前 x 坐标。
当前 Y	number	手势的当前 y 坐标。
速度 X	number	手势当前在 x 轴上移动的速度。
速度 Y	number	手势当前在 y 轴上移动的速度。
德尔塔 X	number	自开始以来手势在 x 轴上移动了多少。
德尔塔 Y	number	自开始以来手势在 y 轴上移动了多少。
timeStamp	number	手势的当前时间戳。
event	UIEvent	由浏览器调度的原生事件。请参阅 UIEvent 了解更多信息。
data	any | undefined	用户指定的任何数据。这可以在任何回调中设置和读取。

方法

¥Methods

enable(enable: boolean = true) => void

启用或禁用手势。

¥Enable or disable the gesture.

destroy() => void

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

¥Destroy the gesture instance and stop listening on the target element.