處理多點觸控手勢

試試 Compose 的方式

Jetpack Compose 是 Android 推薦的 UI 工具包。瞭解如何在 Compose 中使用觸控和輸入功能。

Multi-touch 手勢 →

多點觸控手勢是指同時使用多個指標 (手指) 輕觸螢幕。本文將說明如何偵測涉及多個指標的手勢。

追蹤多個指標

當多個指標同時輕觸螢幕時，系統會產生下列觸控事件：

• ACTION_DOWN：當第一個指標輕觸螢幕時，系統會傳送這項事件。這會啟動手勢。這個指標的指標資料一律會位於 MotionEvent 中的索引 0。
• ACTION_POINTER_DOWN：當其他指標在第一個指標後進入螢幕時，系統會傳送這項事件。您可以使用 getActionIndex() 取得剛剛向下移動的指標索引。
• ACTION_MOVE：在手勢發生變更時傳送，涉及任意數量的指標。
• ACTION_POINTER_UP：當非主要指標向上移動時傳送。您可以使用 getActionIndex() 取得剛剛向上移動的指標索引。
• ACTION_UP：當最後一個指標離開螢幕時傳送。
• ACTION_CANCEL：表示已取消整個手勢，包括所有指標。

開始和結束手勢

手勢是一系列以 ACTION_DOWN 事件開始，並以 ACTION_UP 或 ACTION_CANCEL 事件結束的事件。一次只能有一個手勢處於啟用狀態。動作「向下」、「移動」、「向上」和「取消」會套用至整個手勢。舉例來說，使用 ACTION_MOVE 的事件可在該時刻指出所有指標向下移動。

追蹤指標

使用指標的索引和 ID，追蹤 MotionEvent 中的個別指標位置。

• 索引：MotionEvent 會在陣列中儲存指標資訊。指標的索引是指標在這個陣列中的位置。大多數 MotionEvent 方法會使用指標索引做為參數，而非指標 ID。
• ID：每個指標也都有一個 ID 對應項目，可在觸控事件中持續保留，以便在整個手勢中追蹤個別指標。

個別指標會以未定順序顯示在動作事件中。因此，指標的索引可以從一個事件變更為下一個事件，但只要指標仍處於活動狀態，指標 ID 就保證會保持不變。請使用 getPointerId() 方法取得指標的 ID，以便在手勢的所有後續動作事件中追蹤指標。接著，針對連續動作事件，請使用 findPointerIndex() 方法，取得該動作事件中特定指標 ID 的指標索引。例如：

Kotlin

private var mActivePointerId: Int = 0

override fun onTouchEvent(event: MotionEvent): Boolean {
    ...
    // Get the pointer ID.
    mActivePointerId = event.getPointerId(0)

    // ... Many touch events later...

    // Use the pointer ID to find the index of the active pointer
    // and fetch its position.
    val (x: Float, y: Float) = event.findPointerIndex(mActivePointerId).let { pointerIndex ->
        // Get the pointer's current position.
        event.getX(pointerIndex) to event.getY(pointerIndex)
    }
    ...
}

Java

private int mActivePointerId;

public boolean onTouchEvent(MotionEvent event) {
    ...
    // Get the pointer ID.
    mActivePointerId = event.getPointerId(0);

    // ... Many touch events later...

    // Use the pointer ID to find the index of the active pointer
    // and fetch its position.
    int pointerIndex = event.findPointerIndex(mActivePointerId);
    // Get the pointer's current position.
    float x = event.getX(pointerIndex);
    float y = event.getY(pointerIndex);
    ...
}

如要支援多個觸控指標，您可以在個別 ACTION_POINTER_DOWN 和 ACTION_DOWN 事件時間，將所有有效指標和 ID 快取。在 ACTION_POINTER_UP 和 ACTION_UP 事件中，從快取中移除指標。您可能會發現，這些快取 ID 有助於正確處理其他動作事件。舉例來說，在處理 ACTION_MOVE 事件時，請找出每個已快取的有效指標 ID 的索引，使用 getX() 和 getY() 函式擷取指標的座標，然後將這些座標與已快取的座標進行比較，找出移動的指標。

