【Qt6 QML Book 基础】08：输入元素（附完整可运行代码）

原创于 2025-04-24 15:00:17 发布 · 608 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#qt6 #qml6 #qt6qml #qml6book #c++ #javascript

Qt6Qml基础专栏收录该内容

15 篇文章

订阅专栏

引言

在 Qt Quick 应用开发中，输入组件是构建交互式界面的核心元素。合理设计输入组件的视觉样式、焦点逻辑与键盘交互，直接影响用户体验。本文结合《Qt6 QML Book》官方示例，从基础组件TextInput/TextEdit的核心特性出发，解析自定义输入组件时的焦点问题，演示如何通过FocusScope和KeyNavigation实现高效键盘交互。

一、运行效果图

二、基础输入组件：TextInput 的核心特性

2.1 基础用法与视觉呈现

TextInput是单行文本输入的基础组件，支持输入约束（validator、inputMask）、回显模式（echoMode）等特性。以下是一个基础示例：

// TextInputExample.qml
Rectangle {
    width: 200; height: 80; color: "linen"
    TextInput {
        id: input1; x: 8; y: 8; width: 96; height: 20
        focus: true; text: "Text Input 1" // 初始聚焦
    }
    TextInput {
        id: input2; x: 8; y: 36; width: 96; height: 20
        text: "Text Input 2"
    }
}

关键点：

focus: true：设置初始焦点
视觉上仅显示文本和闪烁光标，需通过容器组件添加边框等装饰

2.2 键盘焦点切换：KeyNavigation

通过KeyNavigation附加属性实现键盘焦点切换，例如 Tab 键切换：

// Tab键焦点切换示例
TextInput {
    id: input1
    KeyNavigation.tab: input2  // 按下Tab键时焦点切换到input2
}
TextInput {
    id: input2
    KeyNavigation.tab: input1  // 按下Tab键时焦点切换回input1
}

关键点：

支持tab、backtab（Shift+Tab）等预设导航键
直接绑定目标组件 ID 即可实现焦点转移

三、自定义输入组件：从 TLineEditV1 到 V2

3.1 基础封装（TLineEditV1）

为提升复用性，将TextInput封装到带边框的矩形组件中（视觉封装与属性暴露），为统一输入组件样式，需将TextInput封装到自定义组件中。

初始版本TLineEditV1使用Rectangle作为容器：

// TLineEditV1.qml（焦点问题版本）
Rectangle {
    width: 96; height: input.height + 8
    color: "lightsteelblue"; border.color: "gray"
    property alias text: input.text  // 暴露文本属性
    property alias input: input      // 暴露原始组件
    TextInput {
        id: input
        anchors.fill: parent; anchors.margins: 4
        focus: true  // 焦点设置在内部TextInput
    }
}

问题：当外部通过KeyNavigation切换焦点时，焦点会停留在外层Rectangle而非内部TextInput，导致输入无响应。

3.2 焦点作用域：FocusScope（TLineEditV2）

FocusScope是解决焦点传递问题的关键组件，其核心机制是：当焦点作用于焦点范围时，焦点会自动转发给最后一个声明focus: true的子元素。

修正后的TLineEditV2以FocusScope为根元素：

// TLineEditV2.qml（焦点正确传递版本）
import QtQuick

FocusScope {
    width: 96; height: input.height + 8
    Rectangle {
        anchors.fill: parent
        color: "lightsteelblue"
        border.color: "gray"

    }

    property alias text: input.text
    property alias input: input

    TextInput {
        id: input
        anchors.fill: parent
        anchors.margins: 4
        focus: true // 子元素声明焦点，FocusScope负责转发
    }
}

关键点：

FocusScope会将焦点传递给最后一个声明focus: true的子组件
确保焦点始终作用于内部TextInput，而非容器元素
解决自定义组件的焦点隔离问题，确保键盘导航正常工作

四、多行文本编辑：TextEdit 的组件化封装

TextEdit支持多行文本输入，无输入约束属性，但需处理焦点与视觉封装。基于FocusScope的自定义组件TTextEdit实现如下：

// TTextEdit.qml
import QtQuick

FocusScope {
    width: 96; height: 96
    Rectangle {
        anchors.fill: parent
        color: "lightsteelblue"
        border.color: "gray"
    }

    property alias text: input.text
    property alias input: input

    TextEdit {
        id: input
        anchors.fill: parent
        anchors.margins: 4
        focus: true
    }
}

使用场景：

