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

Keys QML Type (Uncreatable)

为 Items 提供键处理功能。更多...

Import Statement: import QtQuick

注意：这是一个不可创建的类型。无法在 QML 中对其进行实例化。

属性

信号

详细说明

所有视觉基元均支持通过“Keys”连接类型进行按键处理。可通过 onPressed 和 onReleased 信号属性处理按键。

这些信号属性有一个名为KeyEvent 的参数，名为event，其中包含事件的详细信息。如果处理了某个按键，应将event.accepted设置为true，以防止事件向上传播到项目层次结构中。

使用示例

以下示例演示了如何使用通用的 onPressed 处理程序来检测特定按键；此处以左方向键为例：

Item {
    anchors.fill: parent
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
}

某些按键也可以通过特定的信号属性（例如onSelectPressed）进行处理。这些处理程序会自动将event.accepted设置为 true。

Item {
    anchors.fill: parent
    focus: true
    Keys.onLeftPressed: console.log("move left")
}

键盘代码列表请参见Qt.Key 。

键处理优先级

“Keys”的附加类型可配置为在所附加项之前或之后处理键事件。这使得可以拦截事件以覆盖项的默认行为，或作为该项未处理键的备用方案。

如果priority 的值为 Keys.BeforeItem（默认值），则键事件的处理顺序为：

  1. 在forwardTo
  2. 特定键处理程序中指定的项，例如 onReturnPressed
  3. onPressed、onReleased 处理程序
  4. 项目特有的键处理，例如TextInput 键处理
  5. 父项

如果优先级为 Keys.AfterItem，则键事件处理的顺序为：

  1. 特定于项的键处理，例如TextInput 键处理
  2. 在forwardTo
  3. 特定键处理程序中指定的项目，例如 onReturnPressed
  4. onPressed、onReleased 处理程序
  5. 父项

如果在上述任何一步中事件被接受，键传播将停止。

另请参阅 KeyEvent 和KeyNavigation attached property 。

属性文档

enabled : bool

如果该标志为真（默认值），则启用键处理；否则不会调用任何键处理程序。

forwardTo : list<Item> [read-only]

该属性提供了一种将按键按下、按键释放以及来自输入法（如键盘）的输入转发给其他项的方法。当您希望某个项处理某些按键（例如向上和向下箭头键），而另一个项处理其他按键（例如向左和向右箭头键）时，此功能会非常有用。 一旦接收了转发键事件的控件接受了该事件，该事件就不再转发给列表中后续的控件。

此示例将键盘事件转发给两个列表：

Item {
    ListView {
        id: list1
        // ...
    }
    ListView {
        id: list2
        // ...
    }
    Keys.forwardTo: [list1, list2]
    focus: true
}

要了解使用 forwardTo 时事件的接收顺序，请参阅Key Handling Priorities 。

priority : enumeration

此属性决定是在附加项自身键处理之前还是之后处理这些键。

常量描述
Keys.BeforeItem(默认) 在常规项目键处理之前处理键事件。如果事件被接受，则不会将其传递给该项目。
Keys.AfterItem在常规项键处理之后处理键事件。如果项接受了键事件，则该事件不会由“Keys”附加属性处理程序处理。

另请参阅 Key Handling Priorities 。

Signal 文档

asteriskPressed(KeyEvent event)

按下星号“*”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onAsteriskPressed 。

backPressed(KeyEvent event)

按下“返回”键时会触发此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onBackPressed 。

backtabPressed(KeyEvent event)

当按下 Shift+Tab 组合键（Backtab）时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onBacktabPressed 。

callPressed(KeyEvent event)

按下“呼叫”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onCallPressed 。

cancelPressed(KeyEvent event)

按下“取消”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onCancelPressed 。

context1Pressed(KeyEvent event)

当按下 Context1 键时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onContext1Pressed 。

context2Pressed(KeyEvent event)

当按下 Context2 键时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onContext2Pressed 。

context3Pressed(KeyEvent event)

当按下 Context3 键时，会发出此信号。event 参数提供了有关该事件的信息。

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

