Entorno de ejecución de JavaScript
QML proporciona un entorno de ejecución de JavaScript adaptado a la creación de aplicaciones QML. Este entorno es diferente del que ofrecen los navegadores o de los entornos de JavaScript del lado del servidor, como Node.js. Por ejemplo, QML no proporciona un objeto ` window ` ni ` DOM API `, como suele ser habitual en un entorno de navegador.
Base común
Al igual que un navegador o un entorno de JavaScript del lado del servidor, el QML Runtime implementa el estándar de la especificación del lenguaje ECMAScript. Esto proporciona acceso a todos los tipos y funciones integrados definidos por el estándar, como Object, Array y Math. El QML Runtime implementa la 7.ª edición del estándar.
La fusión de valores nulos (??) (desde Qt 5.15) y el encadenamiento opcional (?.) (desde Qt 6.2) también están implementados en el QML Runtime.
Además, los separadores de literales numéricos (los guiones bajos en 1_000_000) son compatibles desde Qt 6.8.
Las funciones integradas estándar de ECMAScript no se documentan explícitamente en la documentación de QML. Para obtener más información sobre su uso, consulta la norma ECMA-262, 7.ª edición, o alguno de los numerosos sitios web de referencia y tutoriales de JavaScript, como la Referencia de JavaScript de W3Schools (sección «Referencia de objetos de JavaScript»). Muchos sitios se centran en el JavaScript del navegador, por lo que, en algunos casos, puede que tengas que consultar la especificación para determinar si una función u objeto concreto forma parte del ECMAScript estándar o es específico del entorno del navegador. En el caso del enlace de W3Schools mencionado anteriormente, la sección « JavaScript Objects Reference » (Objetos de JavaScript) abarca, en general, el estándar, mientras que las secciones « Browser Objects Reference » (Objetos de JavaScript del navegador) y « HTML DOM Objects Reference » (Objetos de JavaScript del navegador) son específicas del navegador (y, por lo tanto, no son aplicables a QML).
Anotaciones de tipo y aserciones
Las declaraciones de funciones en los documentos QML pueden, y deben, contener anotaciones de tipo. Las anotaciones de tipo se añaden a la declaración de los argumentos y a la propia función, para indicar 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 interpretar el código y a proporcionar mejores diagnósticos. Además, facilitan el uso de las funciones desde C++. Consulta Interacción con objetos QML desde C++ para obtener más información.
La excepción a esta regla son las funciones asignadas a controladores de señales: en ese caso, las anotaciones de tipo están prohibidas para evitar una posible discrepancia con los tipos de la señal. Esto no supone ningún problema para las herramientas, ya que la señal ya proporciona la información necesaria.
Nota: En QML, las enumeraciones no son tipos y, por lo tanto, no pueden utilizarse como anotaciones de tipo. En su lugar, debe utilizarse su tipo numérico subyacente, int o double.
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, la aserción de tipo devuelve el mismo objeto. De lo contrario, devuelve ` null`. En el siguiente fragmento de código, asercionamos que el objeto ` parent ` es un ` Rectangle ` antes de acceder a uno de sus miembros específicos.
El encadenamiento opcional (?.) evita que se lance una excepción si el objeto padre no es realmente un rectángulo. En ese caso, se elige «red» como parentColor.
Desde Qt 6.7, las anotaciones de tipo se aplican siempre al llamar a funciones. Los valores se convierten a los tipos requeridos según sea necesario. Anteriormente, el intérprete y el compilador JIT ignoraban las anotaciones de tipo, pero qmlcachegen y qmlsc las aplicaban al compilar a C++. Esto podía dar lugar a diferencias de comportamiento en algunos casos extremos. Para solicitar explícitamente el comportamiento anterior del intérprete y del JIT, puedes añadir lo siguiente a tu documento QML:
pragma FunctionSignatureBehavior: IgnoredObjeto global de QML
El entorno de JavaScript de QML implementa una serie de objetos y funciones del host, tal y como se detalla en la documentación de «Objetos globales de QML ».
Estos objetos y funciones del 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 se puede encontrar una relación de los objetos, funciones y propiedades de JavaScript compatibles con el motor de QML.
Ten 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 que tienen en cuenta la configuración regional a los prototipos de Date y Number.
Véase también:
- Number: el objeto JavaScript Number
- Date: el objeto Date de JavaScript
- XMLHttpRequest: el objeto JavaScript XMLHttpRequest
Además, QML también amplía el comportamiento de la función `instanceof` para permitir la comprobación de tipos con respecto a los tipos de QML. Esto significa que puedes utilizarla para verificar que una variable es efectivamente del tipo que esperas, por ejemplo:
var v = something();
if (!v instanceof Item) {
throw new TypeError("I need an Item type!");
}
...Restricciones del entorno de 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» sí puede modificar el objeto global, y dichas modificaciones serán visibles para el archivo «.qml» al importarlo.En QML, el objeto global es constante: las propiedades existentes no se pueden modificar ni eliminar, y no se pueden crear nuevas propiedades.
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 por parte de JavaScript supone una modificación implícita del objeto global, lo cual está prohibido en QML.
Suponiendo que la variable `
a` no existe en la cadena de ámbito, el siguiente código no es válido en QML:// Illegal modification of undeclared variable a = 1; for (var ii = 1; ii < 10; ++ii) a = a * ii; console.log("Result: " + a);Se puede modificar fácilmente para convertirlo en este código válido.
var a = 1; for (var ii = 1; ii < 10; ++ii) a = a * ii; console.log("Result: " + a);Cualquier intento de modificar el objeto global —ya sea de forma implícita o explícita— provocará una excepción. Si no se captura, se mostrará una advertencia que incluirá el nombre del archivo y el número de línea del código problemático.
- 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», este se ejecuta en un ámbito que contiene únicamente el propio archivo externo y el objeto global. Es decir, no tendrá acceso a los objetos y propiedades QML a los que normalmente tendría acceso.
Se permite el código global que solo acceda a 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 se debe a que el entorno QML aún no está completamente configurado. Para ejecutar código una vez finalizada la configuración del entorno, consulta la sección «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 al vincular propiedades desde JavaScript. En las expresiones de enlace de QML, los controladores de señales de QML y las funciones declaradas en QML, «this» hace referencia al objeto de ámbito. En todas las demás situaciones, el valor de «this» es indefinido en QML.Para hacer referencia a un objeto específico, utilice `
id`. Por ejemplo:
Véase también «Ámbito y resolución de nombres».
© 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.