处理多点触摸手势

尝试 Compose 方法
Jetpack Compose 是推荐的 Android UI 工具包。了解如何在 Compose 中使用触摸和输入。
多点触摸手势 →

多点触摸手势是指多个指针（手指）同时点击屏幕。本文档介绍如何检测涉及多个指针的手势。

跟踪多个指针

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

  • ACTION_DOWN：当第一个指针点击屏幕时发送。这将启动手势。此指针的指针数据始终位于MotionEvent中的索引0。
  • ACTION_POINTER_DOWN：当第一个指针之后其他指针进入屏幕时发送。您可以使用getActionIndex()获取刚刚按下指针的索引。
  • ACTION_MOVE：当手势发生变化时发送，涉及任意数量的指针。
  • ACTION_POINTER_UP：当非主指针抬起时发送。您可以使用getActionIndex()获取刚刚抬起的指针的索引。
  • ACTION_UP：当最后一个指针离开屏幕时发送。
  • ACTION_CANCEL：表示整个手势（包括所有指针）都被取消。

开始和结束手势

手势是一系列事件，从ACTION_DOWN事件开始，以ACTION_UP或ACTION_CANCEL事件结束。一次只有一个活动手势。DOWN、MOVE、UP 和 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);
    ...
}

为了支持多个触摸指针，您可以使用它们的ID在各自的ACTION_POINTER_DOWN和ACTION_DOWN事件时间缓存所有活动指针。在它们的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()返回与操作关联的指针的索引，如下面的代码片段所示

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.多点触摸绘图模式。

其他资源

有关输入事件的更多信息，请参阅以下参考资料