context4Pressed(KeyEvent event)

当按下 Context4 键时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onContext4Pressed 。

deletePressed(KeyEvent event)

按下 Delete 键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDeletePressed 。

digit0Pressed(KeyEvent event)

当按下数字“0”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onDigit0Pressed 。

digit1Pressed(KeyEvent event)

当按下数字“1”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit1Pressed 。

digit2Pressed(KeyEvent event)

当按下数字“2”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit2Pressed 。

digit3Pressed(KeyEvent event)

当按下数字“3”时，会发出此信号。event 参数提供了有关该事件的信息。

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

digit4Pressed(KeyEvent event)

当按下数字“4”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit4Pressed 。

digit5Pressed(KeyEvent event)

当按下数字“5”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit5Pressed 。

digit6Pressed(KeyEvent event)

当按下数字“6”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit6Pressed 。

digit7Pressed(KeyEvent event)

当按下数字“7”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit7Pressed 。

digit8Pressed(KeyEvent event)

当按下数字“8”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onDigit8Pressed 。

digit9Pressed(KeyEvent event)

当按下数字“9”时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onDigit9Pressed 。

downPressed(KeyEvent event)

按下向下箭头键时会发出此信号。event 参数提供了有关该事件的信息。

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

enterPressed(KeyEvent event)

按下回车键时会发出此信号。event 参数提供了有关该事件的信息。

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

escapePressed(KeyEvent event)

按下Esc键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onEscapePressed 。

flipPressed(KeyEvent event)

按下“翻转”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onFlipPressed 。

hangupPressed(KeyEvent event)

按下挂断键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onHangupPressed 。

leftPressed(KeyEvent event)

按下左箭头键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onLeftPressed 。

按下“菜单”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onMenuPressed 。

noPressed(KeyEvent event)

当按下“No”键时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onNoPressed 。

pressed(KeyEvent event)

按下按键时会触发此信号。event 参数提供了有关该事件的信息。

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

released(KeyEvent event)

当按键被释放时，会发出此信号。event 参数提供了有关该事件的信息。

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

returnPressed(KeyEvent event)

按下“返回”键时会发出此信号。event 参数提供了有关该事件的信息。

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

rightPressed(KeyEvent event)

按下“向右箭头”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onRightPressed 。

selectPressed(KeyEvent event)

按下“选择”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onSelectPressed 。

shortcutOverride(KeyEvent event)

当按下某个可能用作快捷键的键时，会发出此信号。event 参数提供了有关该事件的信息。

若希望阻止被按下的键被其他类型（如Shortcut ）用作快捷键，请将event.accepted 设置为true 。例如：

Item {
    id: escapeItem
    focus: true

    // Ensure that we get escape key press events first.
    Keys.onShortcutOverride: (event)=> event.accepted = (event.key === Qt.Key_Escape)

    Keys.onEscapePressed: {
        console.log("escapeItem is handling escape");
        // event.accepted is set to true by default for the specific key handlers
    }
}

Shortcut {
    sequence: "Escape"
    onActivated: console.log("Shortcut is handling escape")
}

与其他信号一样，只有当项目具有“activeFocus ”属性时，该项目才会发出shortcutOverride 信号。

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

另请参阅 Shortcut 。

spacePressed(KeyEvent event)

按下空格键时会触发此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onSpacePressed 。

tabPressed(KeyEvent event)

按下 Tab 键时会触发此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onTabPressed 。

upPressed(KeyEvent event)

当按下向上箭头键时，会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onUpPressed 。

volumeDownPressed(KeyEvent event)

按下“音量减小”键时会触发此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onVolumeDownPressed 。

volumeUpPressed(KeyEvent event)

按下“音量增大”键时会触发此信号。event 参数提供了有关该事件的信息。

注意： 对应的处理程序 是onVolumeUpPressed 。

yesPressed(KeyEvent event)

按下“是”键时会发出此信号。event 参数提供了有关该事件的信息。

注意： 相应的处理程序 为onYesPressed 。

© 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.