QJSValue Class

QJSValue 类是 Qt/JavaScript 数据类型的容器。更多

头文件: #include <QJSValue>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml

公共类型

enum ErrorType { GenericError, RangeError, ReferenceError, SyntaxError, TypeError, URIError }
enum ObjectConversionBehavior { ConvertJSObjects, RetainJSObjects }
enum SpecialValue { UndefinedValue, NullValue }

公共函数

QJSValue(QJSValue::SpecialValue value = UndefinedValue)
QJSValue(bool value)
QJSValue(const QLatin1String &value)
QJSValue(const QString &value)
QJSValue(const char *value)
QJSValue(double value)
QJSValue(int value)
QJSValue(uint value)
QJSValue(const QJSValue &other)
QJSValue(QJSValue &&other)
~QJSValue()
QJSValue call(const QJSValueList &args = QJSValueList()) const
QJSValue callAsConstructor(const QJSValueList &args = QJSValueList()) const
QJSValue callWithInstance(const QJSValue &instance, const QJSValueList &args = QJSValueList()) const
bool deleteProperty(const QString &name)
bool equals(const QJSValue &other) const
QJSValue::ErrorType errorType() const
bool hasOwnProperty(const QString &name) const
bool hasProperty(const QString &name) const
bool isArray() const
bool isBool() const
bool isCallable() const
bool isDate() const
bool isError() const
bool isNull() const
bool isNumber() const
bool isObject() const
bool isQMetaObject() const
bool isQObject() const
bool isRegExp() const
bool isString() const
bool isUndefined() const
bool isUrl() const
QJSValue property(const QString &name) const
QJSValue property(quint32 arrayIndex) const
QJSValue prototype() const
void setProperty(const QString &name, const QJSValue &value)
void setProperty(quint32 arrayIndex, const QJSValue &value)
void setPrototype(const QJSValue &prototype)
bool strictlyEquals(const QJSValue &other) const
bool toBool() const
QDateTime toDateTime() const
qint32 toInt() const
double toNumber() const
QJSPrimitiveValue toPrimitive() const
const QMetaObject *toQMetaObject() const
QObject *toQObject() const
QString toString() const
quint32 toUInt() const
QVariant toVariant(QJSValue::ObjectConversionBehavior behavior) const
QVariant toVariant() const
QJSValue &operator=(QJSValue &&other)
QJSValue &operator=(const QJSValue &other)

详细说明

QJSValue 支持ECMA-262标准中定义的类型:原始类型包括未定义类型、空类型、布尔类型、数字类型和字符串类型;对象类型和数组类型。此外,还为QVariantQObject 等 Qt/C++ 类型提供了内置支持。

对于基于对象的类型(包括 Date 和 RegExp),请使用QJSEngine 中的 newT() 函数(如QJSEngine::newObject()) 创建所需类型的 QJSValue。对于原始类型,请使用 QJSValue 构造函数重载之一。对于其他类型,例如已注册的小工具类型(如QPoint ),可以使用QJSEngine::toScriptValue

名为 isT() 的方法(如isBool(),isUndefined() )可用于测试值是否属于某种类型。名为 toT() 的方法(如toBool(),toString() )可用于将 QJSValue 转换为另一种类型。您还可以使用通用的 qjsvalue_cast() 函数。

对象值有零个或多个属性,这些属性本身就是 QJSValue。使用setProperty() 设置对象的属性,调用property() 获取属性值。

QJSEngine myEngine;
QJSValue myObject = myEngine.newObject();
QJSValue myOtherObject = myEngine.newObject();
myObject.setProperty("myChild", myOtherObject);
myObject.setProperty("name", "John Doe");

如果要遍历脚本对象的属性,请使用QJSValueIterator 类。

对象值有一个内部prototype 属性,可通过prototype() 和setPrototype() 访问。

函数对象(isCallable()) 返回 true 的对象)可以通过调用call() 来调用。构造函数可以通过调用callAsConstructor() 来构造新对象。

使用equals() 或strictlyEquals() 可以比较一个 QJSValue 和另一个 QJSValue。

