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)

返回已转换为模板类型To 的给定from 。转换以 JavaScript 语义进行。这与qvariant_cast 的语义不同。qvariant_cast 默认不执行 JavaScript 等价类型之间的一些隐式转换。该方法是对该类中所有其他转换方法的概括。

另请参见 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)

使用lineNumber 作为基准行号，对program 进行求值，并返回求值结果。

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

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

lineNumber 用于指定 的起始行号；引擎报告的与本次评估相关的行号信息将以该参数为基础。例如，如果 由两行代码组成，而第二行的语句会导致脚本异常，则异常行号为 加一。如果没有指定起始行号，行号将以 1 为基准。program program lineNumber

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

exceptionStackTrace 用于报告是否抛出了未捕获异常。如果将指向 的非空指针传递给它，那么如果脚本抛出了未处理异常，它就会将该指针设置为 "栈帧消息 "列表，否则就会设置为空列表。堆栈帧消息的格式为：函数名：行号：列：文件名QStringList

另请参阅 QQmlExpression::evaluate 。

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

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

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

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

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

由于QJSPrimitiveValue 只能容纳 int、bool、double、QString 以及 JavaScriptnull 和undefined 的等价类型，因此如果请求任何其他类型，该值将被强制性强制转换。

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

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

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

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

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

返回已转换为模板类型T 的给定value 。转换以 JavaScript 语义进行。这与qvariant_cast 的语义不同。qvariant_cast 默认不执行 JavaScript 等价类型之间的隐式转换。

另请参见 coerceValue(),fromScriptValue(), 和qvariant_cast().

QJSValue QJSEngine::globalObject() const

返回该引擎的全局对象。

默认情况下，全局对象包含ECMA-262 的内置对象，如数学、日期和字符串。此外，您还可以设置全局对象的属性，以便在所有脚本代码中使用自己的扩展。脚本代码中的非本地变量将创建为全局对象的属性，全局代码中的本地变量也将创建为全局对象的属性。

[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-ing 枚举值，可以同时安装多个扩展：

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

另请参见 Extension 。

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

创建一个类为 Error 的 JavaScript 对象，错误信息为message 。

创建对象的原型是errorType 。

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

QJSValue QJSEngine::newObject()

创建一个对象类的 JavaScript 对象。

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

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

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

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

另请参阅 newQObject() 和QObject Integration 。

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

创建封装给定QMetaObject 的 JavaScript 对象metaObject 的寿命必须超过脚本引擎的寿命。建议仅对静态元对象使用此方法。

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

另请参阅 newQObject() 和QObject Integration 。

QJSValue QJSEngine::newQObject(QObject *object)

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

object 的信号和插槽、属性和子对象可作为创建的QJSValue 的属性使用。

如果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 。

另请参阅 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 抛出运行时错误（异常）。

该方法在 C++ 中对应于 JavaScript 中的throw() 表达式。它能让 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)

该函数重载 throwError()。

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

该函数在 Qt 6.1 中引入。

另请参阅 Script Exceptions 和newErrorObject()。

[since 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 中引入。

另请参阅 Script Exceptions 和newErrorObject()。

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

用给定的value 创建QJSManagedValue 。

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

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

使用给定的value 创建QJSPrimitiveValue 。

由于QJSPrimitiveValue 只能容纳 int、bool、double、QString 以及 JavaScriptnull 和undefined 的等价类型，因此如果传递任何其他类型，值将被强制强制。

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

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

用给定的value 创建QJSValue 。

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