En esta página

Sistema de eventos de señales y controladores

Los componentes de la aplicación y de la interfaz de usuario deben comunicarse entre sí. Por ejemplo, un botón debe saber que el usuario ha hecho clic en él. El botón puede cambiar de color para indicar su estado o ejecutar alguna lógica. Asimismo, la aplicación debe saber si el usuario está haciendo clic en el botón. Es posible que la aplicación tenga que transmitir este evento de clic a otras aplicaciones.

QML cuenta con un mecanismo de señales y controladores, en el que la señal es el evento y la respuesta a la señal se realiza a través de un controlador de señales. Cuando se emite una señal, se invoca el controlador de señales correspondiente. Al incluir lógica, como un script u otras operaciones, en el controlador, el componente puede responder al evento.

Recepción de señales con controladores de señales

Para recibir una notificación cuando se emite una señal concreta para un objeto determinado, la definición del objeto debe declarar un controlador de señales denominado on<Signal>, donde <Signal> es el nombre de la señal, con la primera letra en mayúscula. El controlador de señales debe contener el código JavaScript que se ejecutará cuando se invoque dicho controlador.

Por ejemplo, el tipo « Button » del módulo «Qt Quick Controls» tiene una señal « clicked », que se emite cada vez que se hace clic en el botón. En este caso, el controlador de señales para recibir esta señal debe ser « onClicked ». En el ejemplo siguiente, cada vez que se hace clic en el botón, se invoca el controlador « onClicked », que aplica un color aleatorio al elemento padre « Rectangle »:

import QtQuick
import QtQuick.Controls