典型应用：日志输入、备注编辑、用户评论等需要多行输入的场景
可通过contentHeight、contentWidth获取内容区域尺寸

五、键盘事件处理：Keys 附加属性与焦点协同管理

在 QML 中，Keys附加属性是处理键盘输入的核心机制。当界面包含多标签页（如TabBar）时，需结合焦点管理确保键盘事件精准作用于目标组件。以下通过实际案例解析复杂场景下的键盘交互实现。

5.1 键盘事件核心：Keys 附加属性

Keys附加属性允许在任意组件上监听键盘事件，通过event.key获取按键枚举值（需导入QtQuick），并通过event.accepted控制事件传播：

// KeysExample.qml核心逻辑
DarkSquare {
    width: 400; height: 200; focus: true // 必须显式声明焦点
    Keys.onPressed: event => {
        if (handleControlKeys(event)) { // 自定义逻辑处理
            event.accepted = true // 阻止事件向上冒泡
        }
    }
    function handleControlKeys(event) {
        switch(event.key) {
            // 移动控制（边界限制）
        case Qt.Key_Left:
            square.x = Math.max(8, square.x - 8)
            return true
        case Qt.Key_Right:
            square.x = Math.min(width - square.width - 8, square.x + 8)
            return true
        case Qt.Key_Up:
            square.y = Math.max(8, square.y - 8)
            return true
        case Qt.Key_Down:
            square.y = Math.min(height - square.height - 8, square.y + 8)
            return true
            // 缩放控制（范围限制)
        case Qt.Key_Plus:
            square.scale = Math.min(3.0, square.scale + 0.2)
            return true
        case Qt.Key_Minus:
            square.scale = Math.max(0.5, square.scale - 0.2)
            return true
        }
        return false
    }
    GreenSquare { id: square; /* 初始位置 */ } // 受控的可移动方块
}

焦点前提：组件必须声明focus: true或通过forceActiveFocus()获取焦点，否则键盘事件无法触发
事件拦截：返回true表示事件已处理，阻止父组件（如标签页容器）响应相同按键
边界计算：通过Math.max/min确保方块不超出背景区域，提升交互体验
缩放逻辑：限制缩放范围（0.5-3.0），避免组件尺寸异常
视觉提示：底部文本明确操作方式，增强用户引导

5.2 多标签页焦点管理：FocusScope 与自动聚焦

当键盘控制组件位于StackLayout标签页中时，需通过FocusScope隔离焦点域，并在页面激活时强制获取焦点：

// 示例6：键盘控制
// 新增键盘控制示例项
FocusScope {  // 焦点作用域根元素，隔离标签页间的焦点干扰
    id: keyControlPage

    KeysExample {
        id: keysExample
        anchors.centerIn: parent
        scale: 1.5

        // 禁用Tab键切换焦点（避免与TabBar切换冲突）
        KeyNavigation.tab: undefined
        KeyNavigation.backtab: undefined
    }

    // 页面激活时自动获取焦点
    onVisibleChanged: if (visible) keysExample.forceActiveFocus()
}

FocusScope 作用：确保焦点仅在当前标签页内传递，避免切换标签后焦点残留
forceActiveFocus()：标签页切换到 “键盘控制” 时，强制将焦点赋予KeysExample组件，确保首次按键即生效
禁用 Tab 导航：通过KeyNavigation.tab: undefined阻止组件响应 Tab 键，避免与顶部TabBar的切换逻辑冲突

六、组件设计原则

6.1 组件化封装三要素

视觉封装：通过容器元素（Rectangle、FocusScope）统一样式
属性暴露：使用property alias导出核心属性（text、focus、input）
焦点管理：始终通过 FocusScope 确保子组件焦点有效传递

6.2 代码复用策略

将通用输入组件（TLineEdit、TTextEdit）存入公共组件库
通过scale属性实现组件缩放适配不同分辨率（如示例中的scale: 1.5）
使用StackLayout+TabBar实现多示例页面切换，提升代码组织性

七、总结

QML 输入元素通过灵活的组件组合和焦点管理，能够实现丰富的交互场景。掌握TextInput/TextEdit的基础用法、KeyNavigation的键盘导航、FocusScope的焦点传递，以及Keys的事件处理，是构建高效用户界面的关键。后续可结合validator、inputMask等属性实现更复杂的输入校验逻辑。通过合理运用 QML 的焦点管理机制与组件化设计，开发者可高效构建交互友好、风格统一的输入界面，为复杂业务场景奠定坚实基础。

掌握以下要点可显著提升开发效率：