1. 课程导入

在桌面、嵌入式和移动设备上，用户对界面的第一期待往往不是“功能齐全”，而是“跟手、顺滑、自然”。Qt Quick 作为 Qt 框架中面向现代 UI 的声明式技术，天然适合构建高帧率、可触摸、可动画的交互界面。但很多开发者在从鼠标事件迁移到触摸与手势时，会遇到一个共同困惑：为什么点击能响应，滑动却卡顿？为什么单指正常，多指就乱？为什么 QML 里写了 MouseArea，手指拖动却没有惯性？ 本课程正是围绕这些问题展开，帮助你建立一套从触摸事件到手势识别、从单点交互到多点协同的完整知识体系。

一、学习目标：从“能点”到“会交互”

本课程不是简单罗列 API，而是以“输入信号如何被采集、传递、识别并转化为界面行为”为主线。完成学习后，你应当能够：

• 理解 Qt Quick 中触摸、鼠标、手写笔等输入事件的统一抽象与差异；
• 掌握 MultiPointTouchArea、PinchArea、Flickable、DragHandler 等核心交互组件的适用边界；
• 能够根据业务场景选择“事件级处理”还是“手势级处理”；
• 能够诊断触摸延迟、事件被拦截、手势冲突、多点坐标错乱等常见问题；
• 能够为自定义控件设计可复用、可测试的触摸交互逻辑。

二、核心概念：触摸交互的四层模型

为了避免“见树不见林”，我们先建立一张整体认知图。Qt Quick 的触摸交互可以拆成四层：输入层负责采集原始触摸点；事件层把原始点封装为 QTouchEvent / QMouseEvent；识别层判断这是点击、拖动、捏合还是旋转；行为层把识别结果映射为位移、缩放、动画或业务状态。很多问题之所以难排查，是因为开发者只盯着行为层，却忽略了事件层是否被某个 Item 提前消费。

三、整体框架：课程如何展开

本课程共 30 章，整体遵循“先建立模型，再掌握工具，最后解决冲突”的路径。前 6 章聚焦基础：触摸事件模型、坐标系统、MouseArea 与 TouchArea 的差异、Flickable 的惯性机制。中段 7 至 18 章进入手势核心：单指拖动、双指缩放、旋转、长按、滑动方向判定，以及 PinchArea、MultiPointTouchArea、DragHandler 等组件的组合使用。后段 19 至 30 章面向工程化：手势冲突、事件穿透、性能优化、跨平台差异、自定义手势识别器、测试与调试方法。

四、典型场景：一个可拖拽缩放的图片查看器

为了把抽象概念落到具体代码，我们以“图片查看器”作为贯穿案例。它需要同时支持：单指拖动平移、双指捏合缩放、双击复位、边界回弹。这个场景几乎覆盖了触摸交互的全部核心难点：单点与多点切换、手势竞争、坐标映射、动画回退。

import QtQuick 2.15

Rectangle {
    width: 640; height: 480
    color: "#101820"

    Image {
        id: photo
        source: "sample.jpg"
        anchors.centerIn: parent
        scale: 1.0
        x: 0; y: 0
    }

    PinchArea {
        anchors.fill: parent
        pinch.target: photo
        pinch.minimumScale: 0.5
        pinch.maximumScale: 4.0

        onPinchUpdated: {
            // 捏合过程中同步更新位置与缩放
            photo.x += pinch.center.x - pinch.previousCenter.x
            photo.y += pinch.center.y - pinch.previousCenter.y
        }
    }

    MouseArea {
        anchors.fill: parent
        drag.target: photo
        onDoubleClicked: {
            photo.scale = 1.0
            photo.x = 0; photo.y = 0
        }
    }
}

这段代码看似简单，却隐藏着两个典型问题：MouseArea 与 PinchArea 同时铺满父项时，谁先接收事件？拖动过程中缩放中心如何保持稳定？这些问题会在后续章节逐一拆解。此处先建立直觉：手势不是孤立 API，而是事件竞争与状态协调的结果。

五、常见误区与复盘

初学者最容易陷入以下误区：

• 把 MouseArea 当万能触摸组件。MouseArea 能处理点击和拖动，但对多点、压力、手写笔支持有限，复杂手势应优先考虑专用组件。
• 忽略 accepted 属性。事件是否继续向父项传递，取决于是否被接受。很多“父项收不到事件”的问题，根源在于子项默认消费了事件。
• 用动画补偿触摸延迟。如果触摸本身不跟手，加动画只会掩盖问题。应先确认事件采样与坐标映射是否正确。
• 在 onPressed 中做重计算。按下阶段应尽量轻量，把复杂逻辑放到 onPositionChanged 或手势识别完成后。

本章没有要求你立刻写出复杂手势，而是希望你先建立一张清晰的“交互地图”。接下来，我们会从触摸事件的最小单元开始，逐步把这张地图填满。只要四层模型清晰，后续每一个组件、每一段代码，都会找到它在该模型中的位置。