处理多点触控手势

试用 Compose 方式
Jetpack Compose 是推荐用于 Android 的界面工具包。了解如何在 Compose 中使用触摸和输入功能。

多点触控手势是指多个指针(手指)同时点按屏幕。本文档介绍了如何检测涉及多个指针的手势。

跟踪多个指针

当多个指针同时点按屏幕时,系统会生成以下触摸事件:

  • ACTION_DOWN:在第一个指针点按屏幕时发送。这是手势的起点。此指针的指针数据始终位于 MotionEvent 中的索引 0 处。
  • ACTION_POINTER_DOWN:当额外的指针在第一个指针之后进入屏幕时发送。您可以使用 getActionIndex() 获取刚刚释放的指针的索引。
  • ACTION_MOVE:当手势发生变化且涉及任意数量的指针时发送。
  • ACTION_POINTER_UP:在非主要指针抬起时发送。您可以使用 getActionIndex() 获取刚刚释放的指针的索引。
  • ACTION_UP:在最后一个指针离开屏幕时发送。
  • ACTION_CANCEL:表示取消整个手势,包括所有指针。

开始和结束手势

手势是一系列以 ACTION_DOWN 事件开始并以 ACTION_UPACTION_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_DOWNACTION_DOWN 事件时分别缓存所有活动指针及其 ID。通过指针的 ACTION_POINTER_UPACTION_UP 事件从缓存中移除指针。您可能会发现这些缓存的 ID 有助于正确处理其他操作事件。例如,在处理 ACTION_MOVE 事件时,请查找每个缓存的有效指针 ID 的索引,使用 getX()getY() 函数检索指针的坐标,然后将这些坐标与缓存的坐标进行比较,以发现移动了哪些指针。

请仅将 getActionIndex() 函数用于 ACTION_POINTER_UPACTION_POINTER_DOWN 事件。请勿将此函数与 ACTION_MOVE 事件一起使用,因为此函数始终返回 0

检索 MotionEvent 操作

使用 getActionMasked() 方法或兼容版本 MotionEventCompat.getActionMasked() 可检索 MotionEvent 的操作。与之前的 getAction() 方法不同,getActionMasked() 可与多个指针配合使用。它返回没有指针索引的操作。对于具有有效指针索引的操作,请使用 getActionIndex() 返回与操作相关联的指针的索引,如以下代码段所示:

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.多点触控绘制图案。

其他资源

如需详细了解输入事件,请参阅以下参考文档: