TapHandler QML Type

点按处理程序更多

• 所有成员（包括继承成员）的列表

属性

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• exclusiveSignals : enumeration (since 6.5)
• gesturePolicy : enumeration
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : handlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

信号

• canceled(eventPoint point)
• doubleTapped(eventPoint eventPoint, Qt::MouseButton button)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• longPressed()
• singleTapped(eventPoint eventPoint, Qt::MouseButton button)
• tapCountChanged()
• tapped(eventPoint eventPoint, Qt::MouseButton button)

详细说明

TapHandler 是一个处理程序，用于处理触摸屏上的点击或鼠标上的单击。

有效点击手势的检测取决于gesturePolicy 。默认值为 DragThreshold，它要求按下和松开在空间和时间上都很接近。在这种情况下，TapHandler 只需被动抓取即可运行，因此不会干扰其他项目或输入处理程序的事件交付。因此，当您想通过添加带有绑定和/或 JavaScript 回调的 TapHandler 来修改现有控件或项的行为时，默认的gesturePolicy 非常有用。

请注意，按钮（如QPushButton ）的实现通常不会考虑按下和松开是否发生在一起：如果按下按钮后改变主意，则需要从按钮边缘一直拖动才能取消点击。在这种情况下，请将gesturePolicy 设置为TapHandler.ReleaseWithinBounds 。

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

对于多点手势（双击、三击等），鼠标移动的距离不得超过QStyleHints::mouseDoubleClickDistance() ，触摸移动的距离不得超过QStyleHints::touchDoubleTapDistance() ，两次点击之间的时间间隔不得超过QStyleHints::mouseDoubleClickInterval() 。

另请参阅 MouseArea 和Qt Quick 示例 - 指针处理程序。

属性文档

acceptedButtons : flags

可以激活该指针处理程序的鼠标按钮。

默认情况下，该属性设置为Qt.LeftButton 。可以将其设置为鼠标按钮的 OR 组合，并忽略来自其他按钮的事件。

例如，一个控件可以用两种处理程序以不同方式对左右点击做出响应：

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

acceptedDevices : flags

可激活该指针处理程序的指向设备类型。

默认情况下，该属性设置为PointerDevice.AllDevices 。如果将其设置为设备类型的 OR 组合，则会忽略来自非匹配设备的事件。

例如，可以使用两个处理程序，以一种方式响应鼠标和手写笔点击，以另一种方式响应触摸屏轻触：

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : flags

如果设置了该属性，则需要按下给定的键盘修改键才能对指针事件做出反应，否则将忽略它们。

如果该属性设置为Qt.KeyboardModifierMask （默认值），则PointerHandler 会忽略修改键。

例如，Item 可以有两个相同类型的处理程序，其中一个只有在按下所需键盘修饰符时才启用：

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

如果将acceptedModifiers 设置为修改器按键的 OR 组合，则表示必须按下所有这些修改器才能激活处理程序：

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

可用的修改器如下：

如果需要比多个处理程序和多个修改器标志组合更复杂的行为，可以在 JavaScript 代码中检查修改器：

Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}

另请参见 Qt::KeyboardModifier 。

acceptedPointerTypes : flags

可激活该指针处理程序的指向工具类型（手指、触控笔、橡皮擦等）。

默认情况下，该属性设置为PointerDevice.AllPointerTypes 。如果将其设置为设备类型的 OR 组合，则会忽略来自非匹配devices 的事件。

例如，可以用两种处理程序使一个控件对鼠标、触摸和手写笔的点击作出某种响应，但如果用绘图板上的橡皮擦工具点击，该控件就会自行删除：

Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.Generic | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

active : bool [read-only]

只要该输入处理程序通过成功独占一个或多个eventPoints 点，从而独自负责处理一个或多个true 。这意味着该输入处理程序会根据这些事件点的移动更新其属性，并积极操作其target （如有）。

cursorShape : Qt::CursorShape

该属性用于保存鼠标悬停在parent 项目上时显示的光标形状，同时active 是true 。

可用的光标形状有

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

默认值未设置，允许cursor 的parent 项目出现。可通过将该属性设置为未定义来将其重置为相同的初始状态。

另请参阅 Qt::CursorShape 、QQuickItem::cursor() 和HoverHandler::cursorShape 。

dragThreshold : int

用户必须拖动eventPoint 才能被视为拖动手势的距离（以像素为单位）。

默认值取决于平台和屏幕分辨率。可以通过将其设置为未定义来将其重置为默认值。拖动手势开始时的行为在不同的处理程序中有所不同。

enabled : bool

如果PointerHandler 被禁用，它将拒绝所有事件，也不会发出任何信号。

如果PointerHandler 的parent 为disabled ，即使enabled 属性仍为true ，处理程序也将被禁用。

exclusiveSignals : enumeration [since 6.5]

确定singleTapped() 和doubleTapped() 信号的排他性。

此属性在 Qt 6.5 中引入。

gesturePolicy : enumeration

要识别轻按或长按手势的空间约束条件，以及释放必须在longPressThreshold 计时结束前发生的约束条件。如果不满足这些约束条件，就不会发出tapped 信号，也不会递增tapCount 。如果违反了空间限制，pressed 会立即从真转为假，而不管所持时间的长短。

