QJSValue类
QJSValue类充当Qt/JavaScript数据类型的容器。 更多...
| 头文件 | #include <QJSValue> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake | QT += qml |
公开类型
| 枚举 | ErrorType { GenericError, RangeError, ReferenceError, SyntaxError, TypeError, URIError } |
| 枚举 | ObjectConversionBehavior { ConvertJSObjects, RetainJSObjects } |
| 枚举 | SpecialValue { UndefinedValue, NullValue } |
公开函数
| QJSValue(QJSValue::SpecialValue value = UndefinedValue) | |
| QJSValue(bool value) | |
| QJSValue(int value) | |
| QJSValue(uint value) | |
| QJSValue(double value) | |
| QJSValue(const QString &value) | |
| QJSValue(const QLatin1String &value) | |
| QJSValue(const char *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 |
| bool | isVariant() 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标准中定义的类型：原始类型，包括Undefined、Null、Boolean、Number和String；以及Object和Array类型。此外，还提供了对Qt/C++类型，如QVariant和QObject的内置支持。
对于基于对象的类型（包括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 与另一个值。
注意，对于 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();
另请参阅QJSEngine 和 QJSValueIterator。
成员类型文档
enum QJSValue::ErrorType
使用此枚举值来表示 JavaScript 语言特定的 Error 对象类型。
它们可能在模拟 C++ 中语言功能的时需要使用特殊异常类型时很有用。此外，它们可能有助于更清晰地传达某些典型条件，而不是抛出通用的 JavaScript 异常。例如，处理网络和资源定位符的代码可能发现使用 URIError 类型传播与损坏的定位符相关的错误很有用。
| 常量 | 值 | 描述 |
|---|---|---|
QJSValue::GenericError | 1 | 一个通用的 Error 对象，但不是任何特定子类型。 |
QJSValue::RangeError | 3 | 一个值没有匹配预期的集合或范围。 |
QJSValue::ReferenceError | 4 | 引用了一个不存在的变量。 |
QJSValue::SyntaxError | 5 | 遇到不遵守语言语法的无效标记或标记序列。 |
QJSValue::TypeError | 6 | 操作数或参数与预期的类型不兼容。 |
QJSValue::URIError | 7 | URI 处理函数使用不当或提供的 URI 是无效的。 |
enum QJSValue::ObjectConversionBehavior
此枚举用于指定在将 JavaScript 对象和符号转换为 QVariant 时应该如何处理没有等效本地 Qt 类型的对象。
| 常量 | 值 | 描述 |
|---|---|---|
QJSValue::ConvertJSObjects | 0 | 尝试执行最佳努力转换，可能会丢失数据。符号转换为 QString。 |
QJSValue::RetainJSObjects | 1 | 值保留为包含在 QVariant 中以 QJSValue 封装的 QJSValue。 |
enum QJSValue::SpecialValue
此枚举用于指定单一值类型。
| 常量 | 值 | 描述 |
|---|---|---|
QJSValue::UndefinedValue | 1 | 一个未定义的值。 |
QJSValue::NullValue | 0 | 一个空值。 |
成员函数文档
QJSValue::QJSValue(QJSValue::SpecialValue value = UndefinedValue)
构造一个包含特殊值的 QJSValue 对象。
QJSValue::QJSValue(bool value)
构造一个包含布尔值的 QJSValue 对象。
QJSValue::QJSValue(int value)
构造一个包含数字值的 QJSValue 对象。
QJSValue::QJSValue(uint value)
构造一个包含数字值的 QJSValue 对象。
QJSValue::QJSValue(double value)
构造一个包含数字值的 QJSValue 对象。
QJSValue::QJSValue(const QString &value)
构造一个包含字符串值的 QJSValue 对象。
QJSValue::QJSValue(const QLatin1String &value)
构造一个包含字符串值的 QJSValue 对象。
QJSValue::QJSValue(const char *value)
构造一个包含字符串值的 QJSValue 对象。
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
将此 QJSValue 作为函数调用，将 args 作为参数传递给函数，并使用 globalObject() 作为 "this" 对象。返回函数返回的值。
如果此 QJSValue 不可调用，call() 不做任何事情并返回一个未定义的 QJSValue。
调用 call() 可能会导致脚本引擎抛出异常；在这种情况下，call() 返回抛出的值（通常是 Error 对象）。您可以在返回值上调用 isError() 来确定是否发生异常。
另请参阅 isCallable()，callWithInstance() 和 callAsConstructor()。
QJSValue QJSValue::callAsConstructor(const QJSValueList &args = QJSValueList()) const
创建一个新的
如果这个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()返回所抛出的值（通常是错误对象）。您可以在返回值上调用isError()以确定是否发生了异常。
另请参阅call。
bool QJSValue::deleteProperty(const QString &name)
尝试删除给定name的该对象的属性。如果属性被删除，则返回true；否则返回false。
此函数的行为与JavaScript的delete运算符一致。特别是
- 不可配置的属性无法删除。
- 即使这个对象没有指定的name属性，此函数也将返回true（即不存在属性可以“简易删除”）。
- 如果该对象没有指定的name属性（自有属性），但
原型链中的某个对象有，则原型对象上的属性不会被删除，此函数将返回true。
另请参阅setProperty()和hasOwnProperty。
bool QJSValue::equals(const QJSValue &other) const
如果这个QJSValue等于other，则返回true，否则返回false。比较遵循ECMA-262第11.9.3节“抽象等式比较算法”中描述的行为。
此函数可以在此QJSValue的类型与另一个值的类型不同的情况下返回true；即比较不是严格的。例如，将数字9与字符串"9"比较返回true；将未定义值与空值比较返回true；将原始值为6的Number对象与原始值为"6"的String对象比较返回true；以及将数字1与布尔值true比较返回true。如果您想执行不包含此类隐式值转换的比较，请使用strictlyEquals。
请注意，如果此QJSValue或另一个值是对象，则调用此函数会对脚本引擎产生副作用，因为引擎将调用该对象的valueOf()函数（以及在可能的情况下 toString）），尝试将对象转换为原始值（可能引发未捕获的脚本异常）。
另请参阅strictlyEquals。
QJSValue::ErrorType QJSValue::errorType() const
如果此QJSValue是Error对象，则返回它表示的错误类型。否则，返回NoError."
另请参阅isError() 和 QJSEngine - 脚本异常。
bool QJSValue::hasOwnProperty(const QString &name) const
如果此对象有一个给定名称的自身（非原型继承）属性，则返回true，否则返回false。
另请参阅property() 和 hasProperty。
bool QJSValue::hasProperty(const QString &name) const
如果此对象有一个给定名称的属性，则返回true，否则返回false。
另请参阅property() 和 hasOwnProperty。
bool QJSValue::isArray() const
如果此QJSValue是Array类的对象，则返回true，否则返回false。
另请参阅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 - 脚本异常。
bool QJSValue::isNull() const
如果此 QJSValue 是原始类型 Null，则返回 true；否则返回 false。
bool QJSValue::isNumber() const
如果此 QJSValue 是原始类型 Number，则返回 true；否则返回 false。
另请参阅toNumber。
bool QJSValue::isObject() const
如果此 QJSValue 是 Object 类型，则返回 true；否则返回 false。
请注意，函数值、变体值和 QObject 值都是对象，因此此函数对于此类值返回 true。
另请参阅QJSEngine::newObject。
bool QJSValue::isQMetaObject() const
如果此 QJSValue 是 QMetaObject，则返回 true；否则返回 false。
另请参阅toQMetaObject 和 QJSEngine::newQMetaObject。
bool QJSValue::isQObject() const
如果此 QJSValue 是 QObject，则返回 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 是原始类型 Undefined 或如果托管值已被清除（通过删除引擎），则返回 true。否则返回 false。
bool QJSValue::isUrl() const
如果此 QJSValue 是 URL JavaScript 类的对象，则返回 true；否则返回 false。
bool QJSValue::isVariant() const
如果此 QJSValue 是变体值，则返回 true；否则返回 false。
另请参阅toVariant。
QJSValue QJSValue::property(const QString &name) const
返回此 QJSValue 有指定 name 的属性值。如果没有此属性，则返回未定义的 QJSValue。
如果属性使用getter函数实现（例如，已设置PropertyGetter标志），调用property()将导致脚本引擎产生副作用，因为getter函数将被调用（可能会导致未捕获的脚本书异常）。如果发生异常，property()将返回抛出的值（通常是Error对象）。
要访问数组元素，请使用< Span class="a" href="qjsvalue.html#setProperty-1" translate="no">setProperty（quint32 arrayIndex，const QJSValue &value）重载。
另请参阅 setProperty（），hasProperty（）和QJSValueIterator。
QJSValue QJSValue::< Span class="name"> property
这是一个覆盖函数。
返回给定arrayIndex的属性。
可以通过两种方式访问数组元素。第一种是使用数组索引作为属性名
qDebug() << jsValueArray.property(QLatin1String("4")).toString();
第二种是使用带有索引的重载
qDebug() << jsValueArray.property(4).toString();
这两种方法都达到同样的结果，但后者
- 更容易使用（可以直接使用整数）
- 更快（无需转换成整数）
如果此QJSValue不是数组对象，则此函数的行为就如同使用arrayIndex的字符串表示调用property()函数。
QJSValue QJSValue::< Span class="name"> prototype（)< Span class="plink" href="#prototype" title="Direct link to this heading">
如果此QJSValue是对象，则返回此对象的内部原型（__proto__属性）；否则返回未定义的QJSValue。
另请参阅 setPrototype（）和isObject（）。
void QJSValue::setProperty（const < Span class="type">QString &name，const < Span class="type">QJSValue &value）< Span class="plink" href="#setProperty" title="Direct link to this heading">
将此QJSValue的属性值.name设置给给定的value。
如果此QJSValue不是对象，则此函数不执行任何操作。
如果此QJSValue尚未具有名为name的属性，则创建一个新的属性。
要更改数组元素，请使用setProperty（quint32 arrayIndex，const QJSValue &value）重载。
另请参阅 property（）和deleteProperty（）。
void QJSValue::setProperty（quint32 arrayIndex，const < Span class="type">QJSValue &value）< Span class="plink" href="#setProperty-1" title="Direct link to this heading">
这是一个覆盖函数。
将给定arrayIndex的属性设置给给定的value。
可以通过两种方式修改数组元素。第一种是使用数组索引作为属性名
jsValueArray.setProperty(QLatin1String("4"), value);
第二种是使用带有索引的重载
jsValueArray.setProperty(4, value);
这两种方法都达到同样的结果，但后者
- 更容易使用（可以直接使用整数）
- 更快（无需转换成整数）
如果此QJSValue不是数组对象，则此函数的行为就如同使用arrayIndex的字符串表示调用setProperty()函数。
另请参阅 property（quint32 arrayIndex）和数组操作。
void QJSValue::setPrototype（const QJSValue &prototype）< Span class="plink" href="#setPrototype" title="Direct link to this heading">
如果这个QJSValue是对象，将此对象的内部原型（__proto__属性）设置为prototype；如果QJSValue是null，则将原型设置为null；否则不做任何操作。
内部原型不应与名为"prototype"的公开属性混淆；公开原型通常仅在充当构造函数的函数上设置。
bool QJSValue::strictlyEquals(const QJSValue &other) const
如果此QJSValue使用严格比较（无转换）等于other，则返回true，否则返回false。比较遵循ECMA-262第11.9.6节中所描述的行为，“严格的相等比较算法”。
如果此QJSValue的类型与other值的类型不同，则此函数返回false。如果类型相同，结果取决于类型，如下表所示
| 类型 | 结果 |
|---|---|
| Undefined | true |
| Null | true |
| Boolean | 如果两个值都为true，则为true，否则为false |
| Number | 如果任一值是NaN（非数字），则为 false；如果值相等，则为 true，否则为 false |
| String | 如果两个值都完全是相同的字符序列，则为 true，否则为 false |
| Object | 如果两个值引用的是同一对象，则为 true，否则为 false |
另请参阅equals()。
bool QJSValue::toBool() const
返回此QJSValue的布尔值，使用ECMA-262第9.2节中描述的转换规则，“转换为布尔值”。
请注意，如果此QJSValue是对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的价值函数（可能还有toString））以尝试将对象转换为原始值（可能产生未捕获的脚本异常）。
另请参阅isBool()。
QDateTime QJSValue::toDateTime() const
返回此值的QDateTime表示，为本地时间。如果此QJSValue不是日期或日期的值是NaN（非数字），将返回无效的QDateTime。
另请参阅isDate()。
qint32 QJSValue::toInt() const
返回此QJSValue的带符号32位整数值，使用ECMA-262第9.5节中描述的转换规则，“ToInt32”。
请注意，如果此QJSValue是对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的价值函数（可能还有toString））以尝试将对象转换为原始值（可能产生未捕获的脚本异常）。
double QJSValue::toNumber() const
返回此QJSValue的数字值，根据ECMA-262第9.3节中定义的规则，“ToNumber”。
请注意，如果此QJSValue是对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的价值函数（可能还有toString））以尝试将对象转换为原始值（可能产生未捕获的脚本异常）。
另请参阅isNumber()，toInt()和toUInt()。
QJSPrimitiveValue QJSValue::toPrimitive() const
将值转换为QJSPrimitiveValue。如果值是QJSPrimitiveValue支持的类型，则复制值。否则，将值转换为字符串，并将字符串存储在QJSPrimitiveValue中。
注意：将托管值转换为字符串可能会抛出异常。特别是，符号不能被强制转换为字符串，或者可能抛出自定义的toString() 方法。在这种情况下，结果是未定义的值，并且在转换之后引擎包含一个错误。
const QMetaObject *QJSValue::toQMetaObject() const
如果这个QJSValue是一个QMetaObject，则返回这个QJSValue所代表的QMetaObject指针；否则，返回nullptr。
另请参阅：isQMetaObject()。
QObject *QJSValue::toQObject() const
如果这个QJSValue是一个QObject，则返回这个QJSValue所代表的QObject指针；否则，返回nullptr。
如果此QJSValue包装的QObject已被删除，则此函数返回nullptr（即，当isQObject()返回true时，也可以让toQObject()返回nullptr）。
另请参阅：isQObject()。
QString QJSValue::toString() const
返回此QJSValue的字符串值，如ECMA-262的第9.8节“ToString”中定义。
请注意，如果此QJSValue是一个对象，则调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的toString()函数（以及可能的价值Of()）以尝试将对象转换为原始值（可能引发未捕获的脚本异常）。
另请参阅：isString()。
quint32 QJSValue::toUInt() const
返回此QJSValue的无符号32位整数值，使用ECMA-262的第9.6节“ToUint32”中描述的转换规则。
请注意，如果此QJSValue是对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的价值函数（可能还有toString））以尝试将对象转换为原始值（可能产生未捕获的脚本异常）。
QVariant QJSValue::toVariant(QJSValue::ObjectConversionBehavior behavior) const
如果可以将此QJSValue转换为QVariant，则返回此QJSValue的QVariant值；否则返回一个无效的QVariant。一些JavaScript类型和对象在Qt中具有本地表达式。它们被转换为它们的本地表达式。例如
| 输入类型 | 结果 |
|---|---|
| Undefined | 一个无效的QVariant。 |
| Null | 包含空指针（QMetaType::Nullptr）的QVariant。 |
| Boolean | 包含布尔值的QVariant。 |
| Number | 包含数字值的QVariant。 |
| String | 包含字符串值的QVariant。 |
| QVariant对象 | 结果是对象的无转换QVariant值。 |
| QObject对象 | 包含指向QObject指针的QVariant。 |
| 日期对象 | 包含日期值的QVariant（toDateTime()). |
| 正则表达式对象 | 包含正则表达式值的QVariant。 |
对于其他类型，行为参数是相关的。如果提供了ConvertJSObjects，则尝试进行最佳尝试转换，但这种转换可能是损失性的。通用JavaScript对象转换为QVariantMap。JavaScript数组转换为QVariantList。每个属性或元素都递归地转换为QVariant；不跟随循环引用。JavaScript函数对象被丢弃。如果提供了RetainJSObjects，则通过QVariant::fromValue()将QJSValue包裹到QVariant中。 resulting conversion is lossless but the internal structure of the objects is not immediately accessible.
另请参阅isVariant().
QVariant QJSValue::toVariant() const
这是一个覆盖函数。
返回到Variant(ConvertJSObjects).
另请参阅isVariant().
QJSValue &QJSValue::operator=(QJSValue &&other)
将other移动分配给此QJSValue对象。
QJSValue &QJSValue::operator=(const QJSValue &other)
将other值赋给此QJSValue。
请注意，如果other是对象（isObject()返回true），则只会分配底层对象的引用；对象本身不会被复制。
© 2024 Qt公司有限公司。本文件中包含的文档贡献是各自所有者的版权。提供的文档根据自由软件基金会发布的GNU自由文档许可协议第1.3版的条款进行许可。Qt和相应的标志是芬兰和/或全球其他地区的Qt公司有限公司的商标。所有其他商标均为各自所有者的财产。
