QJSEngine Class
La clase QJSEngine proporciona un entorno para evaluar código JavaScript. Más información...
| Encabezado: | #include <QJSEngine> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Heredado de: | QObject |
| Heredado por: |
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
| enum | Extension { TranslationExtension, ConsoleExtension, GarbageCollectionExtension, AllExtensions } |
| flags | Extensions |
| enum | ObjectOwnership { CppOwnership, JavaScriptOwnership } |
Propiedades
- uiLanguage : QString
Funciones públicas
| QJSEngine() | |
| QJSEngine(QObject *parent) | |
| virtual | ~QJSEngine() override |
(since Qt 6.1) QJSValue | catchError() |
| To | coerceValue(const From &from) |
| void | collectGarbage() |
| QJSValue | evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr) |
| T | fromManagedValue(const QJSManagedValue &value) |
| T | fromPrimitiveValue(const QJSPrimitiveValue &value) |
| T | fromScriptValue(const QJSValue &value) |
| T | fromVariant(const QVariant &value) |
| QJSValue | globalObject() const |
(since Qt 6.1) bool | hasError() const |
| QJSValue | importModule(const QString &fileName) |
| void | installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue()) |
| bool | isInterrupted() const |
| QJSValue | newArray(uint length = 0) |
| QJSValue | newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString()) |
| QJSValue | newObject() |
| QJSValue | newQMetaObject() |
| QJSValue | newQMetaObject(const QMetaObject *metaObject) |
| QJSValue | newQObject(QObject *object) |
(since 6.2) QJSValue | newSymbol(const QString &name) |
| bool | registerModule(const QString &moduleName, const QJSValue &value) |
| void | setInterrupted(bool interrupted) |
| void | setUiLanguage(const QString &language) |
(since Qt 5.12) void | throwError(const QString &message) |
(since 6.1) void | throwError(const QJSValue &error) |
(since Qt 5.12) void | throwError(QJSValue::ErrorType errorType, const QString &message = QString()) |
| QJSManagedValue | toManagedValue(const T &value) |
| QJSPrimitiveValue | toPrimitiveValue(const T &value) |
| QJSValue | toScriptValue(const T &value) |
| QString | uiLanguage() const |
Señales
| void | uiLanguageChanged() |
Miembros públicos estáticos
| QJSEngine::ObjectOwnership | objectOwnership(QObject *object) |
| void | setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership) |
No miembros relacionados
| QJSEngine * | qjsEngine(const QObject *object) |
Descripción detallada
Evaluación de guiones
Utiliza evaluate() para evaluar el código de un script.
evaluate() devuelve un objeto QJSValue que contiene el resultado de la evaluación. La clase QJSValue proporciona funciones para convertir el resultado a diversos tipos de C++ (por ejemplo, QJSValue::toString() y QJSValue::toNumber()).
El siguiente fragmento de código muestra cómo se puede definir una función de script y, a continuación, invocarla desde C++ utilizando QJSValue::call():
QJSValue fun = myEngine.evaluate("(function(a, b) { return a + b; })");
QJSValueList args;
args << 1 << 2;
QJSValue threeAgain = fun.call(args);Como se puede observar en los fragmentos anteriores, el script se proporciona al motor en forma de cadena. Una forma habitual de cargar scripts consiste en leer el contenido de un archivo y pasarlo a evaluate():
QString fileName = "helloworld.qs";
QFile scriptFile(fileName);
if (!scriptFile.open(QIODevice::ReadOnly))
// handle error
QTextStream stream(&scriptFile);
QString contents = stream.readAll();
scriptFile.close();
myEngine.evaluate(contents, fileName);Aquí pasamos el nombre del archivo como segundo argumento a evaluate(). Esto no afecta en modo alguno a la evaluación; el segundo argumento es una cadena de uso general que se almacena en el objeto Error con fines de depuración.
Para funcionalidades más complejas, es posible que desees encapsular tu código y tus datos en módulos. Un módulo es un archivo que contiene código de script, variables, etc., y utiliza sentencias «export» para describir su interfaz con respecto al resto de la aplicación. Con la ayuda de las sentencias «import», un módulo puede hacer referencia a la funcionalidad de otros módulos. Esto permite crear una aplicación basada en scripts a partir de bloques de construcción más pequeños y conectados entre sí de forma segura. Por el contrario, el enfoque de utilizar « evaluate()» conlleva el riesgo de que las variables o funciones internas de una llamada a « evaluate()» contaminen accidentalmente el objeto global y afecten a las evaluaciones posteriores.
El siguiente ejemplo muestra un módulo capaz de sumar números:
export function sum(left, right)
{
return left + right
}Este módulo se puede cargar con QJSEngine::import() si se guarda con el nombre math.mjs:
QJSvalue module = myEngine.importModule("./math.mjs");
QJSValue sumFunction = module.property("sum");
QJSValue result = sumFunction.call(args);Los módulos también pueden utilizar la funcionalidad de otros módulos mediante sentencias de importación:
import { sum } from "./math.mjs";
export function addTwice(left, right)
{
return sum(left, right) * 2;
}Los módulos no tienen por qué ser archivos. Pueden ser valores registrados mediante la función ` QJSEngine::registerModule()`:
import version from "version";
export function getVersion()
{
return version;
}QJSValue version(610);
myEngine.registerModule("version", version);
QJSValue module = myEngine.importModule("./myprint.mjs");
QJSValue getVersion = module.property("getVersion");
QJSValue result = getVersion.call();Se admiten exportaciones con nombre, pero, dado que se tratan como miembros de un objeto, la exportación por defecto debe ser un objeto ECMAScript. La mayoría de las funciones newXYZ de QJSValue devolverán un objeto.
QJSValue name("Qt6");
QJSValue obj = myEngine.newObject();
obj.setProperty("name", name);
myEngine.registerModule("info", obj);import { name } from "info";
export function getName()
{
return name;
}Configuración del motor
La función globalObject() devuelve el objeto global asociado al motor de scripts. Se puede acceder a las propiedades del objeto global desde cualquier código de script (es decir, son variables globales). Normalmente, antes de evaluar los scripts «de usuario», se suele configurar el motor de scripts añadiendo una o más propiedades al objeto global:
myEngine.globalObject().setProperty("myNumber", 123);
...
QJSValue myNumberPlusOne = myEngine.evaluate("myNumber + 1");Añadir propiedades personalizadas al entorno de scripts es una de las formas habituales de proporcionar una API de scripts específica para su aplicación. Normalmente, estas propiedades personalizadas son objetos creados por las funciones newQObject() o newObject().
Excepciones de script
evaluate() puede lanzar una excepción de script (por ejemplo, debido a un error de sintaxis). Si lo hace, evaluate() devuelve el valor que se ha lanzado (normalmente un objeto Error ). Utiliza QJSValue::isError() para comprobar si hay excepciones.
Para obtener información detallada sobre el error, utilice QJSValue::toString() para obtener un mensaje de error y QJSValue::property() para consultar las propiedades del objeto Error. Están disponibles las siguientes propiedades:
namemessagefileNamelineNumberstack
QJSValue result = myEngine.evaluate(...);
if (result.isError())
qDebug()
<< «Excepción no detectada en la línea»
<< result.property("lineNumber").toInt()
<< «:» << result.toString();Creación de un objeto de script
Utiliza newObject() para crear un objeto JavaScript; esto es el equivalente en C++ de la instrucción script new Object(). Puedes utilizar la funcionalidad específica de objetos en QJSValue para manipular el objeto script (p. ej., QJSValue::setProperty()). Del mismo modo, utiliza newArray() para crear un objeto de matriz de JavaScript.
Integración con QObject
Utilice newQObject() para envolver un puntero a QObject (o una subclase). newQObject() devuelve un objeto de script proxy; las propiedades, los hijos y las señales y ranuras de QObject están disponibles como propiedades del objeto proxy. No se necesita código de enlace, ya que se realiza de forma dinámica mediante el sistema de metobjetos de Qt.
QPushButton*button = new QPushButton;
QJSValue scriptButton = myEngine.newQObject(button);
myEngine.globalObject().setProperty("button", scriptButton);
myEngine.evaluate("button.checkable = true");
qDebug() << scriptButton.property("checkable").toBool();
scriptButton.property("show").call(); // llama al slot show()Utiliza newQMetaObject() para envolver un QMetaObject; esto te proporciona una «representación en script» de una clase basada en QObject. newQMetaObject() devuelve un objeto de script proxy; los valores de la enumeración de la clase están disponibles como propiedades del objeto proxy.
Los constructores expuestos al sistema de metaobjetos (mediante Q_INVOKABLE) pueden invocarse desde el script para crear una nueva instancia de QObject con JavaScriptOwnership. Por ejemplo, dada la siguiente definición de clase:
class MyObject : public QObject
{
Q_OBJECT
public:
Q_INVOKABLE MyObject() {}
};El ` staticMetaObject ` de la clase se puede exponer a JavaScript de la siguiente manera:
QJSValue jsMetaObject = engine.newQMetaObject(&MyObject::staticMetaObject);
engine.globalObject().setProperty("MyObject", jsMetaObject);A continuación, se pueden crear instancias de la clase en JavaScript:
engine.evaluate("var myObject = new MyObject()");Nota: Actualmente solo se admiten las clases que utilizan la macro « Q_OBJECT »; no es posible exponer la « staticMetaObject » de una clase « Q_GADGET » a JavaScript.
Propiedades dinámicas de QObject
No se admiten las propiedades dinámicas de ` QObject `. Por ejemplo, el siguiente código no funcionará:
QJSEngine engine;
QObject*myQObject = new QObject();
myQObject->setProperty("dynamicProperty", 3);
QJSValue myScriptQObject = engine.newQObject(myQObject);
engine.globalObject().setProperty("myObject", myScriptQObject);
qDebug() << engine.evaluate("myObject.dynamicProperty").toInt();Extensiones
QJSEngine proporciona una implementación compatible con ECMAScript. De forma predeterminada, no están disponibles utilidades habituales como el registro de eventos, pero se pueden instalar mediante la función installExtensions().
Véase también QJSValue, Cómo hacer que las aplicaciones sean programables y Lista de objetos y funciones de JavaScript.
Documentación sobre tipos de miembros
enum QJSEngine::Extension
flags QJSEngine::Extensions
Esta enumeración se utiliza para especificar las extensiones que se van a instalar mediante la función ` installExtensions()`.
| Constante | Valor | Descripción |
|---|---|---|
QJSEngine::TranslationExtension | 0x1 | Indica que deben instalarse las funciones de traducción (por ejemplo, `qsTr()`). Esto también instala la propiedad Qt. `uiLanguage `. |
QJSEngine::ConsoleExtension | 0x2 | Indica que deben instalarse las funciones de consola (console.log(), por ejemplo). |
QJSEngine::GarbageCollectionExtension | 0x4 | Indica que deben instalarse las funciones de recolección de basura (por ejemplo,gc()). |
QJSEngine::AllExtensions | 0xffffffff | Indica que deben instalarse todas las extensiones. |
Extensión de traducción
La relación entre las funciones de traducción de scripts y las funciones de traducción de C++ se describe en la siguiente tabla:
| Función de script | Función de C++ correspondiente |
|---|---|
| qsTr() | QObject::tr() |
| QT_TR_NOOP() | QT_TR_NOOP() |
| qsTranslate() | QCoreApplication::translate() |
| QT_TRANSLATE_NOOP() | QT_TRANSLATE_NOOP() |
| qsTrId() | qtTrId() |
| QT_TRID_NOOP() | QT_TRID_NOOP() |
Este indicador también añade una función « arg() » al prototipo de la cadena.
Para obtener más información, consulta la documentación sobre Internacionalización con Qt.
ConsoleExtension
El objeto «console» implementa un subconjunto de la API de Console, que proporciona funciones de registro habituales, como ` console.log()`.
La lista de funciones añadidas es la siguiente:
console.assert()console.debug()console.exception()console.info()console.log()(equivalente a `console.debug()`)console.error()console.time()console.timeEnd()console.trace()console.count()console.warn()print()(equivalente a `console.debug()`)
Para obtener más información, consulta la documentación de la API de Console.
GarbageCollectionExtension
La función gc() es equivalente a llamar a collectGarbage().
El tipo Extensions es un typedef para QFlags<Extension>. Almacena una combinación OR de valores de Extension.
enum QJSEngine::ObjectOwnership
La propiedad del objeto (ObjectOwnership) determina si el gestor de memoria de JavaScript destruye automáticamente el objeto de propiedad del objeto ( QObject ) cuando el motor recoge como basura el objeto de JavaScript correspondiente. Las dos opciones de propiedad son:
| Constante | Valor | Descripción |
|---|---|---|
QJSEngine::CppOwnership | 0 | El objeto es propiedad del código C++ y el gestor de memoria de JavaScript nunca lo eliminará. El método destroy() de JavaScript no se puede utilizar con estos objetos. Esta opción es similar a QScriptEngine::QtOwnership. |
QJSEngine::JavaScriptOwnership | 1 | El objeto es propiedad de JavaScript. Cuando el objeto se devuelve al gestor de memoria de JavaScript como valor de retorno de una llamada a un método, el gestor de memoria de JavaScript lo rastreará y lo eliminará si no quedan referencias de JavaScript al mismo y no tiene ningún QObject::parent(). Un objeto al que haga seguimiento un motor de JavaScript ( QJSEngine ) se eliminará durante el destructor de ese motor de JavaScript ( QJSEngine). Por lo tanto, las referencias de JavaScript entre objetos con JavaScriptOwnership procedentes de dos motores diferentes dejarán de ser válidas si uno de estos motores se elimina. Esta opción es similar a QScriptEngine::ScriptOwnership. |
Por lo general, una aplicación no necesita establecer explícitamente la propiedad de un objeto. El gestor de memoria de JavaScript utiliza una heurística para establecer la propiedad por defecto. Por defecto, un objeto creado por el gestor de memoria de JavaScript tiene JavaScriptOwnership. La excepción a esto son los objetos raíz creados al llamar a ` QQmlComponent::create()` o ` QQmlComponent::beginCreate()`, que tienen `CppOwnership` por defecto. Se considera que la propiedad de estos objetos de nivel raíz se ha transferido al llamante de C++.
Los objetos no creados por el gestor de memoria de JavaScript tienen CppOwnership por defecto. La excepción a esto son los objetos devueltos por llamadas a métodos de C++; su propiedad se establecerá en JavaScriptOwnership. Esto se aplica únicamente a las invocaciones explícitas de métodos o ranuras de Q_INVOKABLE, pero no a las invocaciones de getter de propiedades.
La llamada a ` setObjectOwnership()` anula la propiedad predeterminada.
Véase también «Propiedad de los datos».
Documentación de propiedades
uiLanguage : QString
Esta propiedad contiene el idioma que se utilizará para traducir las cadenas de la interfaz de usuario
Esta propiedad contiene el nombre del idioma que se utilizará para las traducciones de las cadenas de la interfaz de usuario. Se expone para lectura y escritura como « Qt.uiLanguage » cuando el « QJSEngine::TranslationExtension » está instalado en el motor. Siempre se expone en instancias de « QQmlEngine ».
Puede establecer el valor libremente y utilizarlo en los enlaces. Se recomienda configurarlo tras instalar los traductores en su aplicación. Por convención, una cadena vacía significa que no se pretende realizar ninguna traducción desde el idioma utilizado en el código fuente.
Funciones de acceso:
| QString | uiLanguage() const |
| void | setUiLanguage(const QString &language) |
Señal del notificador:
| void | uiLanguageChanged() |
Documentación de funciones de miembro
QJSEngine::QJSEngine()
Crea un objeto QJSEngine.
El método globalObject() se inicializa para que tenga las propiedades descritas en ECMA-262, sección 15.1.
[explicit] QJSEngine::QJSEngine(QObject *parent)
Crea un objeto QJSEngine con el parent especificado.
El objeto ` globalObject()` se inicializa para que tenga las propiedades descritas en la sección 15.1 de ECMA-262.
[override virtual noexcept] QJSEngine::~QJSEngine()
Destruye este QJSEngine.
No se recoge la basura del montón persistente de JS durante la destrucción de QJSEngine. Si necesitas liberar toda la memoria, llama a collectGarbage() manualmente justo antes de destruir QJSEngine.
[since Qt 6.1] QJSValue QJSEngine::catchError()
Si hay una excepción pendiente en ese momento, la captura y la devuelve como un objeto ` QJSValue`. En caso contrario, devuelve un valor indefinido como ` QJSValue`. Tras llamar a este método, ` hasError()` devuelve ` false`.
Esta función se introdujo en Qt 6.1.
template <typename From, typename To> To QJSEngine::coerceValue(const From &from)
Devuelve el objeto ` from ` proporcionado convertido al tipo de plantilla ` To`. La conversión se realiza según la semántica de JavaScript. Dicha semántica difiere de la de qvariant_cast. Existen varias conversiones implícitas entre tipos equivalentes en JavaScript que qvariant_cast no realiza de forma predeterminada. Este método es una generalización de todos los demás métodos de conversión de esta clase.
Véase también fromVariant(), qvariant_cast(), fromScriptValue() y toScriptValue().
void QJSEngine::collectGarbage()
Ejecuta el recolector de basura.
El recolector de basura intentará recuperar memoria localizando y eliminando los objetos a los que ya no se puede acceder en el entorno del script.
Normalmente no es necesario llamar a esta función; el recolector de basura se invocará automáticamente cuando el « QJSEngine » decida que es conveniente hacerlo (es decir, cuando se haya creado un determinado número de objetos nuevos). Sin embargo, puedes llamar a esta función para solicitar explícitamente que se realice la recolección de basura lo antes posible.
Véase también «Recolección de basura » y « gc()».
QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)
Evalúa ` program`, utilizando ` lineNumber ` como número de referencia, y devuelve el resultado de la evaluación.
El código del script se evaluará en el contexto del objeto global.
Nota: Si necesitas realizar la evaluación dentro de un contexto QML, utiliza QQmlExpression en su lugar.
La evaluación de ` program ` puede provocar una excepción ` exception ` en el motor; en este caso, el valor devuelto será la excepción lanzada (normalmente un objeto ` Error `; véase ` QJSValue::isError()`).
lineNumber Se utiliza para especificar un número de línea de inicio para « program »; la información sobre el número de línea que facilite el motor en relación con esta evaluación se basará en este argumento. Por ejemplo, si program consta de dos líneas de código y la instrucción de la segunda línea provoca una excepción de script, el número de línea de la excepción sería lineNumber más uno. Cuando no se especifica ningún número de línea inicial, los números de línea se contarán a partir de 1.
fileName Se utiliza para la notificación de errores. Por ejemplo, en los objetos de error se puede acceder al nombre del archivo a través de la propiedad «fileName» si se proporciona con esta función.
exceptionStackTrace Se utiliza para indicar si se ha lanzado una excepción no capturada. Si se le pasa un puntero no nulo a un objeto ` QStringList `, lo establecerá como una lista de «mensajes de marco de pila» si el script lanzó una excepción no controlada; en caso contrario, será una lista vacía. Un mensaje de marco de pila tiene el formato: nombre de la función:número de línea:columna:nombre de archivo
Nota: En algunos casos, por ejemplo, en el caso de las funciones nativas, el nombre de la función y el nombre del archivo pueden estar vacíos, y el número de línea y la columna pueden ser -1.
Nota: Si se ha lanzado una excepción y el valor de la excepción no es una instancia de Error (es decir, QJSValue::isError() devuelve false), se seguirá devolviendo el valor de la excepción. Utiliza exceptionStackTrace->isEmpty() para distinguir si el valor era un valor de retorno normal o excepcional.
Véase también QQmlExpression::evaluate.
template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)
Devuelve el objeto ` value ` proporcionado, convertido al tipo de plantilla ` T`.
Véase también toManagedValue() y coerceValue().
template <typename T> T QJSEngine::fromPrimitiveValue(const QJSPrimitiveValue &value)
Devuelve el ` value ` dado convertido al tipo de plantilla ` T`.
Dado que QJSPrimitiveValue solo puede contener int, bool, double, QString y los equivalentes de JavaScript null y undefined, el valor se convertirá de forma agresiva si se solicita cualquier otro tipo.
Véase también toPrimitiveValue() y coerceValue().
template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)
Devuelve el objeto ` value ` proporcionado, convertido al tipo de plantilla ` T`.
Véase también toScriptValue() y coerceValue().
template <typename T> T QJSEngine::fromVariant(const QVariant &value)
Devuelve el objeto ` value ` dado convertido al tipo de plantilla ` T`. La conversión se realiza según la semántica de JavaScript. Esta difiere de la semántica de qvariant_cast. Existen varias conversiones implícitas entre tipos equivalentes en JavaScript que qvariant_cast no realiza de forma predeterminada.
Véanse también coerceValue(), fromScriptValue() y qvariant_cast().
QJSValue QJSEngine::globalObject() const
Devuelve el objeto global de este motor.
Por defecto, el objeto global contiene los objetos integrados que forman parte de ECMA-262, como Math, Date y String. Además, puedes definir propiedades del objeto global para que tus propias extensiones estén disponibles para todo el código de script. Las variables no locales del código de script se crearán como propiedades del objeto global, al igual que las variables locales del código global.
[since Qt 6.1] bool QJSEngine::hasError() const
Devuelve ` true ` si la última ejecución de JavaScript provocó una excepción o si se llamó a ` throwError()`. En caso contrario, devuelve ` false`. Ten en cuenta que ` evaluate()` captura cualquier excepción lanzada en el código evaluado.
Esta función se introdujo en Qt 6.1.
QJSValue QJSEngine::importModule(const QString &fileName)
Importa el módulo ubicado en fileName y devuelve un objeto de espacio de nombres del módulo que contiene como propiedades todas las variables, constantes y funciones exportadas.
Si es la primera vez que se importa el módulo en el motor, el archivo se carga desde la ubicación especificada, ya sea en el sistema de archivos local o en el sistema de recursos de Qt, y se evalúa como un módulo ECMAScript. Se espera que el archivo esté codificado en texto UTF-8.
Las importaciones posteriores del mismo módulo devolverán la instancia importada anteriormente. Los módulos son singletons y permanecen activos hasta que se destruye el motor.
La ruta relativa especificada ( fileName ) se normalizará internamente mediante ` QFileInfo::canonicalFilePath()`. Esto significa que las importaciones múltiples del mismo archivo en disco utilizando diferentes rutas relativas cargarán el archivo solo una vez.
Nota: Si se lanza una excepción durante la carga del módulo, el valor de retorno será la excepción (normalmente un objeto ` Error `; véase ` QJSValue::isError()`).
Véase también registerModule().
void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())
Instala JavaScript extensions para añadir funcionalidades que no están disponibles en una implementación estándar de ECMAScript.
Las extensiones se instalan en el objeto ` object` indicado o, si no se especifica ningún objeto, en ` Global Object `.
Se pueden instalar varias extensiones a la vez utilizando la sintaxis « OR » con los valores de la enumeración:
Véase también Extension.
bool QJSEngine::isInterrupted() const
Devuelve si la ejecución de JavaScript está interrumpida en este momento.
Véase también setInterrupted().
QJSValue QJSEngine::newArray(uint length = 0)
Crea un objeto JavaScript de la clase Array con el length proporcionado.
Véase también newObject().
QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())
Crea un objeto JavaScript de la clase Error, con « message » como mensaje de error.
El prototipo del objeto creado será errorType.
Véase también ` newObject()`, ` throwError()` y ` QJSValue::isError()`.
QJSValue QJSEngine::newObject()
Crea un objeto JavaScript de la clase `Object`.
El prototipo del objeto creado será el objeto prototipo Object.
Véase también newArray() y QJSValue::setProperty().
template <typename T> QJSValue QJSEngine::newQMetaObject()
Crea un objeto JavaScript que envuelve el método estático ` QMetaObject ` asociado a la clase ` T`.
Véase también newQObject() y QObject Integration.
QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)
Crea un objeto JavaScript que envuelve el ` QMetaObject ` especificado. El ` metaObject ` debe permanecer activo más tiempo que el motor de scripts. Se recomienda utilizar este método únicamente con metaobjetos estáticos.
Cuando se invoca como constructor, se creará una nueva instancia de la clase. Solo los constructores expuestos por Q_INVOKABLE serán visibles desde el motor de scripts.
Véase también newQObject() y QObject Integration.
QJSValue QJSEngine::newQObject(QObject *object)
Crea un objeto JavaScript que envuelve el QObject object dado, utilizando JavaScriptOwnership.
Las señales y ranuras, así como las propiedades y los elementos secundarios de ` object ` están disponibles como propiedades del objeto ` QJSValue` creado.
Si ` object ` es un puntero nulo, esta función devuelve un valor nulo. Lo mismo ocurre si ` object ` ha sido programado para su eliminación o cuando su destructor ya se está ejecutando.
Si se ha registrado un prototipo por defecto para la clase de object(o su superclase, de forma recursiva), el prototipo del nuevo objeto de script se establecerá como ese prototipo por defecto.
Si el ` object ` dado se elimina fuera del control del motor, cualquier intento de acceder a los miembros del ` QObject` eliminado a través del objeto envoltorio de JavaScript (ya sea mediante código de script o C++) dará lugar a un ` script exception`.
Véase también ` QJSValue::toQObject()`.
[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)
Crea un objeto JavaScript de la clase Symbol, con el valor « name ».
El prototipo del objeto creado será el objeto prototipo de Symbol.
Esta función se introdujo en Qt 6.2.
Véase también newObject().
[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)
Devuelve el propietario de object.
Véase también setObjectOwnership() y QJSEngine::ObjectOwnership.
bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)
Registra un ` QJSValue ` para que actúe como módulo. Una vez llamada esta función, todos los módulos que importen ` moduleName ` importarán el valor de ` value ` en lugar de cargar ` moduleName ` desde el sistema de archivos.
Se puede registrar cualquier QJSValue válido, pero las exportaciones con nombre (es decir, import { name } from "info") se tratan como miembros de un objeto, por lo que la exportación por defecto debe crearse con uno de los métodos newXYZ de QJSEngine.
Dado que esto permite importar módulos que no existen en el sistema de archivos, las aplicaciones de scripting pueden utilizarlo para proporcionar módulos integrados, de forma similar a Node.js.
Devuelve ` true ` si se realiza correctamente; ` false ` en caso contrario.
Nota: El QJSValue value no se invoca ni se lee hasta que lo utiliza otro módulo. Esto significa que no hay código que evaluar, por lo que no se observarán errores hasta que otro módulo lance una excepción al intentar cargar este módulo.
Advertencia: Intentar acceder a una exportación con nombre desde un ` QJSValue ` que no sea un objeto provocará un ` exception`.
Advertencia: Cuando se registra un módulo, el motor evalúa y captura una instantánea de las propiedades de ` value ` para determinar qué se va a exportar. En el caso de un ` QObject` envuelto, esto significa que sus propiedades solo se leen una vez, y las modificaciones posteriores de dichas propiedades no se reflejarán al acceder a ellas desde JavaScript. Si tu ` QObject ` tiene propiedades cuyos valores cambian tras el registro del módulo, no registres el ` QObject ` directamente. En su lugar, envuélvelo dentro de otro objeto:
// C++ setup
QJSValue container = engine.newObject();
container.setProperty("instance", engine.newQObject(&myDynamicObject));
engine.registerModule("api.mjs", container);
// JavaScript usage
import {instance as Api} from "api.mjs"
// ...
console.log(Api.dynamicProperty)Véase también importModule().
void QJSEngine::setInterrupted(bool interrupted)
Interrumpe o reanuda la ejecución de JavaScript.
Si interrupted es true, cualquier código JavaScript ejecutado por este motor se interrumpe inmediatamente y devuelve un objeto de error hasta que se vuelva a llamar a esta función con un valor de false para interrupted.
Esta función es segura para subprocesos. Se puede llamar desde un subproceso diferente para interrumpir, por ejemplo, un bucle infinito en JavaScript.
Véase también ` isInterrupted()`.
[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)
Establece el ` ownership ` de ` object`.
Un objeto con la propiedad ` JavaScriptOwnership ` no es eliminado por el recolector de basura mientras siga teniendo un padre, aunque no haya referencias a él.
Véase también ` objectOwnership()` y ` QJSEngine::ObjectOwnership`.
[since Qt 5.12] void QJSEngine::throwError(const QString &message)
Genera un error en tiempo de ejecución (excepción) con el valor dado de ` message`.
Este método es el equivalente en C++ de una expresión ` throw() ` en JavaScript. Permite que el código C++ notifique errores de tiempo de ejecución a ` QJSEngine`. Por lo tanto, solo debe invocarse desde código C++ que haya sido invocado por una función de JavaScript mediante ` QJSEngine`.
Al regresar desde C++, el motor interrumpirá el flujo normal de ejecución y llamará al siguiente controlador de excepciones prerregistrado con un objeto de error que contiene el ` message` dado. El objeto de error apuntará a la ubicación del contexto más alto en la pila de llamadas de JavaScript; concretamente, tendrá las propiedades ` lineNumber`, ` fileName ` y ` stack`. Estas propiedades se describen en Script Exceptions.
En el siguiente ejemplo, un método de C++ en FileAccess.cpp lanza un error en qmlFile.qml en la posición en la que se llama a readFileAsText():
// qmlFile.qml
function someFunction() {
...
var text = FileAccess.readFileAsText("/path/to/file.txt");
}// FileAccess.cpp
// Assuming that FileAccess is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// readFileAsText()
QJSValue FileAccess::readFileAsText(const QString & filePath) {
QFile file(filePath);
if (!file.open(QIODevice::ReadOnly)) {
jsEngine->throwError(file.errorString());
return QString();
}
...
return content;
}También es posible capturar el error lanzado en JavaScript:
// qmlFile.qml
function someFunction() {
...
var text;
try {
text = FileAccess.readFileAsText("/path/to/file.txt");
} catch (error) {
console.warn("In " + error.fileName + ":" + "error.lineNumber" +
": " + error.message);
}
}Si necesitas un error en tiempo de ejecución más específico para describir una excepción, puedes utilizar la sobrecarga de throwError(QJSValue::ErrorType errorType, const QString &message).
Esta función se introdujo en Qt 5.12.
Véase también Script Exceptions.
[since 6.1] void QJSEngine::throwError(const QJSValue &error)
Lanza una excepción de tiempo de ejecución « error » (excepción) preconstruida. De este modo, puedes utilizar ` newErrorObject()` para crear el error y personalizarlo según sea necesario.
Esta función sobrescribe QJSEngine::throwError().
Esta función se introdujo en Qt 6.1.
Véase también Script Exceptions y newErrorObject().
[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())
Genera un error en tiempo de ejecución (excepción) con los valores indicados en ` errorType ` y ` message`.
// Assuming that DataEntry is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// setAge().
void DataEntry::setAge(int age) {
if (age < 0 || age > 200) {
jsEngine->throwError(QJSValue::RangeError,
"Age must be between 0 and 200");
}
...
}Esta función sobrescribe QJSEngine::throwError().
Esta función se introdujo en Qt 5.12.
Véase también Script Exceptions y newErrorObject().
template <typename T> QJSManagedValue QJSEngine::toManagedValue(const T &value)
Crea un objeto ` QJSManagedValue ` con el ` value` indicado.
Véase también fromManagedValue() y coerceValue().
template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)
Crea un ` QJSPrimitiveValue ` con el ` value` proporcionado.
Dado que QJSPrimitiveValue solo admite int, bool, double, QString y los equivalentes de JavaScript null y undefined, el valor se convertirá de forma agresiva si se pasa cualquier otro tipo.
Véase también fromPrimitiveValue() y coerceValue().
template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)
Crea un objeto ` QJSValue ` con el ` value` indicado.
Véase también fromScriptValue() y coerceValue().
Elementos no miembros relacionados
QJSEngine *qjsEngine(const QObject *object)
Devuelve el objeto ` QJSEngine ` asociado a ` object`, si existe.
Esta función resulta útil si has expuesto un ` QObject ` al entorno de JavaScript y, más adelante en tu programa, deseas volver a acceder a él. No es necesario que conserves el envoltorio que devolvió la función ` QJSEngine::newQObject()`.
© 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.