Keys QML Type

为项目提供键处理。更多

Import Statement: import QtQuick

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

属性

enabled : bool
forwardTo : list<Item>
priority : enumeration

信号

asteriskPressed(KeyEvent event)
backPressed(KeyEvent event)
backtabPressed(KeyEvent event)
callPressed(KeyEvent event)
cancelPressed(KeyEvent event)
context1Pressed(KeyEvent event)
context2Pressed(KeyEvent event)
context3Pressed(KeyEvent event)
context4Pressed(KeyEvent event)
deletePressed(KeyEvent event)
digit0Pressed(KeyEvent event)
digit1Pressed(KeyEvent event)
digit2Pressed(KeyEvent event)
digit3Pressed(KeyEvent event)
digit4Pressed(KeyEvent event)
digit5Pressed(KeyEvent event)
digit6Pressed(KeyEvent event)
digit7Pressed(KeyEvent event)
digit8Pressed(KeyEvent event)
digit9Pressed(KeyEvent event)
downPressed(KeyEvent event)
enterPressed(KeyEvent event)
escapePressed(KeyEvent event)
flipPressed(KeyEvent event)
hangupPressed(KeyEvent event)
leftPressed(KeyEvent event)
menuPressed(KeyEvent event)
noPressed(KeyEvent event)
pressed(KeyEvent event)
released(KeyEvent event)
returnPressed(KeyEvent event)
rightPressed(KeyEvent event)
selectPressed(KeyEvent event)
shortcutOverride(KeyEvent event)
spacePressed(KeyEvent event)
tabPressed(KeyEvent event)
upPressed(KeyEvent event)
volumeDownPressed(KeyEvent event)
volumeUpPressed(KeyEvent event)
yesPressed(KeyEvent event)

详细说明

所有可视化基元都通过 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 。

按键处理优先级

可对附加的按键属性进行配置，以在其所附加的项目之前或之后处理按键事件。这样就可以拦截事件以覆盖项目的默认行为，或作为项目未处理的按键的后备。

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

在forwardTo
特定按键处理程序中指定的项目，例如 onReturnPressed
onPressed、onReleased 处理程序
项目特定按键处理，例如TextInput 按键处理
父项

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

项目特定按键处理，例如TextInput 按键处理
在forwardTo
特定按键处理程序中指定的项目，例如 onReturnPressed
onPressed、onReleased 处理程序
父项

如果事件在上述任何步骤中被接受，按键传播就会停止。

另请参阅 KeyEvent 和KeyNavigation attached property 。

属性文档

enabled : bool

如果为 true（默认值），该标志将启用按键处理；否则将不调用按键处理程序。

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`	在正常的项目按键处理之后处理按键事件。如果项目接受了按键事件，则不会由按键附加属性处理程序进行处理。

另请参阅 Key Handling Priorities 。

信号文档

asteriskPressed(KeyEvent event)

星号 "*"被按下时会发出该信号。event 参数提供了事件的相关信息。

注：相应的处理程序是onAsteriskPressed 。

backPressed(KeyEvent event)

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

注：相应的处理程序是onBackPressed 。

backtabPressed(KeyEvent event)

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

注：相应的处理程序是onBacktabPressed 。

callPressed(KeyEvent event)

按下 Call 键时发出该信号。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)

按下 Enter 键时发出该信号。event 参数提供了事件的相关信息。

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

escapePressed(KeyEvent event)

按下 Escape 键时发出该信号。event 参数提供了事件的相关信息。

注：相应的处理程序是onEscapePressed 。

flipPressed(KeyEvent event)

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

注：相应的处理程序是onFlipPressed 。

hangupPressed(KeyEvent event)

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

注：相应的处理程序是onHangupPressed 。

leftPressed(KeyEvent event)

按下 "向左 "键时发出该信号。event 参数提供了有关该事件的信息。

注：相应的处理程序是onLeftPressed 。

menuPressed(KeyEvent event)

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

注：相应的处理程序是onMenuPressed 。

noPressed(KeyEvent event)

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

注：相应的处理程序是onNoPressed 。

pressed(KeyEvent event)

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

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

released(KeyEvent event)

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

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

returnPressed(KeyEvent event)

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

注：相应的处理程序是onReturnPressed 。

rightPressed(KeyEvent event)

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

注：相应的处理程序是onRightPressed 。

selectPressed(KeyEvent事件）

按下选择键时发出该信号。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)

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

注：相应的处理程序是onVolumeDownPressed 。

volumeUpPressed(KeyEvent event)

按下 "音量增大 "键时发出该信号。event 参数提供了有关该事件的信息。

注：相应的处理程序是onVolumeUpPressed 。

yesPressed(KeyEvent event)

按下 "Yes"（是）键时发出该信号。event 参数提供了有关该事件的信息。

注：相应的处理程序是onYesPressed 。

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