QML 中的键盘事件

在 QML 中，键盘事件为用户界面提供了与鼠标操作类似的交互方式。通过捕捉键盘事件，我们可以让用户通过按键与界面进行交互，这对于实现键盘导航、快捷键等功能非常重要。

前言

QML 为处理键盘事件提供了 Keys 属性。Keys 允许我们对键盘按键的按下和释放做出响应，并通过 KeyEvent 传递详细信息。Keys 的使用不仅限于通用按键事件，还支持专用的键盘事件。

通用键盘事件

QML 提供了两个基本的键盘事件处理信号：

• pressed(KeyEvent event)：处理按键按下事件。
• released(KeyEvent event)：处理按键释放事件。

KeyEvent 类型的参数包含按键的详细信息，包括按键的文本值和编码值等。

示例：使用方向键移动矩形

在此例中，我们将使用方向键来控制矩形的移动：

import QtQuick

Rectangle {
    width: 100
    height: 100
    color: activeFocus ? "green" : "black"

    // 通过 Tab 键或点击鼠标来获取焦点
    activeFocusOnTab: true
    MouseArea {
        anchors.fill: parent
        onClicked: parent.forceActiveFocus()
    }

    // 键盘按下事件处理
    Keys.onPressed: (event) => {
        console.info("Key %1(%2) was pressed".arg(event.text).arg(event.key))

        switch(event.key) {
        case Qt.Key_Left:
            x -= 10;
            break;
        case Qt.Key_Right:
            x += 10;
            break;
        case Qt.Key_Up:
            y -= 10;
            break;
        case Qt.Key_Down:
            y += 10;
            break;
        default:
            return;
        }
    }
}

在这个例子中，矩形元素的颜色会根据焦点状态变化，按下方向键时，矩形会在窗口中移动。

专用键盘事件

除了 pressed 和 released 这两个通用事件外，Keys 还提供了许多专用的键盘事件。例如：

• backPressed(KeyEvent event)：退格键“Backspace”
• deletePressed(KeyEvent event)：删除键“Delete”
• enterPressed(KeyEvent event)：回车键“Enter”
• spacePressed(KeyEvent event)：空格键
• tabPressed(KeyEvent event)：Tab 键

这些事件非常直观，可以帮助你区分不同的按键操作，进行专门的处理。

示例：处理专用的方向键

Rectangle {
    width: 100
    height: 100
    color: activeFocus ? "green" : "black"

    activeFocusOnTab: true
    MouseArea {
        anchors.fill: parent
        onClicked: parent.forceActiveFocus()
    }

    // 专用的方向键事件
    Keys.onLeftPressed: {
        x -= 10;
    }
    Keys.onRightPressed: {
        x += 10;
    }
    Keys.onUpPressed: {
        y -= 10;
    }
    Keys.onDownPressed: {
        y += 10;
    }
}

这个示例使用了专用的方向键事件处理方法，使得按键操作更加简洁。

组合键

有时候，我们需要处理组合键，例如按下“Ctrl + Shift + 方向键”来实现某种操作。在 QML 中，可以通过 KeyEvent 的 modifiers 属性来检测是否有修饰键（如 Ctrl、Shift、Alt）与其他按键组合。

示例：使用 Ctrl + Shift + 方向键

Rectangle {
    width: 100
    height: 100
    color: activeFocus ? "green" : "black"

    activeFocusOnTab: true
    MouseArea {
        anchors.fill: parent
        onClicked: parent.forceActiveFocus()
    }

    // Ctrl + Shift + 方向键
    Keys.onPressed: (event) => {
        if ((event.modifiers & Qt.ControlModifier) && (event.modifiers & Qt.ShiftModifier)) {
            switch(event.key) {
            case Qt.Key_Left:
                x -= 10;
                break;
            case Qt.Key_Right:
                x += 10;
                break;
            case Qt.Key_Up:
                y -= 10;
                break;
            case Qt.Key_Down:
                y += 10;
                break;
            default:
                return;
            }
        }
    }
}

此代码块检查是否按下了 Ctrl 和 Shift 键，并响应相应的方向键移动操作。

事件传递

QML 中的键盘事件通常会根据元素的焦点状态传递。然而，如果界面中有多个元素需要响应键盘事件，事件如何传递呢？Keys.forwardTo 属性帮助我们控制事件的传递顺序，确保事件能够传递给多个元素。

示例：事件传递

Rectangle {
    id: rect
    width: 150
    height: 150
    color: activeFocus ? "green" : "black"

    activeFocusOnTab: true
    MouseArea {
        anchors.fill: parent
        onClicked: parent.forceActiveFocus()
    }

    Keys.forwardTo: [subRect2, subRect1]

    RowLayout {
        anchors.fill: parent
        anchors.margins: 10
        spacing: 10

        Rectangle {
            id: subRect1
            width: 50
            height: 50
            color: "orange"
            Keys.onPressed: (event) => {
                console.info("subRect1 pressed")
                switch(event.key) {
                case Qt.Key_Left:
                    x -= 10;
                    break;
                case Qt.Key_Right:
                    x += 10;
                    break;
                case Qt.Key_Up:
                    y -= 10;
                    break;
                case Qt.Key_Down:
                    y += 10;
                    break;
                }
            }
        }

        Rectangle {
            id: subRect2
            width: 50
            height: 50
            color: "orange"
            Keys.onPressed: (event) => {
                console.info("subRect2 pressed")
                switch(event.key) {
                case Qt.Key_Left:
                    x -= 10;
                    break;
                case Qt.Key_Right:
                    x += 10;
                    break;
                case Qt.Key_Up:
                    y -= 10;
                    event.accepted = true;  // 表明事件已被处理
                    break;
                case Qt.Key_Down:
                    y += 10;
                    event.accepted = true;
                    break;
                }
            }
        }
    }
}

通过 Keys.forwardTo 属性，我们设置了事件的传递顺序为 subRect2 和 subRect1。当按键事件触发时，首先由 subRect2 处理，如果 subRect2 没有处理（即 event.accepted = false），事件会继续传递给 subRect1。

键盘导航

在需要通过方向键或 Tab 键进行元素间导航的场景中，QML 提供了 KeyNavigation 属性，帮助我们轻松实现焦点的切换。

示例：键盘导航

GridLayout {
    width: 100; height: 100
    columns: 2

    Rectangle {
        id: topLeft
        width: 50; height: 50
        color: activeFocus ? "green" : "black"
        MouseArea {
            anchors.fill: parent
            onClicked: parent.forceActiveFocus()
        }

        KeyNavigation.right: topRight
        KeyNavigation.down: bottomLeft
    }

    Rectangle {
        id: topRight
        width: 50; height: 50
        color: activeFocus ? "green" : "black"
        KeyNavigation.left: topLeft
        KeyNavigation.down: bottomRight
    }

    Rectangle {
        id: bottomLeft
        width: 50; height: 50
        color: activeFocus ? "green" : "black"
        KeyNavigation.right: bottomRight
        KeyNavigation.up: topLeft
    }

    Rectangle {
        id: bottomRight
        width: 50; height: 50
        color: activeFocus ? "green" : "black"
        KeyNavigation.left: bottomLeft
        KeyNavigation.up: topRight
    }
}

此示例展示了一个 2x2 的矩形网格布局，每个矩形都可以通过方向键进行焦点导航，焦点状态通过颜色变化直观地显示。

总结

QML 提供了强大的键盘事件支持，通过 Keys 和 KeyNavigation，我们可以轻松实现键盘交互和焦点管理。无论是处理单个按键、组合键、事件传递，还是键盘导航，都能为用户提供丰富的交互体验。