QML 键盘交互

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

基本属性

关键信号

KeyEvent 对象详解

主要属性

常用按键代码

修饰键标志

焦点管理

关键属性

焦点相关方法

实用代码示例

基本按键处理

qml

import QtQuick 2.15

Item {
    width: 200; height: 200
    focus: true
    
    Keys.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.15

Column {
    spacing: 10
    
    TextField {
        id: field1
        placeholderText: "第一个输入框"
        KeyNavigation.tab: field2
    }
    
    TextField {
        id: field2
        placeholderText: "第二个输入框"
        KeyNavigation.tab: field3
        KeyNavigation.backtab: field1
    }
    
    Button {
        id: field3
        text: "按钮"
        KeyNavigation.backtab: field2
        Keys.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.15

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

按键序列检测

qml

Item {
    property var keySequence: []
    focus: true
    
    Keys.onPressed: {
        keySequence.push(event.key)
        if (keySequence.length > 3) keySequence.shift()
        
        // 检测上上下下左右左右BA
        if (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.15

ApplicationWindow {
    id: window
    width: 800
    height: 600
    
    TextField {
        anchors.centerIn: parent
        width: 200
        placeholderText: "点击输入..."
    }
    
    InputPanel {
        id: keyboard
        anchors.bottom: parent.bottom
        anchors.left: parent.left
        anchors.right: parent.right
        visible: Qt.inputMethod.visible
    }
}

键盘交互最佳实践

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

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

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

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

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

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

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