En esta página

Gestión de la entrada del usuario

Tipos de entradas de usuario admitidos

El Qt Quick módulo ofrece compatibilidad con los tipos más comunes de entradas del usuario, incluidos los eventos de ratón y táctiles, la introducción de texto y los eventos de pulsación de teclas. Otros módulos ofrecen compatibilidad con otros tipos de entradas del usuario.

Este artículo explica cómo gestionar la entrada básica del usuario. Para obtener información sobre la entrada audiovisual, consulta la Qt Multimedia documentación.

Eventos de ratón y táctiles

Los controladores de entrada permiten a las aplicaciones QML gestionar eventos de ratón y táctiles. Por ejemplo, se puede crear un botón añadiendo un ` TapHandler ` a una imagen (`Image`) o a un ` Rectangle ` que contenga un objeto ` Text ` en su interior. El ` TapHandler ` responde a toques o clics en cualquier tipo de dispositivo señalador.

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
        }
    }
}

Nota: Algunos tipos de elementos cuentan con su propio manejo de entradas integrado. Por ejemplo, « Flickable » responde al arrastre con el ratón, a los gestos táctiles y al desplazamiento con la rueda del ratón.

Eventos de teclado y botones

Las pulsaciones de botones y teclas, ya sean de los botones de un dispositivo, de un teclado numérico o de un teclado, pueden gestionarse mediante la propiedad adjunta ` Keys `. Esta propiedad adjunta está disponible en todos los tipos derivados de ` Item ` y funciona junto con la propiedad ` Item::focus ` para determinar qué tipo recibe el evento de tecla. Para una gestión sencilla de las teclas, puedes establecer el foco en `true` en un único ` Item ` y gestionar allí todas las pulsaciones de teclas.

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
    }
}

Para la introducción de texto, disponemos de varios tipos de QML entre los que elegir. TextInput proporciona un campo de texto editable de una sola línea sin estilo, mientras que TextField resulta más adecuado para los campos de formulario en las aplicaciones. TextEdit puede gestionar texto editable de varias líneas, pero TextArea es una mejor alternativa, ya que añade estilo.

El siguiente fragmento de código muestra cómo utilizar estos tipos en tu aplicación:

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"
            }
        }
    }
}

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