建设通网站有建筑公司名录大全_南充房产网官网_自助建站网站模板_网站搜索引擎优化工具

Keys 附加属性是 QML 中处理键盘交互的主要方式，可以附加到任何 Item 上。

基本属性

属性	类型	默认值	说明
forwardTo	list	[]	将键盘事件转发给其他项目
enabled	bool	true	是否启用键盘处理

关键信号

信号	参数	说明
onPressed(KeyEvent event)	event: 键盘事件对象	按键按下时触发
onReleased(KeyEvent event)	event: 键盘事件对象	按键释放时触发
onShortcutOverride(KeyEvent event)	event: 键盘事件对象	快捷键冲突时触发

KeyEvent 对象详解

主要属性

属性	类型	说明
key	int	按键代码(如 Qt.Key_A)
text	string	实际输入的字符
modifiers	flags	修饰键状态(如 Ctrl/Shift)
isAutoRepeat	bool	是否自动重复触发
count	int	重复次数
accepted	bool	是否已处理该事件

常用按键代码

按键常量	值	对应按键
Qt.Key_0 - Qt.Key_9	48-57	数字键0-9
Qt.Key_A - Qt.Key_Z	65-90	字母键A-Z
Qt.Key_Left	0x01000012	左箭头
Qt.Key_Right	0x01000014	右箭头
Qt.Key_Up	0x01000013	上箭头
Qt.Key_Down	0x01000015	下箭头
Qt.Key_Enter	0x01000005	回车键
Qt.Key_Return	0x01000004	返回键
Qt.Key_Escape	0x01000000	ESC键
Qt.Key_Space	0x20	空格键
Qt.Key_Tab	0x01000001	Tab键
Qt.Key_Backspace	0x01000003	退格键
Qt.Key_Delete	0x01000007	删除键

修饰键标志

修饰键常量	值	说明
Qt.NoModifier	0x00000000	无修饰键
Qt.ShiftModifier	0x02000000	Shift键
Qt.ControlModifier	0x04000000	Ctrl键
Qt.AltModifier	0x08000000	Alt键
Qt.MetaModifier	0x10000000	Meta键(Windows键)

焦点管理

关键属性

属性	类型	默认值	说明
focus	bool	false	是否接受键盘焦点
activeFocus	bool	false	只读，是否实际拥有焦点
KeyNavigation.tab	Item	null	Tab键导航目标
KeyNavigation.backtab	Item	null	Shift+Tab导航目标
KeyNavigation.up	Item	null	上箭头导航目标
KeyNavigation.down	Item	null	下箭头导航目标
KeyNavigation.left	Item	null	左箭头导航目标
KeyNavigation.right	Item	null	右箭头导航目标

焦点相关方法

方法	参数	返回值	说明
forceActiveFocus()	-	-	强制获取焦点
nextItemInFocusChain()	-	Item	获取焦点链中下一个项目

实用代码示例

基本按键处理

qml

import QtQuick 2.15Item {width: 200; height: 200focus: trueKeys.onPressed: {switch(event.key) {case Qt.Key_Left:console.log("左箭头按下");break;case Qt.Key_Right:console.log("右箭头按下");break;case Qt.Key_Space:console.log("空格键按下");break;}// 检查组合键if ((event.key === Qt.Key_S) && (event.modifiers & Qt.ControlModifier)) {console.log("Ctrl+S 保存操作");event.accepted = true;}}
}

焦点链管理

qml

import QtQuick 2.15
import QtQuick.Controls 2.15Column {spacing: 10TextField {id: field1placeholderText: "第一个输入框"KeyNavigation.tab: field2}TextField {id: field2placeholderText: "第二个输入框"KeyNavigation.tab: field3KeyNavigation.backtab: field1}Button {id: field3text: "按钮"KeyNavigation.backtab: field2Keys.onReturnPressed: console.log("按钮被回车激活")}
}

快捷键处理

qml

Item {focus: true// 处理复制快捷键Keys.onShortcutOverride: {if (event.matches(StandardKey.Copy)) {event.accepted = true}}Keys.onPressed: {if (event.matches(StandardKey.Copy)) {console.log("执行复制操作")event.accepted = true}}
}

高级键盘处理

全局快捷键

qml

import QtQuick 2.15
import QtQuick.Window 2.15Window {width: 400; height: 300visible: trueItem {anchors.fill: parentfocus: true// F11全屏切换Keys.onPressed: {if (event.key === Qt.Key_F11) {visibility === Window.FullScreen ? showNormal() : showFullScreen()}}}
}

按键序列检测

qml

Item {property var keySequence: []focus: trueKeys.onPressed: {keySequence.push(event.key)if (keySequence.length > 3) keySequence.shift()// 检测上上下下左右左右BAif (keySequence.length === 8 &&keySequence[0] === Qt.Key_Up &&keySequence[1] === Qt.Key_Up &&keySequence[2] === Qt.Key_Down &&keySequence[3] === Qt.Key_Down &&keySequence[4] === Qt.Key_Left &&keySequence[5] === Qt.Key_Right &&keySequence[6] === Qt.Key_Left &&keySequence[7] === Qt.Key_Right) {console.log("Konami code detected!")keySequence = []}}
}

虚拟键盘集成

qml

import QtQuick 2.15
import QtQuick.VirtualKeyboard 2.15ApplicationWindow {id: windowwidth: 800height: 600TextField {anchors.centerIn: parentwidth: 200placeholderText: "点击输入..."}InputPanel {id: keyboardanchors.bottom: parent.bottomanchors.left: parent.leftanchors.right: parent.rightvisible: Qt.inputMethod.visible}
}

键盘交互最佳实践

1. 明确的焦点指示：为获得焦点的项目提供视觉反馈

2. 合理的Tab顺序：确保逻辑化的焦点导航顺序

3. 平台一致性：遵循目标平台的快捷键惯例

4. 无障碍支持：确保所有功能都能通过键盘访问

5. 性能优化：避免在按键事件中进行重操作

6. 错误处理：为无效输入提供反馈

7. 文档说明：为复杂快捷键提供使用说明