請僅在 ACTION_POINTER_UP 和 ACTION_POINTER_DOWN 事件中使用 getActionIndex() 函式。請勿將此函式與 ACTION_MOVE 事件搭配使用，因為這會一律傳回 0。

擷取 MotionEvent 動作

請使用 getActionMasked() 方法或相容性版本 MotionEventCompat.getActionMasked() 擷取 MotionEvent 的動作。與先前的 getAction() 方法不同，getActionMasked() 可搭配多個指標運作。會傳回不含指標索引的動作。對於具有有效指標索引的動作，請使用 getActionIndex() 傳回與該動作相關聯的指標索引，如以下程式碼片段所示：

注意：這個範例使用 MotionEventCompat 類別，這是 支援資料庫中的類別。使用 MotionEventCompat 為各種平台提供最佳支援。MotionEventCompat 不是 MotionEvent 類別的替代方案。而是提供靜態公用程式方法，您可以將 MotionEvent 物件傳遞至該方法，以便接收與該事件相關聯的所需動作。

Kotlin

val (xPos: Int, yPos: Int) = MotionEventCompat.getActionMasked(event).let { action ->
    Log.d(DEBUG_TAG, "The action is ${actionToString(action)}")
    // Get the index of the pointer associated with the action.
    MotionEventCompat.getActionIndex(event).let { index ->
        // The coordinates of the current screen contact, relative to
        // the responding View or Activity.
        MotionEventCompat.getX(event, index).toInt() to MotionEventCompat.getY(event, index).toInt()
    }
}

if (event.pointerCount > 1) {
    Log.d(DEBUG_TAG, "Multitouch event")

} else {
    // Single touch event.
    Log.d(DEBUG_TAG, "Single touch event")
}

...

// Given an action int, returns a string description.
fun actionToString(action: Int): String {
    return when (action) {
        MotionEvent.ACTION_DOWN -> "Down"
        MotionEvent.ACTION_MOVE -> "Move"
        MotionEvent.ACTION_POINTER_DOWN -> "Pointer Down"
        MotionEvent.ACTION_UP -> "Up"
        MotionEvent.ACTION_POINTER_UP -> "Pointer Up"
        MotionEvent.ACTION_OUTSIDE -> "Outside"
        MotionEvent.ACTION_CANCEL -> "Cancel"
        else -> ""
    }
}

Java

int action = MotionEventCompat.getActionMasked(event);
// Get the index of the pointer associated with the action.
int index = MotionEventCompat.getActionIndex(event);
int xPos = -1;
int yPos = -1;

Log.d(DEBUG_TAG,"The action is " + actionToString(action));

if (event.getPointerCount() > 1) {
    Log.d(DEBUG_TAG,"Multitouch event");
    // The coordinates of the current screen contact, relative to
    // the responding View or Activity.
    xPos = (int)MotionEventCompat.getX(event, index);
    yPos = (int)MotionEventCompat.getY(event, index);

} else {
    // Single touch event.
    Log.d(DEBUG_TAG,"Single touch event");
    xPos = (int)MotionEventCompat.getX(event, index);
    yPos = (int)MotionEventCompat.getY(event, index);
}
...

// Given an action int, returns a string description
public static String actionToString(int action) {
    switch (action) {

        case MotionEvent.ACTION_DOWN: return "Down";
	case MotionEvent.ACTION_MOVE: return "Move";
	case MotionEvent.ACTION_POINTER_DOWN: return "Pointer Down";
	case MotionEvent.ACTION_UP: return "Up";
	case MotionEvent.ACTION_POINTER_UP: return "Pointer Up";
	case MotionEvent.ACTION_OUTSIDE: return "Outside";
	case MotionEvent.ACTION_CANCEL: return "Cancel";
    }
    return "";
}

圖 1. 多點觸控繪圖模式。

其他資源

如要進一步瞭解輸入事件，請參閱下列參考資料：

• 輸入事件總覽
• 感應器總覽
• 將自訂檢視畫面設為互動式
• 拖曳與縮放