Back to Qt.io
Contact Us Blog Download Qt
本页内容

MultiPointTouchArea QML Type

支持处理多个触点。更多...

Import Statement: import QtQuick
Inherits:

Item

属性

信号

详细说明

MultiPointTouchArea 是一个用于跟踪多个触点的位置的不可见控件。

Item::enabled 属性用于启用或禁用触摸处理。禁用时，触摸区域对鼠标和触摸事件将变得透明。

默认情况下，鼠标将被视为单点触控进行处理，且触控区域下方的控件不会接收鼠标事件，因为这些事件由触控区域处理。但如果将mouseEnabled 属性设置为false，该区域对鼠标事件将变为透明，从而允许另一个对鼠标敏感的控件（例如MouseArea ）单独处理鼠标交互。

MultiPointTouchArea 有两种使用方式：

  • 将 `touchPoints ` 设置为 `true`，以便为触摸点对象提供可绑定的属性
  • 通过 onTouchUpdated 或 onPressed、onUpdated 以及 onReleased 处理程序

虽然一个 MultiPointTouchArea可以独占某些触点，但也可以同时激活多个 MultiPointTouchArea，每个都处理不同的一组触点。

另请参阅 ` TouchPoint`。

属性文档

maximumTouchPoints : int

minimumTouchPoints : int

这些属性定义了触摸区域所处理的触摸点范围。

这些属性提供了便利，例如，允许您创建嵌套的 MultiPointTouchArea，其中一个处理两指触摸，另一个处理三指触摸。

默认情况下，触摸区域内的所有触摸点都会被处理。

如果mouseEnabled 为true，则鼠标将作为触摸点，因此也受这些限制的约束：例如，如果maximumTouchPoints 为2，则可以使用鼠标作为其中一个触摸点，用手指作为另一个触摸点，总共两个。

mouseEnabled : bool

此属性控制MultiPointTouchArea 是否也会处理鼠标事件。如果为true（默认值），则触摸区域会将鼠标视为单点触摸；如果为false，则触摸区域将忽略鼠标事件并允许其“穿透”，以便下方的其他控件能够处理这些事件。

touchPoints : list<TouchPoint> [read-only]

该属性包含一组可用于绑定的用户自定义触点对象。

如果mouseEnabled 为true（默认值），且鼠标悬停在触摸区域上时按下了鼠标左键，则当前鼠标位置将变为这些触摸点之一。

在下面的示例中，我们有两个小矩形，它们会跟随我们的触点移动。

import QtQuick

Rectangle {
    width: 400; height: 400
    MultiPointTouchArea {
        anchors.fill: parent
        touchPoints: [
            TouchPoint { id: point1 },
            TouchPoint { id: point2 }
        ]
    }

    Rectangle {
        width: 30; height: 30
        color: "green"
        x: point1.x
        y: point1.y
    }

    Rectangle {
        width: 30; height: 30
        color: "yellow"
        x: point2.x
        y: point2.y
    }
}

默认情况下，此属性包含一个空列表。

另请参阅 TouchPoint 。

Signal 文档

canceled(list<TouchPoint> touchPoints)

当新的触摸事件因另一个项目抢占了触摸事件处理而被取消时，会发出此信号。

该信号适用于高级场景：当存在多个正在处理输入的MultiPointTouchArea 时，或者当Flickable 内部包含MultiPointTouchArea 时，该信号非常有用。 在后一种情况下，如果您在onPressed 信号处理程序中执行某些逻辑，然后开始拖动，Flickable 可能会从MultiPointTouchArea 处抢占触摸处理权。在这种情况下，当MultiPointTouchArea 将触摸处理权让给Flickable 时，除了处理released 外，还应处理canceled ，以重置相关逻辑。

touchPoints 是已取消的点列表。

注意：如果您在 信号处理程序代码中使用了touchPoints 参数，最好在形式参数中将其重命名，以避免与touchPoints 属性混淆（参见《QML编码规范》）：

onCanceled: (points) => console.log("canceled", points.length)

注意： 相应的处理程序 是onCanceled 。

gestureStarted(GestureEvent gesture)

当达到全局拖动阈值时，会触发此信号。

该信号通常用于将MultiPointTouchArea 嵌套在Flickable或其他MultiPointTouchArea 中时。当达到阈值且信号被处理时，您可以确定触摸区域是否应捕获当前的触摸点。 默认情况下，这些触点不会被捕获；若要捕获它们，请调用gesture.grab() 。如果手势未被捕获，那么嵌套的 Flickable（例如）也将有机会进行捕获。

gesture 对象还包含有关当前touchPoints 集合以及dragThreshold 的信息。

注意： 对应的处理程序 为onGestureStarted 。

pressed(list<TouchPoint> touchPoints)

当添加新的触点时，会触发此信号。touchPoints 是一个包含这些新触点的列表。

如果将 `minimumTouchPoints ` 设置为大于 1 的值，则该信号不会被触发，直到达到所需的最小触点数量为止。

注意：如果您在 信号处理程序代码中使用 `touchPoints ` 参数，最好在形式参数中将其重命名，以避免与 `touchPoints ` 属性混淆（参见《QML 编码规范》）：

onPressed: (points) => console.log("pressed", points.length)

注意： 相应的处理程序 是onPressed 。

released(list<TouchPoint> touchPoints)

当现有触点被移除时，会触发此信号。touchPoints 是一个包含这些被移除触点的列表。

注意：如果您在 信号处理程序代码中使用 `touchPoints ` 参数，最好在形式参数中将其重命名，以避免与 `touchPoints ` 属性混淆（参见《QML 编码规范》）：

onReleased: (points) => console.log("released", points.length)

注意： 相应的处理程序 是onReleased 。

touchUpdated(list<TouchPoint> touchPoints)

当由 `MultiPointTouchArea ` 处理的触点发生变化时，会触发此信号。这包括添加新触点、移除或取消之前的触点，以及更新当前触点数据。touchPoints 包含所有当前触点的列表。

注意： 相应的处理程序 是onTouchUpdated 。

updated(list<TouchPoint> touchPoints)

当现有触点被更新时，会触发此信号。touchPoints 是一个包含这些已更新触点的列表。

注意：如果您在 信号处理程序代码中使用 `touchPoints ` 参数，最好在形式参数中将其重命名，以避免与 `touchPoints ` 属性混淆（参见《QML 编码规范》）：

onUpdated: (points) => console.log("updated", points.length)

注意： 相应的处理程序 是onUpdated 。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.