En esta página

Expresiones de JavaScript en documentos QML

El entorno de JavaScript proporcionado por QML puede ejecutar construcciones válidas de JavaScript estándar, como operadores condicionales, matrices, asignación de variables y bucles. Además de las propiedades estándar de JavaScript, el objeto global de QML incluye una serie de métodos auxiliares que simplifican la creación de interfaces de usuario y la interacción con el entorno QML.

El entorno de JavaScript que ofrece QML es más estricto que el de un navegador web. Por ejemplo, en QML no se pueden añadir ni modificar miembros del objeto global de JavaScript. En JavaScript convencional, es posible hacerlo de forma accidental al utilizar una variable sin declararla. En QML, esto provocará una excepción, por lo que todas las variables locales deben declararse explícitamente. Consulte Restricciones del entorno de JavaScript para obtener una descripción completa de las restricciones aplicables al código JavaScript ejecutado desde QML.

Varias partes de los documentos QML pueden contener código JavaScript:

  1. El cuerpo de los enlaces de propiedades. Estas expresiones JavaScript describen las relaciones entre las propiedades de los objetos QML. Cuando cambian las dependencias de una propiedad, esta también se actualiza automáticamente, de acuerdo con la relación especificada.
  2. El cuerpo de los controladores de señales. Estas instrucciones de JavaScript se evalúan automáticamente cada vez que un objeto QML emite la señal asociada.
  3. La definición de métodos personalizados. Las funciones de JavaScript que se definen dentro del cuerpo de un objeto QML se convierten en métodos de dicho objeto.
  4. Archivos de recursos de JavaScript independientes (.js). Estos archivos son, en realidad, independientes de los documentos QML, pero pueden importarse a estos. Las funciones y variables definidas en los archivos importados pueden utilizarse en enlaces de propiedades, controladores de señales y métodos personalizados.

JavaScript en los enlaces de propiedades

En el siguiente ejemplo, la propiedad ` color ` de ` Rectangle ` depende de la propiedad ` pressed ` de ` TapHandler`. Esta relación se describe mediante una expresión condicional:

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"

    TapHandler {
        id: inputHandler
    }
}

De hecho, se puede utilizar cualquier expresión de JavaScript (por muy compleja que sea) en la definición de un enlace de propiedad, siempre que el resultado de la expresión sea un valor cuyo tipo se pueda asignar a la propiedad. Esto incluye los efectos secundarios. Sin embargo, se desaconseja el uso de enlaces complejos y efectos secundarios, ya que pueden reducir el rendimiento, la legibilidad y la facilidad de mantenimiento del código.

Hay dos formas de definir una vinculación de propiedad: la más habitual es la que se muestra en el ejemplo anterior, en la inicialización de una propiedad. La segunda forma (mucho menos habitual) consiste en asignar a la propiedad una función devuelta por la función ` Qt.binding()`, desde código JavaScript imperativo, tal y como se muestra a continuación:

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: "red"

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
    }
}

Consulta la documentación sobre enlaces de propiedades para obtener más información sobre cómo definirlos, y consulta la documentación sobre «Asignación de propiedades frente a enlace de propiedades» para conocer en qué se diferencian los enlaces de las asignaciones de valores.

JavaScript en los controladores de señales

Los tipos de objetos QML pueden emitir señales en respuesta a determinados eventos. Dichas señales pueden ser gestionadas por funciones de gestión de señales, que los clientes pueden definir para implementar una lógica de programa personalizada.

Supongamos que un botón representado por un tipo Rectangle tiene un « TapHandler » y una etiqueta «Text». El « TapHandler » emite su señal « tapped » cuando el usuario pulsa el botón. Los clientes pueden reaccionar a la señal en el controlador « onTapped » utilizando expresiones JavaScript. El motor QML ejecuta estas expresiones JavaScript definidas en el controlador según sea necesario. Normalmente, un controlador de señales se vincula a expresiones JavaScript para iniciar otros eventos o para asignar valores a propiedades.

import QtQuick 2.12

Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"

    TapHandler {
        id: inputHandler
        onTapped: {
            // arbitrary JavaScript expression
            console.log("Tapped!")
        }
    }

    Text {
        id: label
        anchors.centerIn: parent
        text: inputHandler.pressed ? "Pressed!" : "Press here!"
    }
}

Para obtener más detalles sobre las señales y los controladores de señales, consulta los siguientes temas:

JavaScript en funciones independientes

La lógica del programa también se puede definir en funciones de JavaScript. Estas funciones se pueden definir de forma inline en documentos QML (como métodos personalizados) o externamente en archivos JavaScript importados.

JavaScript en métodos personalizados

