手勢

概觀

Ionic 手勢是一個工具，可讓開發人員以與平台無關的方式，為其應用程式建構自訂手勢和互動。開發人員不需要使用特定的框架，例如 React 或 Angular，甚至不需要建構 Ionic 應用程式！只要開發人員可以存取 Ionic Framework v5.0 或更高版本，他們就可以存取所有 Ionic 動畫。

建構複雜的手勢可能很耗時。其他提供自訂手勢的程式庫通常太過笨重，最終會捕獲滑鼠或觸控事件，而不讓它們傳播。這可能會導致其他元素無法再捲動或點擊。

安裝

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: 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，我們可以確保我們的手勢物件可以偵測點擊。此外，我們定義了一個點擊閾值，以便只有快速連續發生的 2 次點擊才會算作雙擊。

手勢動畫

請參閱我們關於實作手勢動畫的指南：使用 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

銷毀手勢實例並停止監聽目標元素。