Compose 实践与探索十七 —— 多指手势与自定义触摸反馈

上一节我们讲了滑动的手势识别以及嵌套滑动，二者都属于触摸反馈这个大的范畴内的知识。本节我们将深入触摸反馈这个话题，讲一讲多指手势的识别与完全自定义的触摸反馈的实现。

1、多指手势

多指手势可以分为两类：

利用 API 处理预设好的手势
自定义的多指手势识别：自己分析触摸到屏幕上的每一根手指的滑动轨迹，然后识别对应的手势

本节讲解第 1 种，下节介绍第 2 种。

Compose 提供了三种多指手势的识别：移动、放缩与旋转，它们都存在于 detectTransformGestures 函数中，该函数也需要在 pointerInput() 内使用。我们先来看该函数的参数：

/**
* 一个用于旋转、平移和缩放的手势检测器。一旦达到触摸阈值，用户可以使用旋转、平移和缩放手势。
* 当发生旋转、缩放或平移中的任何一种手势时，将调用 onGesture，传递旋转角度（以度为单位）、
* 缩放比例因子和像素偏移量。每个改变都是前一次调用和当前手势之间的差异。在触摸阈值之后，这将
* 消耗所有位置变化。onGesture 还将提供所有已按下指针的中心点。
*
* 如果 panZoomLock 设置为 true，则只有在检测到旋转的触摸阈值之前才允许旋转，然后才能进行平移
* 或缩放动作。否则，将检测到平移和缩放手势，但不会检测到旋转手势。如果 panZoomLock 设置为 false，
* 则一旦触摸阈值被触发，将检测到所有三种手势。
*/
suspend fun PointerInputScope.detectTransformGestures(
    panZoomLock: Boolean = false,
    onGesture: (centroid: Offset, pan: Offset, zoom: Float, rotation: Float) -> Unit
)

第一个参数 panZoomLock 是一个开关，分为两种情况：

当它为 false 时，三种手势可以同时识别
当它为 true 时，如果先识别到旋转操作，那么就不会再监测滑动和缩放；如果先监测到滑动或缩放，那么就不会再监测旋转。相当于是把滑动和缩放放在一组，旋转单独放在另外一组，只监测先触发的那组操作

第二个参数 onGesture 参数是一个回调函数，它的参数含义如下：

centroid：所有按下手指的中心点。这是一个辅助参数，需要配合后面三个参数使用
pan：位移参数，表示中心点 centroid 在这一时刻与上一时刻的位置偏移量
zoom：这一时刻与上一时刻相比的放缩倍数
rotation：这一时刻与上一时刻相比的旋转角度

2、完全自定义触摸算法

前面我们讲了很多半自动化 API 进行手势识别，那些 API 可以覆盖绝大多数的使用场景。本节我们来介绍，如何通过底层 API 实现完全自定义的触摸算法。

2.1 写法、思维逻辑与代码框架

完全自定义触摸算法意味着要从获取触摸事件开始，自己对每一个触摸事件进行处理。

与前面介绍过的半自动化 API 类似的是，需要在 Modifier.pointerInput() 中调用底层 API 来接收触摸事件，这个底层 API 是 AwaitPointerEventScope 接口内的 awaitPointerEvent()：

@RestrictsSuspension
@JvmDefaultWithCompatibility
interface AwaitPointerEventScope : Density {
    /**
     * 挂起协程，直到指定的输入通道（input pass）报告 PointerEvent 事件，pass 参数默认值是
     * PointerEventPass.Main。
     * [awaitPointerEvent] 会在受限制的挂起作用域中以同步的方式恢复执行。这意味着调用者在
     * [awaitPointerEvent] 返回后可以立即对输入做出反应，并同时影响当前帧和输入处理管道的下一个
     * 处理程序或阶段。调用者应在等待下一个事件前，对返回的 [PointerEvent] 进行修改，以便在输入处
     * 理流程的下一阶段运行前消费该事件的某些处理结果。
     */
    suspend fun awaitPointerEvent(
        pass: PointerEventPass = PointerEventPass.Main
    ): PointerEvent
}

它的大致使用模式如下：