请注意,isObject() 为 true 的 QJSValue 只携带对实际对象的引用;复制 QJSValue 只会复制对象引用,而不会复制对象本身。如果要克隆一个对象(即复制一个对象的属性到另一个对象),可以借助脚本代码中的for-in 语句或 C++ 中的QJSValueIterator 来实现。

使用数组

要使用 QJSValue 创建数组,请使用QJSEngine::newArray() :

// Assumes that this class was declared in QML.
QJSValue jsArray = engine->newArray(3);

要设置数组中的单个元素,请使用setProperty(quint32 arrayIndex, const QJSValue &value) 重载。例如,用整数填充上述数组:

for (int i = 0; i < 3; ++i) {
    jsArray.setProperty(i, QRandomGenerator::global().generate());
}

要确定数组的长度,请访问"length" 属性。要访问数组元素,请使用property(quint32 arrayIndex) 重载。下面的代码会将我们创建的数组读回列表:

QVector<int> integers;
const int length = jsArray.property("length").toInt();
for (int i = 0; i < length; ++i) {
    integers.append(jsArray.property(i).toInt());
}

转换为 JSON

可以将 QJSValue 转换为 JSON 类型。例如,要转换为数组,请使用QJSEngine::fromScriptValue() :

const QJsonValue jsonValue = engine.fromScriptValue<QJsonValue>(jsValue);
const QJsonArray jsonArray = jsonValue.toArray();

另请参阅 QJSEngineQJSValueIterator

成员类型文档

enum QJSValue::ErrorType

该枚举用于 JavaScript 语言特定类型的错误对象。

当模拟 C++ 语言特性需要使用专门的异常类型时,它们可能会很有用。此外,它们还有助于更清晰地传达某些典型条件,而不是抛出一个通用的 JavaScript 异常。例如,处理网络和资源定位器的代码可能会发现,使用 URIError 类型传播与畸形定位器相关的错误非常有用。

常量描述
QJSValue::GenericError1通用错误对象,但不属于特定子类型。
QJSValue::RangeError3值与预期集合或范围不匹配。
QJSValue::ReferenceError4引用了一个不存在的变量。
QJSValue::SyntaxError5遇到不符合语言语法的无效标记或标记序列。
QJSValue::TypeError6操作符或参数与预期类型不兼容。
QJSValue::URIError7URI 处理函数使用不当,或提供的 URI 不正常。

enum QJSValue::ObjectConversionBehavior

该枚举用于指定在将 JavaScript 对象和符号转换为QVariant 时,如何处理没有对应本地 Qt 类型的 JavaScript 对象和符号。

常量说明
QJSValue::ConvertJSObjects0尝试尽力(可能是有损)转换。符号转换为QString
QJSValue::RetainJSObjects1值保留为QJSValue ,用QVariant 包装。

enum QJSValue::SpecialValue

该枚举用于指定单值类型。

常量描述
QJSValue::UndefinedValue1未定义的值。
QJSValue::NullValue0空值

成员函数文档

QJSValue::QJSValue(QJSValue::SpecialValue value = UndefinedValue)

构造一个新的 QJSValue,其特殊value

QJSValue::QJSValue(bool value)

使用布尔值value 构造一个新的 QJSValue。

QJSValue::QJSValue(const QLatin1String &value)

使用字符串value 构建一个新的 QJSValue。

QJSValue::QJSValue(const QString &value)

使用字符串value 构建一个新的 QJSValue。

QJSValue::QJSValue(const char *value)

使用字符串value 构建一个新的 QJSValue。

QJSValue::QJSValue(double value)

构造一个新的 QJSValue,数值为value

QJSValue::QJSValue(int value)

构造一个新的 QJSValue,数值为value

QJSValue::QJSValue(uint value)

构造一个新的 QJSValue,数值为value

QJSValue::QJSValue(const QJSValue &other)

构造一个新的 QJSValue,它是other 的副本。

请注意,如果other 是一个对象(即isObject() 将返回 true),那么只有对底层对象的引用会被复制到新的脚本值中(即对象本身不会被复制)。