gesturePolicy 还会影响抓取行为，详情如下。

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

Qt Quick Examples - Pointer Handlers演示了其中的一些用例。

grabPermissions : flags

该属性指定了当该处理程序的逻辑决定接管独占抓取时，或当该处理程序被其他处理程序要求批准接管或取消抓取时的权限。

默认值为PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ，允许大多数抓取场景，但可避免两个 PinchHandler 争夺同一个接触点。

longPressThreshold : real

如果eventPoint 的值大于0 ，则必须按下 才能触发长按手势并发出longPressed() 信号的时间（以秒为单位）。如果在此时间限制之前松开点，则可以在满足gesturePolicy 约束条件的情况下检测到点击。如果longPressThreshold 为0 ，则计时器被禁用，不会发出信号。如果longPressThreshold 设置为undefined ，则使用默认值，并可从该属性中读取默认值。

默认值是QStyleHints::mousePressAndHoldInterval() 转换为秒。

margin : real

超出parent 项目边界的余量，在此范围内eventPoint 可以激活此处理程序。例如，在PinchHandler 上，如果target 也是parent ，那么将其设置为至少为典型用户手指宽度一半的距离是非常有用的，这样，如果parent 被缩放到非常小，仍可实现捏合手势。或者，如果基于TapHandler 的按钮放置在屏幕边缘附近，则可用于遵守菲茨定律：即使按钮与屏幕边缘在视觉上相差几个像素，也会对屏幕边缘的鼠标点击做出反应。

默认值为 0。

parent : Item

作为处理程序作用域的Item ；也就是声明该处理程序的 Item。处理程序将代表该 Item 处理事件，这意味着如果指针事件中至少有一个eventPoints 出现在该 Item 的内部，那么该指针事件就是相关的。最初target() 是相同的，但可以重新分配。

另请参见 target 和QObject::parent()。

point : handlerPoint [read-only]

当前正在处理的eventPoint 。如果当前没有正在处理的点，该对象将重置为默认值（所有坐标均为 0）。

pressed : bool [read-only]

当鼠标或触摸点被按下时，pressed 将保持为真，且按下后的任何移动都符合当前的gesturePolicy 。当释放eventPoint 或违反策略时，按下将变为 false。

tapCount : int [read-only]

在规定的时间和空间内，被视为一个手势的点击次数。如果按钮发生变化，计数器将重置为 1。例如，要检测三次点击，可以写入以下内容

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

target : Item

该处理程序将处理的项目。

默认情况下，它与parent ，即处理程序所声明的 Item 相同。不过，有时也可以将目标设置为不同的项，以便处理一个项中的事件，但操作另一个项；或者将目标设置为null ，禁用默认行为，而执行其他操作。

timeHeld : real [read-only]

长按点在不超过拖动阈值的情况下保持的时间（以秒为单位）。每渲染一帧至少更新一次，这样就可以渲染一个动画，显示长按触发的动作的进展情况。此外，还可以根据长按时间触发一系列操作。

小于零的值表示该处理程序的Item 中没有按住任何点。

信号文档

canceled(eventPoint point)

如果此处理程序已经抓取了给定的point ，则当抓取被其他指针处理程序或项窃取时，将发出此信号。

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

当parent 项目在很短的时间（QStyleHints::mouseDoubleClickInterval() ）和距离（QStyleHints::mouseDoubleClickDistance() 或QStyleHints::touchDoubleTapDistance() ）内被点击两次时，就会发出该信号。该信号总是出现在singleTapped 、tapped 和tapCountChanged 之后。eventPoint 信号参数包含释放事件中有关被点击点的信息，而button 是被点击的mouse button ，或触摸屏上的NoButton 。

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

当抓取发生与该处理程序相关的某种变化时，就会发出该信号。

transition （动词）说明发生了什么。point （对象）是被抓取或未被抓取的点。

transition 的有效值是

longPressed()

当按住parent 项目的时间超过longPressThreshold 时，就会发出该信号。也就是说，如果您按住一个触摸点或按钮，而任何移动都没有超过拖动阈值，那么在timeHeld 超过longPressThreshold 时，就会发出longPressed 信号。

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

当parent 项目被点击一次时，就会发出该信号。经过大于QStyleHints::mouseDoubleClickInterval 的时间后，可以再次点击；但如果距离下一次点击的时间较短，tapCount 将增加。eventPoint 信号参数包含释放事件中关于被点击点的信息，而button 是被点击的mouse button ，或触摸屏上的NoButton 。

tapCountChanged()

当parent 项目被点击一次或多次（在指定的时间和距离范围内），并且当前的tapCount 与之前的tapCount 不同时，就会发出该信号。

tapped(eventPoint eventPoint, Qt::MouseButton button)

每次点击parent 项目时都会发出该信号。

也就是说，如果您在小于longPressThreshold 的时间段内按下并释放了触摸点或按钮，同时任何移动都没有超过拖动阈值，那么在释放时就会发出tapped 信号。eventPoint 信号参数包含释放事件中有关被点击点的信息，button 是被点击的mouse button ，或触摸屏上的NoButton 。

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}