Foco del teclado en Qt Quick
Cuando se pulsa o se suelta una tecla, se genera un evento de teclado que se envía al elemento Qt Quick Item que tiene el foco. Para facilitar la creación de componentes reutilizables y abordar algunos de los casos propios de las interfaces de usuario fluidas, los elementos Qt Quick añaden una extensión basada en el ámbito al modelo tradicional de foco de teclado de Qt.
Descripción general del manejo de teclas
Cuando el usuario pulsa o suelta una tecla, ocurre lo siguiente:
- Qt recibe la acción de la tecla y genera un evento de tecla.
- Si un « QQuickWindow » es el « focus window » de la aplicación, el evento de tecla se le envía a él.
- La escena envía el evento de tecla al « Item » con el foco activo. Si ningún elemento tiene el foco activo, el evento de tecla se ignora.
- Si el « QQuickItem » con el foco activo acepta el evento de tecla, la propagación se detiene. De lo contrario, el evento se envía al elemento padre del «Item» hasta que se acepte el evento o se alcance el elemento raíz.
Si el tipo «
Rectangle» del siguiente ejemplo tiene el foco activo y se pulsa la tecla «A», el evento no se propagará más allá. Al pulsar la tecla «B», el evento se propagará hasta el elemento raíz y, por lo tanto, se ignorará.Rectangle { width: 100; height: 100 focus: true Keys.onPressed: (event)=> { if (event.key == Qt.Key_A) { console.log('Key A was pressed'); event.accepted = true; } } } - Si se alcanza el Item raíz, el evento de tecla es ignored y continúa el manejo habitual de teclas de Qt.
Véanse también « Keys attached property » y « KeyNavigation attached property ».
Consulta del elemento con foco activo
Se puede consultar si un Item tiene el foco activo a través de la propiedad Item::activeFocus. Por ejemplo, aquí tenemos un tipo Text cuyo texto varía en función de si tiene o no el foco activo.
Text {
text: activeFocus ? "I have active focus!" : "I do not have active focus"
}Obtención del foco y ámbitos de foco
Un elemento « Item » solicita el foco estableciendo la propiedad « focus » en « true ».
En casos muy sencillos, a veces basta con establecer la propiedad ` focus `. Si ejecutamos el siguiente ejemplo con la herramienta `qml`, vemos que el tipo ` keyHandler ` tiene el foco activo y que al pulsar las teclas ` A`, ` B` o ` C ` el texto se modifica adecuadamente.
Rectangle {
color: "lightsteelblue"; width: 240; height: 25
Text { id: myText }
Item {
id: keyHandler
focus: true
Keys.onPressed: (event)=> {
if (event.key == Qt.Key_A)
myText.text = 'Key A was pressed'
else if (event.key == Qt.Key_B)
myText.text = 'Key B was pressed'
else if (event.key == Qt.Key_C)
myText.text = 'Key C was pressed'
}
}
}
Sin embargo, si el ejemplo anterior se utilizara como componente reutilizable o importado, este uso sencillo de la propiedad focus ya no sería suficiente.
Para demostrarlo, creamos dos instancias de nuestro componente definido anteriormente y establecemos que la primera tenga el foco. La intención es que, al pulsar las teclas A, B o C, el primero de los dos componentes reciba el evento y responda en consecuencia.
El código que importa y crea dos instancias de MyWidget:
//Window code that imports MyWidget
Rectangle {
id: window
color: "white"; width: 240; height: 150
Column {
anchors.centerIn: parent; spacing: 15
MyWidget {
focus: true //set this MyWidget to receive the focus
color: "lightblue"
}
MyWidget {
color: "palegreen"
}
}
}El código de MyWidget:
Rectangle {
id: widget
color: "lightsteelblue"; width: 175; height: 25; radius: 10; antialiasing: true
Text { id: label; anchors.centerIn: parent}
focus: true
Keys.onPressed: (event)=> {
if (event.key == Qt.Key_A)
label.text = 'Key A was pressed'
else if (event.key == Qt.Key_B)
label.text = 'Key B was pressed'
else if (event.key == Qt.Key_C)
label.text = 'Key C was pressed'
}
}Queremos que el primer objeto MyWidget tenga el foco, por lo que establecemos su propiedad focus en true. Sin embargo, al ejecutar el código, puede ocurrir que el segundo widget reciba el foco.