QJSValue::QJSValue(QJSValue &&other)

移动构造函数。从other 移动到此 QJSValue 对象。

[noexcept] QJSValue::~QJSValue()

摧毁QJSValue.

QJSValue QJSValue::call(const QJSValueList &args = QJSValueList()) const

QJSValueargs 作为参数传递给函数,并使用 globalObject() 作为 "this "对象。返回函数返回的值。

如果此QJSValue 不可调用,则 call() 不会执行任何操作,并返回未定义的QJSValue

调用 call() 会导致脚本引擎出现异常;在这种情况下,call() 返回被抛出的值(通常是Error 对象)。您可以调用返回值isError() 来确定是否发生了异常。

另请参阅 isCallable()、callWithInstance() 和callAsConstructor()。

QJSValue QJSValue::callAsConstructor(const QJSValueList &args = QJSValueList()) const

创建一个新的Object ,并调用QJSValue 作为构造函数,使用创建的对象作为 "this "对象,并传递args 作为参数。如果构造函数调用的返回值是一个对象,则返回该对象;否则返回默认构造的对象。

如果QJSValue 不是函数,则 callAsConstructor() 不会执行任何操作,而是返回未定义的QJSValue

调用该函数可能会导致脚本引擎出现异常;在这种情况下,将返回被抛出的值(通常是Error 对象)。您可以在返回值上调用isError() 来确定是否发生了异常。

另请参阅 call() 和QJSEngine::newObject()。

QJSValue QJSValue::callWithInstance(const QJSValue &instance, const QJSValueList &args = QJSValueList()) const

以函数形式调用QJSValue ,在函数调用中使用instance 作为 "this "对象,并将args 作为参数传递给函数。返回函数返回的值。

如果QJSValue 不是函数,则call() 不会执行任何操作,而是返回未定义的QJSValue

请注意,如果instance 不是对象,全局对象(参见QJSEngine::globalObject() )将被用作 "this "对象。

调用call() 可能会导致脚本引擎出现异常;在这种情况下,call() 会返回被抛出的值(通常是Error 对象)。您可以调用返回值isError() 来确定是否发生了异常。

另请参阅 call()。

bool QJSValue::deleteProperty(const QString &name)

尝试删除此对象中name 给定值的属性。如果属性已删除,则返回 true,否则返回 false。

此函数的行为与 JavaScript 的删除操作符一致。特别是

  • 不可配置的属性无法删除。
  • 即使此对象没有给定name 的属性,此函数也会返回 true(也就是说,不存在的属性是 "可删除的")。
  • 如果此对象没有name 的属性,但prototype() 链中的一个对象有,则原型对象的属性不会被删除,此函数返回 true。

另请参见 setProperty() 和hasOwnProperty()。

bool QJSValue::equals(const QJSValue &other) const

如果QJSValue 等于other ,则返回 true,否则返回 false。比较遵循ECMA-262第 11.9.3 节 "抽象相等比较算法 "中描述的行为。

即使QJSValue 的类型与other 值的类型不同,该函数也能返回 true;也就是说,比较并不严格。例如,将数字 9 与字符串 "9 "比较,返回 true;将未定义值与空值比较,返回 true;将基元值为 6 的Number 对象与基元值为 "6 "的String 对象比较,返回 true;将数字 1 与布尔值true 比较,返回 true。如果要执行比较而不进行这种隐式值转换,请使用strictlyEquals()。

请注意,如果QJSValueother 值是对象,调用此函数会对脚本引擎产生副作用,因为引擎会调用对象的 valueOf() 函数(可能还会调用toString() 函数),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参阅 strictlyEquals()。

QJSValue::ErrorType QJSValue::errorType() const

如果QJSValue 是 Error 对象,则返回其代表的错误类型。否则,返回NoError."

另请参阅 isError() 和QJSEngine - Script Exceptions

bool QJSValue::hasOwnProperty(const QString &name) const

如果该对象具有给定name 的自有(非原型继承)属性,则返回 true,否则返回 false。

另请参阅 property() 和hasProperty()。

bool QJSValue::hasProperty(const QString &name) const