setContent {
    // 尾随 lambda 是挂起函数环境的
    Modifier.pointerInput(Unit) {
        // 事件对象
        var event: PointerEvent
        // 提供调用 awaitPointerEvent() 的环境 AwaitPointerEventScope
        awaitPointerEventScope {
            while (true) {
                // 挂起以获取触摸事件
                event = awaitPointerEvent()
            }
        }
    }
}

awaitPointerEvent() 的返回值类型是 PointerEvent，该类型内部封装了原生的触摸事件类型 MotionEvent。通过 PointerEvent 的 type 属性可以获取事件的具体类型：

    actual var type: PointerEventType = calculatePointerEventType()
        internal set

    private fun calculatePointerEventType(): PointerEventType {
        val motionEvent = motionEvent
        if (motionEvent != null) {
            return when (motionEvent.actionMasked) {
                MotionEvent.ACTION_DOWN,
                MotionEvent.ACTION_POINTER_DOWN -> PointerEventType.Press
                MotionEvent.ACTION_UP,
                MotionEvent.ACTION_POINTER_UP -> PointerEventType.Release
                MotionEvent.ACTION_HOVER_MOVE,
                MotionEvent.ACTION_MOVE -> PointerEventType.Move
                MotionEvent.ACTION_HOVER_ENTER -> PointerEventType.Enter
                MotionEvent.ACTION_HOVER_EXIT -> PointerEventType.Exit
                ACTION_SCROLL -> PointerEventType.Scroll

                else -> PointerEventType.Unknown
            }
        }
        ...
        return PointerEventType.Move
    }

在 calculatePointerEventType() 中能看出原生的 MotionEvent 的类型在 Compose 中对应 PointerEventType 的哪种类型。需要注意的是，原生中把第一个手指按下的类型定义为 ACTION_DOWN，把非第一个手指按下的类型定义为 ACTION_POINTER_DOWN。但是在 Compose 中，将按下类型都合并为 Press。同样的，原生的最后一个手指抬起是 ACTION_UP，非最后一个手指抬起是 ACTION_POINTER_UP，在 Compose 中也被合并为 Release。

此外，我们还应注意到，Compose 获取事件的代码形式与原生不同。原生是在发生触摸事件后通过回调 onTouchEvent() 传入具体的事件类型实现的事件监听:

class CustomView(context: Context?, attrs: AttributeSet?) : View(context, attrs) {
    override fun onTouchEvent(event: MotionEvent?): Boolean {
        when (event?.action) {
            MotionEvent.ACTION_DOWN -> {...}
            MotionEvent.ACTION_POINTER_DOWN -> {...}
            else -> {...}
        }
        return super.onTouchEvent(event)
    }
}

而 Compose 则需要自己循环调用 awaitPointerEvent() 去获取发生的事件 PointerEvent，然后通过 PointerEvent 的 type 属性去判断具体的触摸事件类型。看似是 Compose 要比 Android 原生更麻烦一些，但实际上这并不是 Compose 与原生的区别，而是传统的 Java 回调与 Kotlin 协程在写法上的不同造成的。协程以线性代码完成了异步操作，从整体上来讲，这样的写法要比回调更加直观和简单。

接下来举个例子，自己实现一个点击监听器：

fun Modifier.clickListener(onClick: () -> Unit) = pointerInput(Unit) {
    awaitPointerEventScope {
        // 循环接收所有的触摸事件
        while (true) {
            // 先接收一串触摸事件的第一个事件，按下事件
            val down = awaitPointerEvent()
            // 循环接收后续事件
            while (true) {
                val event = awaitPointerEvent()
                // 滑动事件不能超出组件范围，否则抬起时不响应 onClick
                if (event.type == PointerEventType.Move) {
                    val position = event.changes[0].position
                    if (position.x < 0 || position.x > size.width || position.y < 0 || position.y > size.height) {
                        break
                    }
                } else if (event.type == PointerEventType.Release) {
                    onClick()
                    break
                }
            }
        }
    }
}

以上是实现的比较粗糙的点击监听器，在组件范围内按下并抬起后会回调 onClick 参数，但如果是在组件范围外抬起，就跳出本次的事件监听，从下一次的按下事件重新开始。监听过程中，使用了 PointerEvent 的 changes 数组：

