QJSEngine Class

成员函数文档

QJSEngine::QJSEngine()

创建一个 QJSEngine 对象。

globalObject() 的初始化使其具有ECMA-262 第 15.1 节中描述的属性。

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

根据给定的parent ，构建一个QJSEngine对象。

globalObject() 的初始化将使其具有ECMA-262 第 15.1 节中所述的属性。

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

销毁此QJSEngine 。

在QJSEngine 销毁过程中，持久化JS堆中的垃圾不会被回收。如果您需要释放所有内存，请在销毁QJSEngine 之前手动调用collectGarbage()。

[since Qt 6.1] QJSValue QJSEngine::catchError()

如果当前有未处理的异常，则捕获该异常并将其作为QJSValue 返回；否则，将返回未定义值QJSValue 。调用此方法后，hasError()将返回false 。

该函数在 Qt 6.1 中引入。

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

返回将给定的from 转换为模板类型To 后的结果。该转换遵循JavaScript语义。这些语义与qvariant_cast 的语义不同。在JavaScript等效类型之间存在许多隐式转换，而qvariant_cast 默认不会执行这些转换。此方法是本类中所有其他转换方法的泛化实现。

另请参阅 fromVariant()、qvariant_cast()、fromScriptValue() 以及toScriptValue()。

void QJSEngine::collectGarbage()

运行垃圾回收器。

垃圾回收器将通过定位并销毁脚本环境中已不可达的对象，从而尝试回收内存。

通常您无需调用此函数；当QJSEngine 判断有必要执行垃圾回收时（即创建了一定数量的新对象时），垃圾回收器会自动被调用。不过，您可以调用此函数，以显式要求尽快执行垃圾回收。

另请参阅 “垃圾回收”和gc()。

QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)

评估表达式 `program`，将 `lineNumber ` 作为基准数值，并返回评估结果。

脚本代码将在全局对象的上下文中进行求值。

program 的求值可能会在引擎中引发exception ；在这种情况下，返回值将是抛出的异常（通常是一个Error 对象；请参阅QJSValue::isError()）。

lineNumber 用于指定program 的起始行号；引擎报告的与该评估相关的行号信息将基于此参数。 例如，如果program 包含两行代码，且第二行语句引发了脚本异常，则异常行号为lineNumber 加1。若未指定起始行号，行号将从1开始计数。

fileName 用于错误报告。例如，在错误对象中，如果通过此函数提供了文件名，则可通过“fileName”属性访问该文件名。

exceptionStackTrace 用于报告是否抛出了未捕获的异常。若向QStringList 传递一个非空指针，当脚本抛出未处理的异常时，该指针将指向“堆栈帧消息”列表；否则，将指向空列表。堆栈帧消息的格式为：函数名:行号:列号:文件名

另请参阅 QQmlExpression::evaluate 。

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

返回将给定的value 转换为模板类型T 后的结果。

另请参阅 toManagedValue() 和coerceValue()。

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

返回将给定的value 转换为模板类型T 后的结果。

由于QJSPrimitiveValue 只能包含int、bool、double、QString 以及JavaScript中null 和undefined 的等效类型，因此若请求其他类型，系统将进行强制转换。

另请参阅 toPrimitiveValue() 和coerceValue()。

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

返回将给定的value 转换为模板类型T 后的结果。

另请参阅 toScriptValue() 和coerceValue()。

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

返回将给定的value 转换为模板类型T 的结果。该转换遵循 JavaScript 的语义。这些语义与qvariant_cast 的语义不同。在 JavaScript 等效类型之间存在许多隐式转换，但qvariant_cast 默认不会执行这些转换。

另请参阅 coerceValue()、fromScriptValue() 和qvariant_cast()。

QJSValue QJSEngine::globalObject() const

返回该引擎的全局对象。

默认情况下，全局对象包含属于ECMA-262 标准的内置对象，例如 Math、Date 和 String。此外，您可以设置全局对象的属性，以便将自定义扩展提供给所有脚本代码使用。 脚本代码中的非局部变量将被创建为全局对象的属性，全局代码中的局部变量也是如此。

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

如果上次 JavaScript 执行引发了异常，或者调用了 `throwError()`，则返回 `true `；否则返回 `false`。请注意，`evaluate()` 会捕获评估代码中抛出的任何异常。

该函数在 Qt 6.1 中引入。

QJSValue QJSEngine::importModule(const QString &fileName)

导入位于fileName 的模块，并返回一个模块命名空间对象，该对象将所有导出的变量、常量和函数作为属性包含其中。

如果这是该模块在引擎中首次被导入，则会从本地文件系统或 Qt 资源系统中指定的位置加载该文件，并将其作为 ECMAScript 模块进行解析。该文件应采用 UTF-8 编码。

后续导入同一模块时，将返回先前导入的实例。模块是单例，并在引擎销毁前一直存在。

指定的fileName 将在内部通过QFileInfo::canonicalFilePath()进行规范化处理。这意味着，即使使用不同的相对路径多次导入磁盘上的同一文件，该文件也只会加载一次。

另请参阅 registerModule()。

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

安装 JavaScriptextensions ，以添加标准 ECMAScript 实现中不具备的功能。

这些扩展将安装在指定的 `object` 上；若未指定对象，则安装在 `Global Object ` 上。

可以通过将枚举值作为 `OR` 参数来一次性安装多个扩展：

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

另请参阅 Extension 。

bool QJSEngine::isInterrupted() const

返回当前 JavaScript 执行是否已被中断。

另请参阅 ` setInterrupted()`。

QJSValue QJSEngine::newArray(uint length = 0)