如果该对象具有给定name 的属性,则返回 true,否则返回 false。

另请参阅 property() 和hasOwnProperty()。

bool QJSValue::isArray() const

如果QJSValue 是 Array 类对象,则返回 true;否则返回 false。

注: 此方法等同于 JavaScript 中的Array.isArray()。您可以用它来识别 JavaScript 数组,但对于不是 JavaScript 数组的任何类似数组的对象,它将返回false 。这包括值类型或对象类型的 QMLlist对象、JavaScript 类型数组、JavaScript ArrayBuffer 对象,以及任何你自己创建的自定义类数组对象。但所有这些对象的行为都与 JavaScript 数组类似:它们一般都暴露了相同的方法,并且可以使用下标操作符。因此,使用这种方法来确定一个对象是否可以像数组一样使用并不可取。

另请参见 QJSEngine::newArray()。

bool QJSValue::isBool() const

如果QJSValue 属于布尔基元类型,则返回 true;否则返回 false。

另请参阅 toBool()。

bool QJSValue::isCallable() const

如果QJSValue 是函数,则返回 true,否则返回 false。

另请参见 call()。

bool QJSValue::isDate() const

如果QJSValue 是 Date 类对象,则返回 true;否则返回 false。

bool QJSValue::isError() const

如果QJSValue 是 Error 类对象,则返回 true;否则返回 false。

另请参阅 errorType() 和QJSEngine - Script Exceptions

bool QJSValue::isNull() const

如果QJSValue 属于原始类型 Null,则返回 true;否则返回 false。

bool QJSValue::isNumber() const

如果QJSValue 属于原始类型 Number,则返回 true;否则返回 false。

另请参见 toNumber()。

bool QJSValue::isObject() const

如果QJSValue 属于对象类型,则返回 true;否则返回 false。

请注意,函数值、变量值和QObject 值都是对象,因此对于这些值,该函数返回 true。

另请参见 QJSEngine::newObject()。

bool QJSValue::isQMetaObject() const

如果QJSValueQMetaObject ,则返回 true;否则返回 false。

另请参阅 toQMetaObject() 和QJSEngine::newQMetaObject()。

bool QJSValue::isQObject() const

如果QJSValueQObject ,则返回 true;否则返回 false。

注:即使此QJSValue 封装的QObject 已被删除,此函数仍返回 true。

另请参阅 toQObject() 和QJSEngine::newQObject()。

bool QJSValue::isRegExp() const

如果QJSValue 是 RegExp 类对象,则返回 true;否则返回 false。

bool QJSValue::isString() const

如果QJSValue 属于原始类型 String,则返回 true;否则返回 false。

另请参阅 toString()。

bool QJSValue::isUndefined() const

如果QJSValue 属于未定义基元类型,或者托管值已被清除(通过删除引擎),则返回 true。否则返回 false。

bool QJSValue::isUrl() const

如果QJSValue 是 URL JavaScript 类对象,则返回 true;否则返回 false。

注: 对于包含QUrlQJSValue ,此函数返回 false。不过,toVariant().value<QUrl>() 在这两种情况下都有效。

QJSValue QJSValue::property(const QString &name) const

以给定的name 返回此QJSValue'属性的值。如果不存在此类属性,则返回未定义的QJSValue

如果属性是通过获取函数实现的(即设置了 PropertyGetter 标志),调用 property() 会对脚本引擎产生副作用,因为获取函数将被调用(可能导致未捕获的脚本异常)。如果发生异常,property() 会返回抛出的值(通常是Error 对象)。

要访问数组元素,请使用setProperty(quint32 arrayIndex, const QJSValue &value) 重载。

另请参阅 setProperty(),hasProperty() 和QJSValueIterator

QJSValue QJSValue::property(quint32 arrayIndex) const

这是一个重载函数。

返回给定arrayIndex 的属性。

有两种方法可以访问数组中的元素。第一种是使用数组索引作为属性名:

qDebug() << jsValueArray.property(QLatin1String("4")).toString();

第二种是使用重载函数来获取索引:

qDebug() << jsValueArray.property(4).toString();

