Importación de recursos JavaScript en QML

Los recursosJavaScript pueden ser importados por documentos QML y otros recursos JavaScript. Los recursos JavaScript pueden importarse mediante URL relativas o absolutas. En el caso de una URL relativa, la ubicación se resuelve en relación con la ubicación del documento QML o del recurso JavaScript que contiene la importación. Si no se puede acceder al archivo de script, se producirá un error. Si el JavaScript debe obtenerse de un recurso de red, el componente status se establece en "Loading" (Cargando) hasta que se haya descargado el script.

Los recursos JavaScript también pueden importar módulos QML y otros recursos JavaScript. La sintaxis de una sentencia import dentro de un recurso JavaScript difiere ligeramente de la de una sentencia import dentro de un documento QML, que se documenta detalladamente a continuación.

Importación de un recurso JavaScript desde un documento QML

Un documento QML puede importar un recurso JavaScript con la siguiente sintaxis:

import "ResourceURL" as Qualifier

Por ejemplo:

import "jsfile.js" as Logic

Los recursos JavaScript importados siempre se califican mediante la palabra clave "as". El calificador de los recursos JavaScript debe empezar por mayúscula y ser único, de modo que siempre exista una correspondencia uno a uno entre los calificadores y los archivos JavaScript. (Esto también significa que los calificadores no pueden tener el mismo nombre que los objetos JavaScript incorporados, como Date y Math).

Las funciones definidas en un archivo JavaScript importado están disponibles para los objetos definidos en el documento QML de importación, a través de la sintaxis "Qualifier.functionName(params)". Las funciones de los recursos de JavaScript pueden tomar parámetros cuyos tipos pueden ser cualquier tipo de valor o tipo de objeto de QML, así como tipos normales de JavaScript. Se aplicarán las reglas normales de conversión de tipos de datos a los parámetros y valores de retorno al llamar a dichas funciones desde QML.

Importaciones dentro de recursos JavaScript

En QtQuick 2.0, se ha añadido soporte para permitir que los recursos JavaScript importen otros recursos JavaScript y también espacios de nombres de tipos QML utilizando una variación de la sintaxis de importación QML estándar (en la que se aplican todas las normas y cualificaciones descritas anteriormente).

Debido a la capacidad de un recurso JavaScript para importar otro script o módulo QML de este modo en QtQuick 2.0, se definen algunas semánticas adicionales:

• un script con declaraciones de importación no heredará las importaciones del documento QML que lo importó (el acceso a Component.errorString fallará, por ejemplo)
• un script sin declaraciones de importación heredará las importaciones del documento QML que lo importó (acceder a Component.errorString tendrá éxito, por ejemplo)
• un script compartido (definido como biblioteca .pragma) no heredará las importaciones de los documentos QML aunque el script no importe otros scripts o módulos

La primera semántica es conceptualmente correcta, dado que un script concreto puede ser importado por cualquier número de archivos QML. La segunda semántica se mantiene a efectos de compatibilidad con versiones anteriores. La tercera semántica se mantiene sin cambios con respecto a la semántica actual para scripts compartidos, pero se aclara aquí con respecto al nuevo caso posible (en el que el script importa otros scripts o módulos).

Importación de un recurso JavaScript de otro recurso JavaScript

Un recurso JavaScript puede importar otro de la siguiente manera:

import * as MathFunctions from "factorial.mjs";

O bien:

.import "filename.js" as Qualifier

La primera es la sintaxis estándar de ECMAScript para importar módulos de ECMAScript, y sólo funciona desde dentro de los módulos de ECMAScript, como indica la extensión de archivo mjs. La segunda es una extensión de JavaScript proporcionada por el motor QML y funciona también con los no-módulos. Como extensión sustituida por el estándar ECMAScript, se desaconseja su uso.

Cuando se importa un archivo JavaScript de esta forma, se importa con un calificador. Las funciones de ese archivo son accesibles desde el script de importación a través del calificador (es decir, como Qualifier.functionName(params)).

A veces es deseable que las funciones estén disponibles en el contexto de importación sin necesidad de calificarlas. En este caso, los módulos ECMAScript y la sentencia JavaScript import deben utilizarse sin el calificador as.

Por ejemplo, el código QML de abajo a la izquierda llama a showCalculations() en script.mjs, que a su vez puede llamar a factorial() en factorial.mjs, ya que ha incluido factorial.mjs utilizando import.

import QtQuick
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}

// script.mjs
import { factorial } from "factorial.mjs"
export { factorial }

export function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}

// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}

La función Qt.include() incluye un archivo JavaScript de otro sin utilizar módulos ECMAScript y sin calificar la importación. Hace que todas las funciones y variables del otro archivo estén disponibles en el espacio de nombres del archivo actual, pero ignora todos los pragmas e importaciones definidos en ese archivo. Esto no es una buena idea, ya que una llamada a una función nunca debería modificar el contexto de quien la llama.

Qt.include() está obsoleto y debería evitarse. Será eliminado en una futura versión de Qt.

Importación de un módulo QML desde un recurso JavaScript

Un recurso JavaScript puede importar un módulo QML de la siguiente manera:

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

A continuación puede ver un ejemplo que también muestra cómo utilizar los tipos QML de un módulo importado en javascript:

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

En particular, esto puede ser útil para acceder a la funcionalidad proporcionada a través de un tipo singleton; consulte QML_SINGLETON para obtener más información.

Por defecto, tu recurso javascript puede acceder a todas las importaciones del componente que importa el recurso. No tiene acceso a las importaciones del componente si se declara como una biblioteca sin estado (mediante .pragma library) o contiene una declaración explícita .import.