QJSEngine 类

成员函数文档

QJSEngine::QJSEngine()

构建一个QJSEngine对象。

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

[显式] QJSEngine::QJSEngine(QObject *parent)

使用指定的parent构建一个QJSEngine对象。

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

[覆盖虚拟noexcept] QJSEngine::~QJSEngine()

销毁此QJSEngine。

在QJSEngine销毁期间不会从持久JS堆中收集垃圾。如果您需要释放所有内存，请在销毁QJSEngine之前手动调用collectGarbage()。

[自Qt 6.1起] QJSValue QJSEngine::catchError()

如果当前有异常待处理，则捕获异常并以QJSValue的形式返回它。否则以QJSValue返回undefined。调用此方法后，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认为这样做明智时（即创建了一定的新的对象数时），垃圾回收器将自动调用。然而，您可以通过调用此函数来明确请求尽快执行垃圾回收。

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

使用lineNumber作为基准行号，评估program并返回评估的结果。

脚本代码将在全局对象上下文中进行评估。

program的评估可能会在引擎中引起异常；在这种情况下，返回值将是抛出的异常（通常是Error对象；请参阅QJSValue::isError）。

lineNumber用于指定program的起始行号；与此次评估相关的引擎报告的行号信息将基于此参数。例如，如果program由两行代码组成，且第二行的语句引发脚本异常，则异常行号将是lineNumber加一。如果没有指定起始行号，则行号从1开始。

fileName用于错误报告。例如，如果此函数提供了文件名，错误对象中的文件名可以通过"fileName"属性访问。

exceptionStackTrace用于报告是否抛出了未捕获的异常。如果您向其中传递一个指向QStringList的非空指针，则如果脚本抛出了未处理的异常，它将设置为其的"stackframe messages"列表，否则为空列表。栈帧消息的格式为函数名:行号:列:文件名

参阅：QQmlExpression::evaluate。

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

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

参阅：toManagedValue() 和 coerceValue。

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

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

由于 QJSPrimitiveValue 只能容纳 int、bool、double、QString 以及 JavaScript 中 null 和 undefined 的等价物，如果你请求其他类型，值将被强制转换。

参阅：toPrimitiveValue() 和 coerceValue。

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

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

参阅：toScriptValue() 和 coerceValue。

模板 <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。此外，你可以设置全局对象的属性，以便所有脚本代码都可以使用你自己的扩展。脚本代码中的非局部变量将作为全局对象的属性创建，以及作为全局代码中的局部变量。

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

安装 JavaScript extensions 以添加标准 ECMAScript 实现中不存在的功能。

扩展将安装在指定的 object 上，如果没有指定对象，则安装在 Global Object 上。

可以通过对枚举值执行 OR 运算来一次性安装多个扩展。

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

另请参阅：Extension。

QJSValue QJSEngine::isInterrupted() const

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

另请参阅：setInterrupted。

QJSValue QJSEngine::newArray(uint length = 0)

创建具有给定 length 的类 Array 的 JavaScript 对象。

另请参阅：newObject。

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

创建一个将 message 作为错误消息的类 Error 的 JavaScript 对象。

创建的对象的基类将是 errorType。

另请参阅：newObject，throwError 和 QJSValue::isError。

QJSValue QJSEngine::newObject()

创建一个类 Object 的 JavaScript 对象。

创建的对象的基类将是 Object 原型对象。

另请参阅：newArray 和 QJSValue::setProperty。

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

创建一个JavaScript对象，该对象封装了指定的 QMetaObject。该 metaObject 必须比脚本引擎寿命更长。建议仅使用此方法与静态元对象。

当作为构造函数调用时，将创建该类的新实例。只有通过 Q_INVOKABLE 披露的构造函数才可以从脚本引擎中看到。

另请参阅 newQObject() 和 QObject集成。

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

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

另请参阅 newQObject() 和 QObject集成。

QJSValue QJSEngine::newQObject(QObject *object)

创建一个JavaScript对象，该对象封装了指定的 QObject object，使用 JavaScriptOwnership。

object 的信号和槽、属性和子对象都可作为创建的 QJSValue 的属性访问。

如果 object 是一个空指针，则此函数返回空值。

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

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

另请参阅 QJSValue::toQObject。

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

创建一个具有值 name 的Symbol类的JavaScript对象。

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

此功能在Qt 6.2中引入。

另请参阅：newObject。

[静态] 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 的新XYZ方法之一来创建默认导出。

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

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

另请参阅：importModule()。

void QJSEngine::setInterrupted(bool interrupted)

中断或重新启用JavaScript执行。

如果interrupted为true，此引擎执行的所有JavaScript将立即终止并返回一个错误对象，直到再次调用此函数且interrupted的值为false。

此函数是线程安全的。您可以从不同的线程调用它以中断，例如，JavaScript中的无限循环。

另请参阅：isInterrupted()。

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

设置object的所有权。

只要对象仍有父对象，即使没有引用它，具有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属性。这些属性在脚本异常中描述。

在以下示例中，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中引入的。

另请参阅脚本异常。

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

此函数重载了 throwError()。

抛出带有给定 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中引入的。

另请参阅脚本异常 和 newErrorObject。

[自 6.1 版本开始] void QJSEngine::throwError(const QJSValue &error)

此函数重载了 throwError()。

抛出一个预先构建的运行时 error（异常）。这样你可以使用 newErrorObject() 创建错误并根据需要对其进行自定义。

此函数是在Qt 6.1中引入的。

另请参阅脚本异常 和 newErrorObject。

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

创建一个带有给定 value 的 QJSManagedValue。

另请参阅fromManagedValue() 和 coerceValue。

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

创建一个带有给定 value 的 QJSPrimitiveValue。

由于 QJSPrimitiveValue 只能持有 int、bool、double、QString 以及 JavaScript null 和 undefined 的等效值，如果传入其他类型，则值将被强制转换为。

另请参阅fromPrimitiveValue() 和 coerceValue。

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

创建一个带有给定 value 的 QJSValue。

另请参阅fromScriptValue() 和 coerceValue。