创建一个属于 Array 类的 JavaScript 对象，其length 为给定值。

另请参阅 newObject()。

QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())

创建一个属于 Error 类的 JavaScript 对象，其错误消息为message 。

创建的对象的原型将为errorType 。

另请参阅 newObject()、throwError() 和QJSValue::isError()。

QJSValue QJSEngine::newObject()

创建一个属于 Object 类的 JavaScript 对象。

创建的对象的原型将设置为 Object 原型对象。

另请参阅 newArray() 和QJSValue::setProperty()。

template <typename T> QJSValue QJSEngine::newQMetaObject()

创建一个 JavaScript 对象，该对象封装了与类 `T` 关联的静态 `QMetaObject `。

另请参阅 newQObject() 和QObject Integration 。

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

创建一个 JavaScript 对象，该对象封装了给定的QMetaObject 。metaObject 的生命周期必须长于脚本引擎。建议仅将此方法用于静态元对象。

当作为构造函数调用时，将创建该类的一个新实例。只有由Q_INVOKABLE 公开的构造函数才可在脚本引擎中访问。

另请参阅 newQObject() 和QObject Integration 。

QJSValue QJSEngine::newQObject(QObject *object)

创建一个 JavaScript 对象，该对象使用JavaScriptOwnership 将给定的QObject object 进行封装。

object 的信号与插槽、属性及子节点均可作为创建的QJSValue 的属性使用。

如果 `object ` 是空指针，则该函数返回空值。当 `object ` 已被排入删除队列或其析构函数正在运行时，同样会返回空值。

如果已为object 的类（或其父类，递归地）注册了默认原型，则新脚本对象的原型将被设置为该默认原型。

如果给定的object 在引擎控制范围之外被删除，则任何尝试通过JavaScript封装对象（无论是脚本代码还是C++）访问已被删除的QObject 成员的行为，都将导致script exception 异常。

另请参阅 QJSValue::toQObject()。

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

创建一个类为 Symbol 的 JavaScript 对象，其值为name 。

所创建对象的原型将是 Symbol 原型对象。

该函数在 Qt 6.2 中引入。

另请参阅 newObject()。

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

返回object 的所有权。

另请参阅 setObjectOwnership() 和QJSEngine::ObjectOwnership 。

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

注册一个QJSValue 以作为模块。调用此函数后，所有导入moduleName 的模块都将导入value 的值，而非从文件系统加载moduleName 。

任何有效的 `QJSValue ` 均可进行注册，但命名导出（即 `import { name } from "info"`）将被视为对象的成员，因此默认导出必须通过 `QJSEngine` 的 `newXYZ` 方法之一创建。

由于这允许导入文件系统中不存在的模块，脚本应用程序可以利用此功能提供内置模块，类似于 Node.js。

成功时返回 `true `，否则返回 `false `。

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

另请参阅 importModule()。

void QJSEngine::setInterrupted(bool interrupted)

中断或重新启用 JavaScript 执行。

如果interrupted 的值为true ，则该引擎执行的任何JavaScript都会立即中止，并返回一个错误对象，直到再次调用此函数且interrupted 的值设置为false 为止。

该函数是线程安全的。您可以从另一个线程调用它，例如，以中断 JavaScript 中的无限循环。

另请参阅 isInterrupted()。

[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)

设置 `object` 的 `ownership ` 属性。

只要对象仍有父对象，即使没有任何引用指向它，具有JavaScriptOwnership 的对象也不会被垃圾回收。

另请参阅 objectOwnership() 和QJSEngine::ObjectOwnership 。

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

抛出一个带有给定message 的运行时错误（异常）。

该方法是 JavaScript 中 `throw() ` 表达式的 C++ 对应实现。它使 C++ 代码能够向 `QJSEngine` 报告运行时错误。因此，它仅应由通过 `QJSEngine` 由 JavaScript 函数调用的 C++ 代码调用。

当从 C++ 返回时，引擎将中断正常的执行流程，并调用下一个预先注册的异常处理程序，同时传递一个包含给定message 的错误对象。该错误对象将指向 JavaScript 调用栈中最高层上下文的位置；具体而言，它将具有lineNumber 、fileName 和stack 这些属性。这些属性在Script Exceptions 中有详细说明。

在下面的示例中，FileAccess.cpp中的一个 C++ 方法在qmlFile.qml中调用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;
}

也可以在 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);
  }
}

如果您需要更具体的运行时错误来描述异常，可以使用throwError(QJSValue::ErrorType errorType, const QString &message) 的重载。

该函数在 Qt 5.12 中引入。

另请参阅 Script Exceptions 。

[since 6.1] void QJSEngine::throwError(const QJSValue &error)

抛出一个预先构建的运行时error （异常）。通过这种方式，您可以使用newErrorObject()来创建该错误，并根据需要对其进行自定义。

该函数在 Qt 6.1 中引入。

另请参阅 Script Exceptions 和newErrorObject()。

[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())

抛出一个运行时错误（异常），其errorType 和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");
  }
  ...
}

该函数在 Qt 5.12 中引入。

另请参阅 Script Exceptions 和newErrorObject()。

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

创建一个QJSManagedValue ，其value 为给定值。

另请参阅 fromManagedValue() 和coerceValue()。

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

创建一个QJSPrimitiveValue ，其value 为给定值。

由于QJSPrimitiveValue 只能容纳int、bool、double、QString ，以及JavaScript中null 和undefined 的等效类型，因此若传入其他类型，系统将进行强制转换。

另请参阅 fromPrimitiveValue() 和coerceValue()。

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

创建一个QJSValue ，其value 为给定值。

另请参阅 fromScriptValue() 和coerceValue()。