QJSEngine Class

Documentación de funciones miembro

QJSEngine::QJSEngine()

Construye un objeto QJSEngine.

globalObject() se inicializa para que tenga las propiedades descritas en ECMA-262, Sección 15.1.

[explicit] QJSEngine::QJSEngine(QObject *parent)

Construye un objeto QJSEngine con la dirección parent.

globalObject() se inicializa para que tenga las propiedades descritas en ECMA-262, Sección 15.1.

[override virtual noexcept] QJSEngine::~QJSEngine()

Destruye este QJSEngine.

La basura no se recoge 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, la atrapa y la devuelve como QJSValue. En caso contrario, devuelve undefined como QJSValue. Después de llamar a este método hasError() devuelve false.

Esta función fue introducida en Qt 6.1.

template <typename From, typename To> To QJSEngine::coerceValue(const From &from)

Devuelve el from dado convertido al tipo de plantilla To. La conversión se realiza en la semántica de JavaScript. Ésta difiere de la semántica de qvariant_cast. Hay una serie de conversiones implícitas entre tipos equivalentes de JavaScript que qvariant_cast no realiza por defecto. 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 que ya no son accesibles en el entorno del script.

Normalmente no es necesario llamar a esta función; el recolector de basura será invocado automáticamente cuando QJSEngine decida que es prudente hacerlo (es decir, cuando se haya creado un cierto número de objetos nuevos). Sin embargo, puede llamar a esta función para solicitar explícitamente que la recolección de basura se realice lo antes posible.

Véase también Recogida 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 línea base, y devuelve el resultado de la evaluación.

El código de script se evaluará en el contexto del objeto global.

La evaluación de program puede causar una exception en el motor; en este caso el valor de retorno será la excepción lanzada (típicamente un objeto Error; ver QJSValue::isError()).

lineNumber se utiliza para especificar un número de línea inicial para program; la información sobre el número de línea proporcionada por el motor en relación con esta evaluación se basará en este argumento. Por ejemplo, si program consiste en dos líneas de código, y la sentencia en la segunda línea causa una excepción de script, el número de línea de excepción sería lineNumber más uno. Si no se especifica un número de línea inicial, los números de línea se basarán en 1.

fileName se utiliza para la notificación de errores. Por ejemplo, en los objetos de error el nombre del archivo es accesible a través de la propiedad "fileName" si se proporciona con esta función.

exceptionStackTrace se utiliza para informar de si se ha lanzado una excepción no capturada. Si le pasas un puntero no nulo a QStringList, lo establecerá como una lista de "mensajes de pila" si el script lanzó una excepción no gestionada, o una lista vacía en caso contrario. Un mensaje stackframe tiene el formato nombre de función:número de línea:columna:nombre de archivo

Véase también QQmlExpression::evaluate.

template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)

Devuelve el value dado 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 sólo puede contener int, bool, double, QString, y los equivalentes de JavaScript null y undefined, el valor se coaccionará agresivamente si se solicita cualquier otro tipo.

Véase también toPrimitiveValue() y coerceValue().

template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)

Devuelve el value dado convertido al tipo de plantilla T.

Véase también toScriptValue() y coerceValue().

template <typename T> T QJSEngine::fromVariant(const QVariant &value)

Devuelve el value dado convertido al tipo de plantilla T. La conversión se realiza en la semántica de JavaScript. Ésta difiere de la semántica de qvariant_cast. Hay una serie de conversiones implícitas entre tipos equivalentes de JavaScript que qvariant_cast no realiza por defecto.

Véase 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 incorporados que forman parte de ECMA-262, como Math, Date y String. Además, puede establecer propiedades del Objeto Global para hacer que sus propias extensiones estén disponibles para todo el código de script. Las variables no locales en el código de script se crearán como propiedades del Objeto Global, así como las variables locales en el código global.

[since Qt 6.1] bool QJSEngine::hasError() const

Devuelve true si la última ejecución de JavaScript resultó en una excepción o si se llamó a throwError(). En caso contrario devuelve false. Tenga 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 de módulo que contiene todas las variables, constantes y funciones exportadas como propiedades.

Si es la primera vez que se importa el módulo en el motor, el archivo se carga desde la ubicación especificada en el sistema de archivos local o en el sistema de recursos 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 hasta que se destruye el motor.