actual val changes: List<PointerInputChange>

该数组的元素类型 PointerInputChange 是触摸事件的核心数据结构，用于描述单个指针（如手指、触控笔或鼠标）的输入状态变化，它是手势处理系统中最细粒度的操作单元。changes 数组就是所有指针触摸状态的变化，示例代码中只取了第一个元素，实际上就是只针对第一个按下的指针进行了状态的判断，没有支持多指逻辑。

下面我们可以试着对示例代码进行优化。

首先，使用在 1.4.0-alpha01 版本中新增的 awaitEachGesture() 可以简化示例代码，它可以帮我们实现连续手势的检测，因此就不用在最外层加一个 while(true) 了：

fun Modifier.clickListener(onClick: () -> Unit) = pointerInput(Unit) {
    awaitEachGesture {
        // 先接收一串触摸事件的第一个事件，按下事件
        val down = awaitPointerEvent()
        // 循环接收后续事件
        while (true) {
            val event = awaitPointerEvent()
            // 滑动事件不能超出组件范围，否则抬起时不响应 onClick
            if (event.type == PointerEventType.Move) {
                val position = event.changes[0].position
                if (position.x < 0 || position.x > size.width || position.y < 0 || position.y > size.height) {
                    break
                }
            } else if (event.type == PointerEventType.Release) {
                onClick()
                break
            }
        }
    }
}

此外，要对抬起和按下事件做细致的区分。因为前面我们贴出相关代码了，Compose 将任何手指的抬起和按下都定义为 Press 和 Release 类型，不同的手指按下与抬起的效果应该是不同的。对于示例代码而言，应该是最后一个手指抬起（对应原生的 MotionEvent.ACTION_UP）才认为发生了点击事件，所以要添加一个“抬起的是最后一个手指”的条件，

fun Modifier.clickListener(onClick: () -> Unit) = pointerInput(Unit) {
    awaitEachGesture {
        val down = awaitPointerEvent()
        while (true) {
            val event = awaitPointerEvent()
            if (event.type == PointerEventType.Move) {
                val position = event.changes[0].position
                if (position.x < 0 || position.x > size.width || position.y < 0 || position.y > size.height) {
                    break
                }
            } else if (event.type == PointerEventType.Release && event.changes.size == 1) { 
                // 添加抬起时只有一个手指的条件
                onClick()
                break
            }
        }
    }
}

关于判断手指抬起的更详细逻辑，可以参考 AwaitPointerEventScope.waitForUpOrCancellation() 的代码：

suspend fun AwaitPointerEventScope.waitForUpOrCancellation(
    pass: PointerEventPass = PointerEventPass.Main
): PointerInputChange? {
    while (true) {
        val event = awaitPointerEvent(pass)
        // 判断所有手指都抬起了
        if (event.changes.fastAll { it.changedToUp() }) {
            // All pointers are up
            return event.changes[0]
        }

        if (event.changes.fastAny {
                it.isConsumed || it.isOutOfBounds(size, extendedTouchPadding)
            }
        ) {
            return null // Canceled
        }

        // Check for cancel by position consumption. We can look on the Final pass of the
        // existing pointer event because it comes after the pass we checked above.
        val consumeCheck = awaitPointerEvent(PointerEventPass.Final)
        if (consumeCheck.changes.fastAny { it.isConsumed }) {
            return null
        }
    }
}

获取按下事件的函数也可以优化为 awaitFirstDown()：

fun Modifier.clickListener(onClick: () -> Unit) = pointerInput(Unit) {
    awaitEachGesture {
        // 先接收一串触摸事件的第一个事件，按下事件
        val down = awaitFirstDown()
        // 循环接收后续事件
        while (true) {
            val event = awaitPointerEvent()
            // 滑动事件不能超出组件范围，否则抬起时不响应 onClick
            if (event.type == PointerEventType.Move) {
                val position = event.changes[0].position
                if (position.x < 0 || position.x > size.width || position.y < 0 || position.y > size.height) {
                    break
                }
            } else if (event.type == PointerEventType.Release && event.changes.size == 1) {
                onClick()
                break
            }
        }
    }
}