这两种方法都能达到相同的结果,只是后者更容易使用(可以使用索引重载):

  • 更容易使用(可以直接使用整数)
  • 速度更快(无需转换为整数)

如果QJSValue 不是一个数组对象,则调用 property() 时将使用arrayIndex 的字符串表示。

QJSValue QJSValue::prototype() const

如果QJSValue 是一个对象,则返回该对象的内部原型(__proto__ 属性);否则返回未定义的QJSValue

另请参阅 setPrototype() 和isObject()。

void QJSValue::setProperty(const QString &name, const QJSValue &value)

QJSValue 的属性值与给定的name 设置为给定的value

如果QJSValue 不是对象,则此函数不会执行任何操作。

如果该QJSValue 还没有名称为name 的属性,则会创建一个新属性。

要修改数组元素,请使用setProperty(quint32 arrayIndex, const QJSValue &value) 重载。

另请参阅 property() 和deleteProperty() 。

void QJSValue::setProperty(quint32 arrayIndex, const QJSValue &value)

这是一个重载函数。

arrayIndex 中的属性设置为value

有两种方法可以修改数组中的元素。第一种是使用数组索引作为属性名称:

jsValueArray.setProperty(QLatin1String("4"), value);

第二种是使用重载来获取索引:

jsValueArray.setProperty(4, value);

这两种方法都能达到相同的效果,只是后者更容易使用(可以使用索引重载):

  • 更容易使用(可以直接使用整数)
  • 速度更快(无需转换为整数)

如果QJSValue 不是数组对象,则该函数的行为与调用arrayIndex 的字符串表示的 setProperty() 函数相同。

另请参见 property(quint32 arrayIndex) 和Working With Arrays

void QJSValue::setPrototype(const QJSValue &prototype)

如果QJSValue 是一个对象,则将该对象的内部原型(__proto__ 属性)设置为prototype ;如果QJSValue 为空,则将原型设置为空;否则不做任何操作。

内部原型不应与名为 "prototype "的公共属性相混淆;公共原型通常只在作为构造函数的函数中设置。

另请参见 prototype() 和isObject()。

bool QJSValue::strictlyEquals(const QJSValue &other) const

如果使用严格比较(不转换),该QJSValue 等于other ,则返回 true,否则返回 false。比较遵循ECMA-262第 11.9.6 节 "严格相等比较算法 "中描述的行为。

如果QJSValue 的类型与other 值的类型不同,该函数将返回 false。如果类型相等,结果取决于类型,如下表所示:

类型结果
未定义
布尔如果值均为真或均为假,则为 true,否则为 false
数字如果任一值为 NaN(非数),则为 false;如果值相等,则为 true,否则为 false
字符串如果两个值都是完全相同的字符序列,则为 true;否则为 false
对象如果两个值指向同一个对象,则为 true;否则为 false

另请参见 equals()。

bool QJSValue::toBool() const

使用ECMA-262第 9.2 节 "ToBoolean "中描述的转换规则,返回QJSValue 的布尔值。

请注意,如果QJSValue 是一个对象,调用此函数会对脚本引擎产生副作用,因为脚本引擎会调用对象的 valueOf() 函数(可能还会调用toString() 函数),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参阅 isBool()。

QDateTime QJSValue::toDateTime() const

以当地时间为单位,返回该值的QDateTime 表示形式。如果QJSValue 不是日期,或者日期值是 NaN(非数字),则返回无效的QDateTime

另请参阅 isDate() 。

qint32 QJSValue::toInt() const

使用ECMA-262第 9.5 节 "ToInt32 "中描述的转换规则,返回QJSValue 的有符号 32 位整数值。

请注意,如果QJSValue 是一个对象,调用此函数会对脚本引擎产生副作用,因为脚本引擎会调用对象的 valueOf() 函数(可能还会调用toString() 函数),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参见 toNumber() 和toUInt()。

double QJSValue::toNumber() const

根据ECMA-262第 9.3 节 "ToNumber "的定义,返回QJSValue 的数值。

