Definición de recursos JavaScript en QML

La lógica del programa de una aplicación QML puede definirse en JavaScript. El código JavaScript puede definirse en línea en documentos QML o separarse en archivos JavaScript (conocidos como JavaScript Resources en QML).

QML admite dos tipos diferentes de recursos JavaScript: archivos de implementación de código subyacente y archivos compartidos (biblioteca). Ambos tipos de recursos JavaScript pueden ser importados por otros recursos JavaScript o incluidos en módulos QML.

Recurso de implementación de código oculto

La mayoría de los archivos JavaScript importados en un documento QML son implementaciones con estado para el documento QML que los importa. En estos casos, cada instancia del tipo de objeto QML definido en el documento requiere una copia independiente de los objetos JavaScript y del estado para comportarse correctamente.

El comportamiento predeterminado al importar archivos JavaScript es proporcionar una copia única y aislada para cada instancia de componente QML. Si ese archivo JavaScript no importa ningún recurso o módulo con una declaración .import, su código se ejecutará en el mismo ámbito que la instancia del componente QML y, en consecuencia, podrá acceder a los objetos y propiedades declarados en ese componente QML y manipularlos. En caso contrario, tendrá su propio ámbito exclusivo, y los objetos y propiedades del componente QML deberán pasarse a las funciones del archivo JavaScript como parámetros si son necesarios.

A continuación se muestra un ejemplo de recurso de implementación de code-behind:

// MyButton.qml
import QtQuick 2.0
import "my_button_impl.js" as Logic // A new instance of this JavaScript resource
                                    // is loaded for each instance of Button.qml.

Rectangle {
    id: rect
    width: 200
    height: 100
    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
        onClicked: Logic.onClicked(rect)
    }
}

// my_button_impl.js
var clickCount = 0;   // this state is separate for each instance of MyButton
function onClicked(button) {
    clickCount += 1;
    if ((clickCount % 5) == 0) {
        button.color = Qt.rgba(1,0,0,1);
    } else {
        button.color = Qt.rgba(0,1,0,1);
    }
}

En general, la lógica simple debe definirse en línea en el archivo QML, pero la lógica más compleja debe separarse en recursos de implementación de código oculto para facilitar el mantenimiento y la lectura.

Recursos JavaScript compartidos (bibliotecas)

Por defecto, los archivos JavaScript importados desde QML comparten su contexto con el componente QML. Esto significa que los archivos JavaScript tienen acceso a los mismos objetos QML y pueden modificarlos. En consecuencia, cada importación debe tener una copia única de estos archivos.

Enla sección anterior se tratan las importaciones con estado de archivos JavaScript. Sin embargo, algunos archivos JavaScript no tienen estado y actúan más como bibliotecas reutilizables, en el sentido de que proporcionan un conjunto de funciones de ayuda que no requieren nada del lugar desde el que se importaron. Puede ahorrar una cantidad significativa de memoria y acelerar la instanciación de componentes QML si marca dichas bibliotecas con un pragma especial, como se muestra en el siguiente ejemplo.

// factorial.js
.pragma library

var factorialCount = 0;

function factorial(a) {
    a = parseInt(a);

    // factorial recursion
    if (a > 0)
        return a * factorial(a - 1);

    // shared state
    factorialCount += 1;

    // recursion base-case.
    return 1;
}

function factorialCallCount() {
    return factorialCount;
}

La declaración de pragma debe aparecer antes de cualquier código JavaScript, excluidos los comentarios.

Tenga en cuenta que varios documentos QML pueden importar "factorial.js" y llamar a las funciones factorial y factorialCallCount que proporciona. El estado de la importación JavaScript se comparte entre los documentos QML que la importan y, por lo tanto, el valor de retorno de la función factorialCallCount puede ser distinto de cero cuando se llama dentro de un documento QML que nunca llama a la función factorial.

Por ejemplo:

// Calculator.qml
import QtQuick 2.0
import "factorial.js" as FactorialCalculator // This JavaScript resource is only
                                             // ever loaded once by the engine,
                                             // even if multiple instances of
                                             // Calculator.qml are created.

Text {
    width: 500
    height: 100
    property int input: 17
    text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
}

Al ser compartidos, los archivos de biblioteca .pragma no pueden acceder directamente a objetos de instancia o propiedades de componentes QML, aunque sí pueden pasarse valores QML como parámetros de función.