Al examinar tanto el código de MyWidget como el de window, el problema resulta evidente: hay tres tipos que establecen la propiedad focus en true. Los dos MyWidgetestablecen focus en true y el componente window también establece el foco. En última instancia, solo un tipo puede tener el foco del teclado, y el sistema tiene que decidir qué tipo recibe el foco. Dado que QML no garantiza qué elemento tendrá sus propiedades inicializadas primero, podría darse el caso de que el último MyWidget obtuviera el foco inicial.
Este problema se debe a la visibilidad. Al componente MyWidget le gustaría tener el foco, pero no puede controlarlo cuando se importa o se reutiliza. Del mismo modo, el componente window no tiene la capacidad de saber si sus componentes importados están solicitando el foco.
Para resolver este problema, QML introduce un concepto conocido como «ámbito de foco». Para los usuarios habituales de Qt, un ámbito de foco es como un proxy de foco automático. Un ámbito de foco se crea declarando el tipo FocusScope.
En el siguiente ejemplo, se añade un tipo ` FocusScope ` al componente y se muestra el resultado visual.
FocusScope {
//FocusScope needs to bind to visual properties of the Rectangle
property alias color: rectangle.color
x: rectangle.x; y: rectangle.y
width: rectangle.width; height: rectangle.height
Rectangle {
id: rectangle
anchors.centerIn: parent
color: "lightsteelblue"; width: 175; height: 25; radius: 10; antialiasing: true
Text { id: label; anchors.centerIn: parent }
focus: true
Keys.onPressed: (event)=> {
if (event.key == Qt.Key_A)
label.text = 'Key A was pressed'
else if (event.key == Qt.Key_B)
label.text = 'Key B was pressed'
else if (event.key == Qt.Key_C)
label.text = 'Key C was pressed'
}
}
}
Conceptualmente, los ámbitos de foco son bastante sencillos.
- Dentro de cada «focus scope», un objeto puede tener la propiedad «
Item::focus» establecida en «true». Si más de un « Item » tiene establecida la propiedad «focus», el último tipo en establecer «focus» tendrá el foco y los demás quedarán desactivados, de forma similar a cuando no hay «focus scopes». - Cuando un ámbito de foco recibe el foco activo, el tipo contenido que tenga establecida la propiedad `
focus` (si lo hay) también obtiene el foco activo. Si este tipo es también un ` FocusScope`, el comportamiento de proxy continúa. Tanto el ámbito de foco como el elemento subenfocado tendrán establecida la propiedad `activeFocus`.
Ten en cuenta que, dado que el tipo « FocusScope » no es un tipo visual, las propiedades de sus elementos secundarios deben exponerse al elemento padre del « FocusScope ». Los tipos de diseño y posicionamiento utilizarán estas propiedades visuales y de estilo para crear el diseño. En nuestro ejemplo, el tipo « Column » no puede mostrar los dos widgets correctamente porque el « FocusScope » carece de propiedades visuales propias. El componente «MyWidget» se vincula directamente a las propiedades de « rectangle » para permitir que el tipo « Column » cree el diseño que contiene los elementos hijos de « FocusScope ».
Hasta ahora, en el ejemplo se ha seleccionado estáticamente el segundo componente. Ahora resulta muy sencillo ampliar este componente para que sea clicable e incorporarlo a la aplicación original. Seguimos estableciendo uno de los widgets como el que tiene el foco por defecto. Ahora, al hacer clic en cualquiera de los MyClickableWidget, este obtiene el foco y el otro widget lo pierde.
El código que importa y crea dos instancias de `MyClickableWidget`:
Rectangle {
id: window
color: "white"; width: 240; height: 150
Column {
anchors.centerIn: parent; spacing: 15
MyClickableWidget {
focus: true //set this MyWidget to receive the focus
color: "lightblue"
}
MyClickableWidget {
color: "palegreen"
}
}
}El código de «MyClickableWidget»:
FocusScope {
id: scope
//FocusScope needs to bind to visual properties of the children
property alias color: rectangle.color
x: rectangle.x; y: rectangle.y
width: rectangle.width; height: rectangle.height
Rectangle {
id: rectangle
anchors.centerIn: parent
color: "lightsteelblue"; width: 175; height: 25; radius: 10; antialiasing: true
Text { id: label; anchors.centerIn: parent }
focus: true
Keys.onPressed: (event)=> {
if (event.key == Qt.Key_A)
label.text = 'Key A was pressed'
else if (event.key == Qt.Key_B)
label.text = 'Key B was pressed'
else if (event.key == Qt.Key_C)
label.text = 'Key C was pressed'
}
}
MouseArea { anchors.fill: parent; onClicked: { scope.focus = true } }
}
Cuando un « Item » de QML cede explícitamente el foco (estableciendo su propiedad « focus » en « false » mientras tiene el foco activo), el sistema no selecciona automáticamente otro elemento para que reciba el foco. Es decir, es posible que no haya ningún foco activo en ese momento.
Consulta «Ejemplos deQt Quick: Interacción con el teclado» para ver una demostración de cómo mover el foco del teclado entre varias áreas utilizando tipos de « FocusScope ».
Usos avanzados de los ámbitos de foco
Los ámbitos de foco permiten dividir fácilmente la asignación del foco. Varios elementos de QML los utilizan con este fin.
ListView, por ejemplo, es en sí mismo un ámbito de foco. Por lo general, esto pasa desapercibido, ya que ` ListView ` no suele tener elementos hijos visuales añadidos manualmente. Al ser un ámbito de foco, ` ListView ` puede centrar el foco en el elemento actual de la lista sin preocuparse de cómo afectará eso al resto de la aplicación. Esto permite que el delegado del elemento actual reaccione a las pulsaciones de teclas.
Este ejemplo ficticio muestra cómo funciona. Al pulsar la tecla « Return » se mostrará el nombre del elemento actual de la lista.
Rectangle {
color: "lightsteelblue"; width: 100; height: 50
ListView {
anchors.fill: parent
focus: true
model: ListModel {
ListElement { name: "Bob" }
ListElement { name: "John" }
ListElement { name: "Michael" }
}
delegate: FocusScope {
width: childrenRect.width; height: childrenRect.height
x:childrenRect.x; y: childrenRect.y
TextInput {
focus: true
text: name
Keys.onReturnPressed: console.log(name)
}
}
}
}
Aunque el ejemplo es sencillo, hay mucho que ocurre entre bastidores. Cada vez que cambia el elemento actual, el ListView establece la propiedad Item::focus del delegado. Como el ListView es un ámbito de enfoque, esto no afecta al resto de la aplicación. Sin embargo, si el propio ListView tiene el enfoque activo, esto hace que el propio delegado reciba el enfoque activo. En este ejemplo, el tipo raíz del delegado también es un ámbito de foco, lo que a su vez otorga el foco activo al tipo TextInput que realmente se encarga de gestionar la tecla Return.
Todas las clases de vista de QML, como PathView y GridView, se comportan de manera similar para permitir la gestión de teclas en sus respectivos delegados.
© 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.