2.2 触摸事件的消费、拦截、取消

Android 原生为什么会有事件的消费、拦截和取消这些概念呢？因为手势可能会冲突。比如用户在屏幕上点击了一下，那么它点击到的是子组件还是父组件呢？这要看哪个组件消费了这个点击事件。结合实际场景，可能会有两种不同的表现：

在一个列表中，每个列表项上都有一个点赞按钮，当用户点击点赞按钮时，它触发的点赞按钮而不是整个列表项的点击。因为用户想点击的一定是表面的那个组件，所以 Android 通常会让子组件优先消费，只有在子组件不消费时才会让父组件消费
另外一种情况，还是在滑动列表中，点在一个列表项上然后向上滑动，用户是要滑动父组件，而不是点击列表项。此时就是父组件拦截了该事件，这个拦截发生在子组件消费之前

总的来说，原生的触摸事件的处理分为拦截与消费两大步骤，在子组件消费之前，会向上按照父组件到根组件的方向去询问是否要进行拦截，如果有任意一个父组件拦截了事件，那么就由该组件消费事件，并向子组件发送一个取消事件，在手指抬起之前，后续的所有事件都不会再发送给子组件。

而假如没有任何父级组件拦截事件，该事件就由子组件开始消费，只有在子组件不消费该事件时，才会一级一级地向父组件的方向传递，查看是否消费。

因此，在原生中，拦截是一个较为强势的过程，只有父组件不拦截才轮到子组件消费。

而在 Compose 中，不再有拦截的概念，只有消费的概念，或者说，把拦截的过程合并到消费中了。首先，事件会先传给父组件，无论父组件是否消费该事件，它都会继续向下传导到子组件中，只不过，如果父组件消费了事件，那么子组件就无法消费该事件了，但是可以利用事件已经被消费的事实去做一些别的事情，然后再次把该事件传回给父组件，形成一个父 -> 子 -> 父的事件传递链。最后再传回给父组件，是为了给嵌套滑动提供基础支持。这是原生的拦截 -> 消费过程所不具备的。

Compose 的事件消费原则：

使用事件前，先检查该事件是否已经被消费了，一般是没有被消费才可被使用，但也有例外，比如滑动过程是不介意按下事件是否被消费了的
使用完某个事件，一般应该消费掉该事件。但肯定也会有特殊场景，比如不想因为对事件的处理影响整体流程，那么处理完事件后也可以不消费掉它

最后来说一下相关的 API。

此前我们说过了 awaitPointerEvent()，它的参数 pass 的默认值为 PointerEventPass.Main，PointerEventPass 实际上就是定义了事件传递流程的枚举类：

enum class PointerEventPass {
    Initial, Main, Final
}

Initial 表示事件第一次由父组件传递给子组件的过程，Main 表示事件由子组件传给父组件的过程，而 Final 表示事件第二次父组件到子组件的过程。当我们一起使用这三个参数时，得到的其实是同一个事件对象：

// event1、event2、event3 是同一个 PointerEvent 对象
val event1 = awaitPointerEvent(PointerEventPass.Initial)
val event2 = awaitPointerEvent(PointerEventPass.Main)
val event3 = awaitPointerEvent(PointerEventPass.Final)

消费事件与检查事件是否已经被消费：

event2.changes[0].consume()
event2.changes[0].isConsumed

完整的代码可以参考 Compose 官方的滑动监听、长按监听等源码。

2.3 多指手势和多重手势

多重手势是指多个手指可以同时进行旋转、滑动、缩放手势，即一个手势可以起多重作用。

如何计算多指手势？对多个触摸点做综合计算，比如说多指滑动，先拿到滑动事件，计算所有手指的中心点，然后用这一时刻中心点与上一时刻中心点的差值作为滑动位移。中心点就用所有点的坐标加和除以触摸点的个数即可。当然这个有现成函数可以用，比如 calculatePan() 就是计算多指滑动的中心点的 API：

val event = awaitPointerEvent()
event.calculatePan()

其余的还有 calculateRotation()、calculateZoom()、calculateCentroid() 等。