Los métodos personalizados se pueden definir en documentos QML y pueden invocarse desde controladores de señales, enlaces de propiedades o funciones de otros objetos QML. A menudo se hace referencia a estos métodos como funciones JavaScript en línea, ya que su implementación se incluye en la definición del tipo de objeto QML (documento QML), en lugar de en un archivo JavaScript externo.

A continuación se muestra un ejemplo de método personalizado en línea:

import QtQuick 2.12

Item {
    function fibonacci(n){
        var arr = [0, 1];
        for (var i = 2; i < n + 1; i++)
            arr.push(arr[i - 2] + arr[i -1]);

        return arr;
    }
    TapHandler {
        onTapped: console.log(fibonacci(10))
    }
}

La función fibonacci se ejecuta cada vez que el objeto ` TapHandler ` emite una señal ` tapped `.

Nota: Los métodos personalizados definidos de forma inline en un documento QML quedan expuestos a otros objetos y, por lo tanto, las funciones inline del objeto raíz de un componente QML pueden ser invocadas por entidades que llaman desde fuera del componente. Si no se desea que esto ocurra, el método puede añadirse a un objeto que no sea el raíz o, preferiblemente, escribirse en un archivo JavaScript externo.

Consulta la documentación sobre atributos de objetos QML para obtener más información sobre cómo definir métodos personalizados en QML utilizando JavaScript.

Funciones definidas en un archivo JavaScript

Es recomendable separar la lógica de programa no trivial en un archivo JavaScript independiente. Este archivo se puede importar a QML mediante una instrucción ` import `, al igual que los módulos QML.

Por ejemplo, el método ` fibonacci() ` del ejemplo anterior podría trasladarse a un archivo externo llamado ` fib.js` y accederse de la siguiente manera:

import QtQuick 2.12
import "fib.js" as MathFunctions

Item {
    TapHandler {
        onTapped: console.log(MathFunctions.fibonacci(10))
    }
}

Para obtener más información sobre cómo cargar archivos JavaScript externos en QML, consulta la sección sobre cómo importar recursos JavaScript en QML.

Conexión de señales a funciones de JavaScript

Los tipos de objetos QML que emiten señales también proporcionan controladores de señal predeterminados para sus señales, tal y como se describe en la sección anterior. Sin embargo, en ocasiones, un cliente desea activar una función definida en un objeto QML cuando otro objeto QML emite una señal. Estos casos se pueden gestionar mediante una conexión de señal.

Una señal emitida por un objeto QML puede conectarse a una función JavaScript llamando al método ` connect() ` de la señal y pasando la función JavaScript como argumento. Por ejemplo, el siguiente código conecta la señal ` tapped ` del objeto ` TapHandler` a la función ` jsFunction() ` definida en ` script.js`:

import QtQuick
import "script.js" as MyScript

Item {
    id: item
    width: 200; height: 200

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        inputHandler.tapped.connect(MyScript.jsFunction)
    }
}
// script.js

function jsFunction() {
    console.log("Called JavaScript function!")
}

La función « jsFunction() » se invoca cada vez que se emite la señal « tapped » de TapHandler.

Consulta «Conexión de señales a métodos y señales» para obtener más información.

JavaScript en el código de inicio de la aplicación

En ocasiones es necesario ejecutar código imperativo al iniciar la aplicación (o una instancia de componente). Aunque resulta tentador incluir simplemente el script de inicio como código global en un archivo de script externo, esto puede suponer graves limitaciones, ya que es posible que el entorno QML aún no se haya establecido por completo. Por ejemplo, es posible que algunos objetos aún no se hayan creado o que no se hayan establecido algunos enlaces de propiedades. Consulta «Restricciones del entorno de JavaScript» para conocer las limitaciones exactas del código de script global.

Un objeto QML emite la señal « Component.completed » cuando se completa su instanciación. El código JavaScript del controlador « Component.onCompleted » correspondiente se ejecuta una vez instanciado el objeto. Por lo tanto, el mejor lugar para escribir el código de inicio de la aplicación es en el controlador « Component.onCompleted » del objeto de nivel superior, ya que este objeto emite « Component.completed » cuando el entorno QML está completamente establecido.

Por ejemplo:

import QtQuick 2.0

Rectangle {
    function startupFunction() {
        // ... startup code
    }

    Component.onCompleted: startupFunction();
}

Cualquier objeto de un archivo QML —incluidos los objetos anidados y las instancias de componentes QML anidadas— puede utilizar esta propiedad asociada. Si hay más de un controlador de onCompleted() que ejecutar al inicio, se ejecutan secuencialmente en un orden indefinido.

Del mismo modo, cada Component emite una señal destruction() justo antes de ser destruido.

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