请注意,如果QJSValue 是一个对象,调用此函数会对脚本引擎产生副作用,因为脚本引擎会调用对象的 valueOf() 函数(可能还会调用toString() 函数),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参阅 isNumber()、toInt() 和toUInt()。

QJSPrimitiveValue QJSValue::toPrimitive() const

将值转换为QJSPrimitiveValue 。如果值持有QJSPrimitiveValue 支持的类型,则复制该值。否则会将值转换为字符串,并将字符串存储在QJSPrimitiveValue 中。

注意: 将托管值转换为字符串可能会产生异常。特别是,符号不能被强制转换为字符串,否则自定义的toString() 方法可能会抛出异常。在这种情况下,转换后的结果是未定义的值,引擎会出现错误。

const QMetaObject *QJSValue::toQMetaObject() const

* 如果QJSValueQMetaObject ,则返回QJSValue 所代表的QMetaObject 指针;否则,返回nullptr 。* *

另请参阅 isQMetaObject() 。

QObject *QJSValue::toQObject() const

如果QJSValueQObject ,则返回QJSValue 所代表的QObject 指针;否则,返回nullptr

如果此QJSValue 封装的QObject 已被删除,则此函数返回nullptr (也就是说,即使isQObject() 返回 true,toQObject() 也有可能返回nullptr )。

另请参阅 isQObject()。

QString QJSValue::toString() const

根据ECMA-262第 9.8 节 "ToString "的定义,返回QJSValue 的字符串值。

请注意,如果QJSValue 是一个对象,调用此函数会对脚本引擎产生副作用,因为脚本引擎会调用对象的 toString() 函数(可能还会调用 valueOf()),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参阅 isString()。

quint32 QJSValue::toUInt() const

使用ECMA-262第 9.6 节 "ToUint32 "中描述的转换规则,返回QJSValue 的无符号 32 位整数值。

请注意,如果QJSValue 是一个对象,调用此函数会对脚本引擎产生副作用,因为脚本引擎会调用对象的 valueOf() 函数(可能还会调用toString() 函数),试图将对象转换为基元值(可能会导致未捕获的脚本异常)。

另请参见 toNumber() 和toInt()。

QVariant QJSValue::toVariant(QJSValue::ObjectConversionBehavior behavior) const

如果可以转换为QVariant ,则返回此QJSValueQVariant 值;否则返回无效的QVariant 。某些 JavaScript 类型和对象在 Qt 中有本地表达式。这些类型和对象会被转换为它们的本地表达式。例如

输入类型结果
未定义无效QVariant
包含空指针的QVariant (QMetaType::Nullptr)。
布尔值包含布尔值的QVariant
数字包含数字值的QVariant
字符串包含字符串值的QVariant
QVariant 对象结果是对象的QVariant 值(无转换)。
QObject 对象一个QVariant ,包含指向QObject 的指针。
日期对象包含日期值 (toDateTime()) 的QVariant
RegularExpression 对象包含正则表达式值的QVariant

对于其他类型,behavior 参数与之相关。如果给定的是ConvertJSObjects ,则会尝试进行尽力而为但可能有损失的转换。通用 JavaScript 对象转换为QVariantMap 。JavaScript 数组会转换为QVariantList 。每个属性或元素都会递归转换为QVariant ;循环引用不会被遵循。JavaScript 函数对象被放弃。如果给出RetainJSObjects ,则通过QVariant::fromValue() 将QJSValue 封装为QVariant 。由此产生的转换是无损的,但无法立即访问对象的内部结构。

另请参见 isVariant()。

QVariant QJSValue::toVariant() const

这是一个重载函数。

返回 toVariant(ConvertJSObjects)。

另请参见 isVariant().

QJSValue &QJSValue::operator=(QJSValue &&other)

Move-assignsotherQJSValue 对象。

QJSValue &QJSValue::operator=(const QJSValue &other)

other 的值赋值给QJSValue

请注意,如果other 是一个对象(isObject() 返回 true),则只会分配对底层对象的引用,而不会复制对象本身。

相关非成员

QJSValueList

这是QList<QJSValue> 的类型定义。

© 2025 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.