La dirección fileName especificada se normalizará internamente mediante QFileInfo::canonicalFilePath(). Esto significa que múltiples importaciones del mismo archivo en disco usando diferentes rutas relativas cargarán el archivo sólo una vez.

Véase también registerModule().

void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

Instala JavaScript extensions para añadir funciones que no están disponibles en una implementación estándar de ECMAScript.

Las extensiones se instalan en el object dado, o en el Global Object si no se especifica ningún objeto.

Se pueden instalar varias extensiones a la vez mediante OR-ing los valores enum:

installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);

Véase también Extension.

bool QJSEngine::isInterrupted() const

Devuelve si la ejecución de JavaScript está actualmente interrumpida.

Véase también setInterrupted().

QJSValue QJSEngine::newArray(uint length = 0)

Crea un objeto JavaScript de la clase Array con la dirección length.

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 la estática QMetaObject asociada 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 dado. El metaObject debe sobrevivir al motor de script. Se recomienda utilizar este método sólo con metaobjetos estáticos.

Cuando se llama como constructor, se crea una nueva instancia de la clase. Sólo 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 dado object, utilizando JavaScriptOwnership.

Las señales y ranuras, propiedades e hijos de object están disponibles como propiedades del objeto creado QJSValue.

Si object es un puntero nulo, esta función devuelve un valor nulo.

Si se ha registrado un prototipo por defecto para la clase object(o su superclase, recursivamente), el prototipo del nuevo objeto script será 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 JavaScript wrapper (ya sea por código script o C++) resultará en un script exception.

Véase también QJSValue::toQObject().

[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)

Crea un objeto JavaScript de clase Symbol, con valor name.

El prototipo del objeto creado será el objeto Symbol prototype.

Esta función se introdujo en Qt 6.2.

Véase también newObject().

[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)

Devuelve la propiedad de object.

Véase también setObjectOwnership() y QJSEngine::ObjectOwnership.

bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)

Registra un QJSValue para servir como módulo. Después de llamar a esta función, todos los módulos que importen moduleName importarán el valor de value en lugar de cargar moduleName del sistema de ficheros.

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 en caso de éxito, false en caso contrario.

Véase también importModule().

void QJSEngine::setInterrupted(bool interrupted)

Interrumpe o reactiva la ejecución de JavaScript.

Si interrupted es true, cualquier JavaScript ejecutado por este motor aborta inmediatamente y devuelve un objeto de error hasta que esta función es llamada de nuevo con un valor de false para interrupted.

Esta función es segura para subprocesos. Puede llamarla desde un hilo 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 JavaScriptOwnership no es recolectado mientras tenga un padre, incluso si no hay referencias a él.

Véase también objectOwnership() y QJSEngine::ObjectOwnership.

[since Qt 5.12] void QJSEngine::throwError(const QString &message)

Lanza un error en tiempo de ejecución (excepción) con la dirección message.

Este método es el equivalente en C++ de una expresión throw() en JavaScript. Permite que el código C++ informe de errores en tiempo de ejecución a QJSEngine. Por lo tanto, sólo debe invocarse desde código C++ que haya sido invocado por una función JavaScript a través de QJSEngine.

Al volver de C++, el motor interrumpirá el flujo normal de ejecución y llamará al siguiente gestor 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 de la pila de llamadas de JavaScript; en concreto, tendrá las propiedades lineNumber, fileName y stack. Estas propiedades se describen en Script Exceptions.

En el siguiente ejemplo, un método C++ en FileAccess.cpp lanza un error en qmlFile.qml en la posición donde 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 arrojado 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 necesita un error de ejecución más específico para describir una excepción, puede utilizar la sobrecarga 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 un error en tiempo de ejecución preconstruido error (excepción). De esta forma puede utilizar newErrorObject() para crear el error y personalizarlo según sea necesario.

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())

Lanza un error en tiempo de ejecución (excepción) con los datos 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 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 QJSManagedValue con el value dado.

Véase también fromManagedValue() y coerceValue().

template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)

Crea un QJSPrimitiveValue con el tipo value.

Dado que QJSPrimitiveValue sólo puede contener int, bool, double, QString, y los equivalentes de JavaScript null y undefined, el valor se coaccionará agresivamente si se pasa cualquier otro tipo.

Véase también fromPrimitiveValue() y coerceValue().

template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)

Crea un QJSValue con el value dado.

Véase también fromScriptValue() y coerceValue().