Entorno de host JavaScript

QML proporciona un entorno de host JavaScript adaptado para escribir aplicaciones QML. Este entorno es diferente del entorno host proporcionado por un navegador o un entorno JavaScript del lado del servidor como Node.js. Por ejemplo, QML no proporciona un objeto window o DOM API como los que se suelen encontrar en un entorno de navegador.

Base común

Al igual que un navegador o un entorno JavaScript del lado del servidor, el tiempo de ejecución de QML implementa el estándar ECMAScript Language Specification. Esto proporciona acceso a todos los tipos y funciones incorporados definidos por el estándar, como Object, Array y Math. El QML Runtime implementa la 7ª edición del estándar.

Nullish Coalescing (??) (desde Qt 5.15) y Optional Chaining (?.) (desde Qt 6.2) también están implementados en el runtime QML.

Además, los separadores literales numéricos (los guiones bajos en 1_000_000) están soportados desde Qt 6.8.

Los complementos estándar de ECMAScript no están explícitamente documentados en la documentación de QML. Para obtener más información sobre su uso, consulte el estándar ECMA-262 7.ª edición o uno de los muchos sitios de referencia y tutoriales en línea sobre JavaScript, como W3Schools JavaScript Reference (sección JavaScript Objects Reference). Muchos sitios se centran en JavaScript en el navegador, por lo que en algunos casos puede ser necesario volver a comprobar la especificación para determinar si una determinada función u objeto forma parte de ECMAScript estándar o es específica del entorno del navegador. En el caso del enlace de W3Schools anterior, la sección JavaScript Objects Reference cubre generalmente el estándar, mientras que las secciones Browser Objects Reference y HTML DOM Objects Reference son específicas del navegador (y, por tanto, no aplicables a QML).

Anotaciones de tipo y aserciones

Las declaraciones de funciones en documentos QML pueden, y deben, contener anotaciones de tipo. Las anotaciones de tipo se añaden a la declaración de argumentos y a la propia función, para anotar el tipo de retorno. La siguiente función toma un parámetro int y otro string, y devuelve un QtObject:

function doThings(a: int, b: string) : QtObject { ... }

Las anotaciones de tipo ayudan a herramientas como Qt Creator y qmllint a dar sentido al código y proporcionar mejores diagnósticos. Además, facilitan el uso de funciones desde C++. Consulte Interacción con objetos QML desde C++ para obtener más información.

La excepción a esta regla son las funciones asignadas a manejadores de señales: En ellas, las anotaciones de tipo están prohibidas para evitar un posible desajuste con los tipos de la señal. Esto no causa problemas a las herramientas, ya que la señal ya proporciona la información necesaria.

Las aserciones de tipo (a veces denominadas as-casts) también pueden utilizarse para convertir un objeto a un tipo de objeto diferente. Si el objeto es realmente del tipo dado, entonces la aserción de tipo devuelve el mismo objeto. Si no, devuelve null. En el siguiente fragmento afirmamos que el objeto parent es un Rectangle antes de acceder a un miembro específico del mismo.

Item {
    property color parentColor: (parent as Rectangle)?.color || "red"
}

El encadenamiento opcional (?.) evita lanzar una excepción si el padre no es realmente un rectángulo. En ese caso "red" es elegido como parentColor.

Desde Qt 6.7 las anotaciones de tipo se aplican siempre al llamar a funciones. Los valores son coaccionados a los tipos requeridos según sea necesario. Anteriormente, las anotaciones de tipo eran ignoradas por el intérprete y el compilador JIT, pero aplicadas por qmlcachegen y qmlsc al compilar a C++. Esto podía dar lugar a diferencias de comportamiento en algunos casos. Para solicitar explícitamente el antiguo comportamiento del intérprete y del JIT, puede añadir lo siguiente a su documento QML:

pragma FunctionSignatureBehavior: Ignored

Objeto global QML

El entorno host JavaScript de QML implementa una serie de objetos y funciones host, como se detalla en la documentación Objeto global QML.

Estos objetos y funciones de host están siempre disponibles, independientemente de si se ha importado algún módulo.

Objetos y funciones de JavaScript

En la Lista de objetos y funciones de JavaScript encontrará una lista de los objetos, funciones y propiedades de JavaScript compatibles con el motor QML.

Tenga en cuenta que QML realiza las siguientes modificaciones en los objetos nativos:

• Se añade una función arg() al prototipo String.
• Se añaden funciones de conversión local a los prototipos Date y Number.

Véase también:

• Number - El objeto Number de JavaScript
• Date - El objeto Date de JavaScript
• XMLHttpRequest - Objeto JavaScript XMLHttpRequest

Además, QML también amplía el comportamiento de la función instanceof para permitir la comprobación de tipos respecto a los tipos QML. Esto significa que puede utilizarla para comprobar que una variable es realmente del tipo que espera, por ejemplo:

var v = something();
if (!v instanceof Item) {
    throw new TypeError("I need an Item type!");
}

...

Restricciones del entorno JavaScript

QML aplica las siguientes restricciones al código JavaScript:

• El código JavaScript escrito en un archivo .qml no puede modificar el objeto global. El código JavaScript de un archivo .js puede modificar el objeto global, y esas modificaciones serán visibles para el archivo .qml cuando se importe.

  En QML, el objeto global es constante: las propiedades existentes no se pueden modificar ni eliminar, y no se pueden crear propiedades nuevas.

  La mayoría de los programas de JavaScript no modifican intencionadamente el objeto global. Sin embargo, la creación automática de variables no declaradas en JavaScript es una modificación implícita del objeto global y está prohibida en QML.

  Suponiendo que la variable a no exista en la cadena de ámbito, el siguiente código es ilegal en QML:

  // Illegal modification of undeclared variable
  a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  Puede modificarse trivialmente a este código legal.

  var a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  Cualquier intento de modificar el objeto global - implícita o explícitamente - causará una excepción. Si no se detecta, se imprimirá una advertencia que incluirá el archivo y el número de línea del código infractor.

• El código global se ejecuta en un ámbito reducido.

  Durante el inicio, si un archivo QML incluye un archivo JavaScript externo con código "global", se ejecuta en un ámbito que sólo contiene el propio archivo externo y el objeto global. Es decir, no tendrá acceso a los objetos y propiedades QML que normalmente tendría.

  Se permite el código global que sólo accede a las variables locales del script. Este es un ejemplo de código global válido.

  var colors = [ "red", "blue", "green", "orange", "purple" ];

  El código global que acceda a objetos QML no se ejecutará correctamente.

  // Invalid global code - the "rootObject" variable is undefined
  var initialPosition = { rootObject.x, rootObject.y }

  Esta restricción existe porque el entorno QML aún no está completamente establecido. Para ejecutar código después de que se haya completado la configuración del entorno, consulte JavaScript en el código de inicio de la aplicación.

• El valor de this no está definido en QML en la mayoría de los contextos.

  La palabra clave this es compatible cuando se vinculan propiedades desde JavaScript. En las expresiones de enlace de QML, los controladores de señales de QML y las funciones declaradas de QML, this hace referencia al objeto scope. En todas las demás situaciones, el valor de this no está definido en QML.

  Para hacer referencia a un objeto específico, proporcione un id. Por ejemplo:

  Item {
      width: 200; height: 100
      function mouseAreaClicked(area) {
          console.log("Clicked in area at: " + area.x + ", " + area.y);
      }
      // This will pass area to the function
      MouseArea {
          id: area
          y: 50; height: 50; width: 200
          onClicked: mouseAreaClicked(area)
      }
  }