用例 - 在 QML 中响应用户输入

支持的用户输入类型

QML Qt Quick模块支持最常见的用户输入类型，包括鼠标和触摸事件、文本输入和按键事件。其他模块支持其他类型的用户输入。

本文将介绍如何处理基本的用户输入。有关视听输入的信息，请参阅 Qt Multimedia文档。

鼠标和触摸事件

输入处理程序让 QML 应用程序处理鼠标和触摸事件。例如，你可以通过添加TapHandler 到 Image，或添加到Rectangle （内含Text 对象）来创建按钮。TapHandler 会响应任何类型指向设备上的点击或单击。

import QtQuick

Item {
    id: root

    width: 320
    height: 480

    Rectangle {
        color: "#272822"
        width: 320
        height: 480
    }

    Rectangle {
        id: rectangle
        x: 40
        y: 20
        width: 120
        height: 120
        color: "red"

        TapHandler {
            onTapped: rectangle.width += 10
        }
    }
}

注：某些项目类型有自己的内置输入处理功能。例如，Flickable 会响应鼠标拖动、触摸滑动和鼠标滚轮滚动。

键盘和按键事件

通过设备上的按钮、键盘或键盘按下按钮和按键，都可以使用Keys 附加属性进行处理。该附加属性适用于所有Item 派生类型，并与Item::focus 属性配合使用，以确定接收按键事件的类型。对于简单的按键处理，可以在单个Item 上将焦点设置为 true，并在该处完成所有按键处理。

import QtQuick

Item {
    id: root

    width: 320
    height: 480

    Rectangle {
        color: "#272822"
        width: 320
        height: 480
    }

    Rectangle {
        id: rectangle
        x: 40
        y: 20
        width: 120
        height: 120
        color: "red"

        focus: true
        Keys.onUpPressed: rectangle.y -= 10
        Keys.onDownPressed: rectangle.y += 10
        Keys.onLeftPressed: rectangle.x += 10
        Keys.onRightPressed: rectangle.x -= 10
    }
}

对于文本输入，我们有几种 QML 类型可供选择。TextInput 提供了无样式的单行可编辑文本，而TextField 更适合应用程序中的表单字段。TextEdit 可以处理多行可编辑文本，但TextArea 是更好的选择，因为它增加了样式。

下面的代码段演示了如何在应用程序中使用这些类型：

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

ApplicationWindow {
    width: 300
    height: 200
    visible: true

    ColumnLayout {
        anchors.fill: parent
        TextField {
            id: singleline
            text: "Initial Text"
            Layout.alignment: Qt.AlignHCenter | Qt.AlignTop
            Layout.margins: 5
            background: Rectangle {
               implicitWidth: 200
               implicitHeight: 40
               border.color: singleline.focus ? "#21be2b" : "lightgray"
               color: singleline.focus ? "lightgray" : "transparent"
            }
        }

        TextArea {
            id: multiline
            placeholderText: "Initial text\n...\n...\n"
            Layout.alignment: Qt.AlignLeft
            Layout.fillWidth: true
            Layout.fillHeight: true
            Layout.margins: 5
            background: Rectangle {
               implicitWidth: 200
               implicitHeight: 100
               border.color: multiline.focus ? "#21be2b" : "lightgray"
               color: multiline.focus ? "lightgray" : "transparent"
            }
        }
    }
}

在 QML 中显示文本 QML 中的可视化元素

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