Rectangle {
    id: rect
    width: 250; height: 250

    Button {
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
        onClicked: {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}

Nota: Aunque los controladores de señales se parecen un poco a las funciones de JavaScript, no debes llamarlos directamente. Si necesitas compartir código entre controladores de señales y otras funcionalidades, refactorízalo en una función independiente. De lo contrario, emite siempre la señal si quieres que se llame al controlador de señales. Puede haber varios controladores, en diferentes ámbitos, para una misma señal.

Manejadores de señales de cambio de propiedad

Se emite automáticamente una señal cuando cambia el valor de una propiedad QML. Este tipo de señal se denomina «señal de cambio de propiedad » y los controladores de estas señales se escriben con el formato on<Propiedad>Changed, donde <Propiedad> es el nombre de la propiedad, con la primera letra en mayúscula.

Por ejemplo, el tipo « MouseArea » tiene una propiedad « pressed ». Para recibir una notificación cada vez que cambie esta propiedad, escribe un controlador de señal denominado « onPressedChanged »:

import QtQuick

Rectangle {
    id: rect
    width: 100; height: 100

    TapHandler {
        onPressedChanged: console.log("taphandler pressed?", pressed)
    }
}

Aunque la documentación de TapHandler no menciona un controlador de señal llamado onPressedChanged, la señal se proporciona implícitamente por el mero hecho de que exista la propiedad pressed.

Parámetros de la señal

Las señales pueden tener parámetros. Para acceder a ellos, debes asignar una función al controlador. Se pueden utilizar tanto funciones flecha como funciones anónimas.

Para los siguientes ejemplos, consideremos un componente Status con una señal errorOccurred (consulta Añadir señales a tipos QML personalizados para obtener más información sobre cómo se pueden añadir señales a los componentes QML).

// Status.qml
import QtQuick

Item {
    id: myitem

    signal errorOccurred(message: string, line: int, column: int)
}
Status {
    onErrorOccurred: (mgs, line, col) => console.log(`${line}:${col}: ${msg}`)
}

Nota: No es necesario quelos nombres de los parámetros formales de la función coincidan con los de la señal.

Si no es necesario gestionar todos los parámetros, es posible omitir los que aparecen al final:

Status {
    onErrorOccurred: message => console.log(message)
}

No es posible omitir los parámetros iniciales que te interesan; sin embargo, puedes utilizar algún nombre de marcador de posición para indicar a los lectores que no son importantes:

Status {
    onErrorOccurred: (_, _, col) => console.log(`Error happened at column ${col}`)
}

Nota: En lugar de utilizar una función, es posible —aunque no recomendable— utilizar un bloque de código sin más. En ese caso, todos los parámetros de la señal se inyectan en el ámbito del bloque. Sin embargo, esto puede dificultar la lectura del código, ya que no queda claro de dónde proceden los parámetros, y ralentiza las búsquedas en el motor QML. La inyección de parámetros de esta forma está en desuso y provocará advertencias en tiempo de ejecución si el parámetro se utiliza realmente.

Uso del objeto especial «arguments»

En JavaScript se puede hacer referencia al objeto especial « arguments », que, cuando está disponible, permite acceder a los valores de los argumentos pasados a una función que no sea de flecha como un objeto de tipo matriz.

Suele estar disponible en el cuerpo de una función o en un bloque de código asignado a un controlador de señal.

Cuando se asigna un bloque de código o una función anónima al controlador de señales, el objeto especial arguments proporcionará los argumentos que fueron pasados por la señal.

Por ejemplo, las dos instrucciones siguientes mostrarán « [object Arguments] world undefined »:

import QtQml

QtObject {
    id: root

    signal hello(message: string)

    onHello: { console.log(arguments, arguments[0], arguments[1]) }

    Component.onCompleted: root.hello("world")
}
import QtQml

QtObject {
    id: root

    signal hello(message: string)

    onHello: function () { console.log(arguments, arguments[0], arguments[1]) }

    Component.onCompleted: root.hello("world")
}

El comportamiento será diferente cuando se asigne una función flecha al controlador de señales. En ese caso, seguirá siendo posible acceder al objeto especial « arguments », pero será un objeto similar a un array vacío.

Por ejemplo, el siguiente código mostrará [object Arguments] undefined undefined:

import QtQml

QtObject {
    id: root

    signal hello(message: string)

    onHello: () => { console.log(arguments, arguments[0], arguments[1]) }

    Component.onCompleted: root.hello("world")
}

La diferencia de comportamiento se debe a la forma en que el objeto especial ` arguments ` interactúa con las funciones flecha, pero es coherente con el comportamiento general de los enlaces.

Según la especificación, una función flecha no lleva su propio objeto especial ` arguments `. Dado que una función flecha sigue tomando prestado de su contexto envolvente, puede tomar prestado el objeto especial ` arguments ` si hay uno disponible.

Un enlace proporciona su propio ámbito al evaluarse. En concreto, la recuperación de la función flecha subyacente se lleva a cabo en el ámbito proporcionado por la evaluación del enlace.

En el ámbito de la vinculación no se proporciona ningún argumento, por lo que habrá un objeto especial « arguments » vacío disponible que la función flecha tomará prestado al recuperarlo.

Dado que una función que no es de flecha sí proporciona el objeto especial ` arguments ` en su propio ámbito, puede hacer referencia a los argumentos que se proporcionaron a la propia función subyacente, que son los argumentos reenviados por la señal.

En general, se debe evitar el uso del objeto especial ` arguments ` y optar por el uso de parámetros con nombre, que son más explícitos y funcionan de manera coherente, independientemente de si se utiliza una función flecha o una función no flecha.

Uso del tipo «Connections»

En algunos casos, puede resultar conveniente acceder a una señal desde fuera del objeto que la emite. Para ello, el módulo QtQuick proporciona el tipo Connections, que permite conectarse a señales de objetos arbitrarios. Un objeto Connections puede recibir cualquier señal de su target especificado.

Por ejemplo, el controlador onClicked del ejemplo anterior podría haber sido recibido por el Rectangle raíz, colocando el controlador onClicked en un objeto Connections que tuviera su target establecido en el button:

import QtQuick
import QtQuick.Controls

Rectangle {
    id: rect
    width: 250; height: 250

    Button {
        id: button
        anchors.bottom: parent.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Change color!"
    }

    Connections {
        target: button
        function onClicked() {
            rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1);
        }
    }
}

Manejadores de señales adjuntos

Un manejador de señales adjunto recibe una señal de un tipo de adjunción, en lugar de del objeto en el que se declara el manejador.

Por ejemplo, Component.onCompleted es un controlador de señales adjunto. Se utiliza a menudo para ejecutar código JavaScript cuando finaliza su proceso de creación. A continuación se muestra un ejemplo:

import QtQuick

Rectangle {
    width: 200; height: 200
    color: Qt.rgba(Qt.random(), Qt.random(), Qt.random(), 1)

    Component.onCompleted: {
        console.log("The rectangle's color is", color)
    }
}

El controlador onCompleted no responde a una señal completed del tipo Rectangle. En su lugar, el motor QML ha asociado automáticamente un objeto del tipo de asociación Component, con una señal completed, al objeto Rectangle. El motor emite esta señal cuando se crea el objeto Rectangle, lo que activa el controlador de señales Component.onCompleted.

Los controladores de señales adjuntos permiten que los objetos reciban notificaciones de señales concretas que son relevantes para cada objeto individual. Si no existiera un controlador de señales adjunto Component.onCompleted, por ejemplo, un objeto no podría recibir esta notificación sin registrarse para recibir alguna señal especial procedente de algún objeto específico. El mecanismo de controladores de señales adjuntos permite a los objetos recibir señales concretas sin necesidad de código adicional.

Consulta «Propiedades asociadas y gestores de señales asociados » para obtener más información sobre los gestores de señales asociados.

Añadir señales a tipos QML personalizados

Las señales se pueden añadir a tipos QML personalizados mediante la palabra clave « signal ».

La sintaxis recomendada para definir una nueva señal es:

signal <name>[([<parameter name> : <type>[, ...]])]

También existe una sintaxis antigua en la que el tipo aparece antes del nombre:

signal <name>[([<type> <parameter name>[, ...]])]

Deberías utilizar la nueva sintaxis.

Una señal se emite invocándola como un método.

Por ejemplo, el código siguiente está definido en un archivo llamado SquareButton.qml. El objeto raíz Rectangle tiene una señal activated, que se emite cada vez que el objeto secundario TapHandler se tapped. En este ejemplo concreto, la señal «activated» se emite con las coordenadas x e y del clic del ratón:

// SquareButton.qml
import QtQuick

Rectangle {
    id: root

    signal activated(xPosition: real, yPosition: real)
    property point mouseXY
    property int side: 100
    width: side; height: side

    TapHandler {
        id: handler
        onTapped: root.activated(root.mouseXY.x, root.mouseXY.y)
        onPressedChanged: root.mouseXY = handler.point.position
    }
}

Ahora, cualquier objeto de la clase SquareButton puede conectarse a la señal activated mediante un controlador de señal onActivated:

// myapplication.qml
SquareButton {
    onActivated: (xPosition, yPosition) => console.log(`Activated at {xPosition}, ${yPosition}`)
}

Consulta «Atributos de señales » para obtener más detalles sobre cómo escribir señales para tipos QML personalizados.

Conexión de señales a métodos y señales

Los objetos de señal disponen de un método « connect() » para conectar una señal, ya sea a un método o a otra señal. Cuando una señal se conecta a un método, este se invoca automáticamente cada vez que se emite la señal. Este mecanismo permite que una señal sea recibida por un método en lugar de por un controlador de señales.

A continuación, la señal « messageReceived » se conecta a tres métodos mediante el método « connect() »:

import QtQuick

Rectangle {
    id: relay

    signal messageReceived(person: string, notice: string)

    Component.onCompleted: {
        relay.messageReceived.connect(sendToPost)
        relay.messageReceived.connect(sendToTelegraph)
        relay.messageReceived.connect(sendToEmail)
        relay.messageReceived("Tom", "Happy Birthday")
    }

    function sendToPost(person: string, notice: string) {
        console.log(`Sending to post: ${person}, ${notice}`)
    }
    function sendToTelegraph(person: string, notice: string) {
        console.log(`Sending to telegraph: ${person}, ${notice}`)
    }
    function sendToEmail(person: string, notice: string) {
        console.log(`Sending to email: ${person}, ${notice}`)
    }
}

En muchos casos basta con recibir señales a través de controladores de señales en lugar de utilizar la función `connect()`. Sin embargo, el uso del método ` connect ` permite que una señal sea recibida por varios métodos, tal y como se ha mostrado anteriormente, lo cual no sería posible con los controladores de señales, ya que estos deben tener nombres únicos. Además, el método ` connect ` resulta útil a la hora de conectar señales a objetos creados dinámicamente.

Existe un método disconnect() correspondiente para eliminar las señales conectadas:

Rectangle {
    id: relay
    //...

    function removeTelegraphSignal() {
        relay.messageReceived.disconnect(sendToTelegraph)
    }
}

Conexión de señal a señal

Al conectar señales entre sí, el método « connect() » permite formar diferentes cadenas de señales.

import QtQuick

Rectangle {
    id: forwarder
    width: 100; height: 100

    signal send()
    onSend: console.log("Send clicked")

    TapHandler {
        id: mousearea
        anchors.fill: parent
        onTapped: console.log("Mouse clicked")
    }

    Component.onCompleted: {
        mousearea.tapped.connect(send)
    }
}

Cada vez que se emita la señal « tapped » del « TapHandler », la señal « send » se emitirá automáticamente también.

output:
    MouseArea clicked
    Send clicked

Nota: Las conexiones con los objetos de función permanecerán activas mientras el remitente de la señal esté activo. Este comportamiento es análogo al de la versión de tres argumentos de ` QObject::connect()` en C++.

Window {
    visible: true
    width: 400
    height: 400

    Item {
        id: item
        property color globalColor: "red"

        Button {
            text: "Change global color"
            onPressed: {
                item.globalColor = item.globalColor === Qt.color("red") ? "green" : "red"
            }
        }

        Button {
            x: 150
            text: "Clear rectangles"
            onPressed: repeater.model = 0
        }

        Repeater {
            id: repeater
            model: 5
            Rectangle {
                id: rect
                color: "red"
                width: 50
                height: 50
                x: (width + 2) * index + 2
                y: 100
                Component.onCompleted: {
                    if (index % 2 === 0) {
                        item.globalColorChanged.connect(() => {
                            color = item.globalColor
                        })
                    }
                }
            }
        }
    }
}

En el ejemplo artificial anterior, el objetivo es invertir el color de cada rectángulo par para que siga un color global. Para lograrlo, por cada rectángulo par se establece una conexión entre la señal globalColorChanged y una función que establece el color del rectángulo. Esto funciona según lo esperado mientras los rectángulos están activos. Sin embargo, una vez pulsado el botón «Borrar», los rectángulos desaparecen, pero la función que gestiona la señal sigue llamándose cada vez que se emite la señal. Esto se puede observar en los mensajes de error generados por la función al intentar ejecutarse en segundo plano al cambiar el color global.

En la configuración actual, las conexiones solo se romperían una vez que se destruyera el elemento que contiene `globalColor`. Para evitar que las conexiones permanezcan activas, se pueden desconectar explícitamente cuando se destruyan los rectángulos.

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