PySide6.QtQml.QJSValue

class QJSValue

QJSValue 类充当 Qt/JavaScript 数据类型的容器。更多…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

QJSValue 支持 ECMA-262 标准中定义的类型：原始类型，包括 Undefined、Null、Boolean、Number 和 String；以及 Object 和 Array 类型。此外，还提供了对 Qt/C++ 类型（如 QVariant 和 QObject）的内置支持。

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

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

对象值具有零个或多个属性，这些属性本身是QJSValues。使用setProperty()来设置对象的属性，并调用property()来检索属性的值。

myEngine = QJSEngine()
myObject = myEngine.newObject()
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()为真，它仅携带对实际对象的引用；复制QJSValue只会复制对象引用，而不是对象本身。如果你想克隆一个对象（即将一个对象的属性复制到另一个对象），你可以在脚本代码中使用for-in语句，或者在C++中使用QJSValueIterator来实现。

使用数组

要使用QJSValue创建数组，请使用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类型。例如，要转换为数组，请使用fromScriptValue()：

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

另请参阅

QJSEngine QJSValueIterator

class SpecialValue

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

常量

描述

QJSValue.UndefinedValue

一个未定义的值。

QJSValue.NullValue

一个空值。
class ErrorType

使用此枚举来表示JavaScript语言特定的错误对象类型。

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

常量

描述

QJSValue.GenericError

一个通用的错误对象，但不是特定子类型的。

QJSValue.RangeError

一个值不符合预期的集合或范围。

QJSValue.ReferenceError

引用了一个不存在的变量。

QJSValue.SyntaxError

遇到了不符合语言语法的无效标记或标记序列。

QJSValue.TypeError

操作数或参数与预期类型不兼容。

QJSValue.URIError

URI处理函数使用不正确或提供的URI格式错误。
class ObjectConversionBehavior

此枚举用于指定在转换为QVariant时，应如何处理没有等效原生Qt类型的JavaScript对象和符号。

常量

描述

QJSValue.ConvertJSObjects

尝试进行尽力而为的、可能有损的转换。符号被转换为QString。

QJSValue.RetainJSObjects

该值被保留为QJSValue，并包装在QVariant中。

在版本6.1中添加。

__init__([value=QJSValue.SpecialValue.UndefinedValue])
Parameters:

值 – SpecialValue

构造一个新的QJSValue，具有一个特殊的value。

__init__(value)
Parameters:

value – 布尔值

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

__init__(other)
Parameters:

其他 – QJSValue

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

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

__init__(value)
Parameters:

值 – QLatin1String

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

__init__(value)
Parameters:

值 – str

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

__init__(str)
Parameters:

str – 字符串

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

__init__(value)
Parameters:

value – 浮点数

使用数字 value 构造一个新的 QJSValue。

__init__(value)
Parameters:

值 – int

使用数字 value 构造一个新的 QJSValue。

__init__(value)
Parameters:

值 – int

使用数字 value 构造一个新的 QJSValue。

call([args=QJSValueList()])
Parameters:

args – QJSValue 的列表

Return type:

QJSValue

将此QJSValue作为函数调用，将args作为参数传递给函数，并使用globalObject()作为“this”对象。返回函数返回的值。

如果这个QJSValue不可调用，call()将不执行任何操作并返回一个未定义的QJSValue。

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

callAsConstructor([args=QJSValueList()])
Parameters:

args – QJSValue 的列表

Return type:

QJSValue

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

如果这个QJSValue不是一个函数，callAsConstructor()将不执行任何操作并返回一个未定义的QJSValue。

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

另请参阅

call() newObject()

callWithInstance(instance[, args=QJSValueList()])
Parameters:

  • 实例 – QJSValue

  • args – QJSValue 的列表

Return type:

QJSValue

将此QJSValue作为函数调用，使用instance作为函数调用中的`this`对象，并将args作为参数传递给函数。返回函数返回的值。

如果这个QJSValue不是一个函数，call()将不执行任何操作并返回一个未定义的QJSValue。

请注意，如果instance不是一个对象，全局对象（参见globalObject()）将被用作`this`对象。

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

另请参阅

call()

deleteProperty(name)
Parameters:

name – str

Return type:

布尔

尝试删除此对象的给定name属性。如果属性被删除，则返回true，否则返回false。

此函数的行为与 JavaScript 的 delete 操作符一致。具体来说：

  • 不可配置的属性不能被删除。

  • 即使此对象没有给定name的属性（即不存在的属性是“可轻松删除的”），此函数也将返回true。

  • 如果此对象没有给定name的自有属性，但prototype()链中的某个对象有该属性，则不会删除原型对象的属性，并且此函数返回true。

另请参阅

setProperty() hasOwnProperty()

equals(other)
Parameters:

其他 – QJSValue

Return type:

布尔

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

即使此QJSValue的类型与other值的类型不同，此函数也可能返回true；即比较不是严格的。例如，将数字9与字符串“9”进行比较返回true；将未定义的值与null值进行比较返回true；将原始值为6的Number对象与原始值为“6”的String对象进行比较返回true；将数字1与布尔值true进行比较返回true。如果你想执行没有这种隐式值转换的比较，请使用strictlyEquals()。

请注意，如果此QJSValue或other值是对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的valueOf()函数（可能还会调用toString()）以尝试将对象转换为原始值（可能导致未捕获的脚本异常）。

另请参阅

strictlyEquals()

errorType()
Return type:

ErrorType

如果这是一个错误对象，则返回此QJSValue表示的错误类型。否则，返回NoError。

另请参阅

isError() QJSEngine - 脚本异常

hasOwnProperty(name)
Parameters:

name – str

Return type:

布尔

如果此对象具有给定name的自有（非原型继承的）属性，则返回true，否则返回false。

另请参阅

property() hasProperty()

hasProperty(name)
Parameters:

name – str

Return type:

布尔

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

isArray()
Return type:

布尔

如果这个 QJSValue 是 Array 类的对象，则返回 true；否则返回 false。

另请参阅

newArray()

isBool()
Return type:

布尔

如果这个QJSValue是原始类型Boolean，则返回true；否则返回false。

另请参阅

toBool()

isCallable()
Return type:

布尔

如果这个QJSValue是一个函数，则返回true，否则返回false。

另请参阅

call()

isDate()
Return type:

布尔

如果这个QJSValue是Date类的对象，则返回true；否则返回false。

isError()
Return type:

布尔

如果这个QJSValue是Error类的对象，则返回true；否则返回false。

另请参阅

errorType() QJSEngine - 脚本异常

isNull()
Return type:

布尔

如果这个QJSValue是原始类型Null，则返回true；否则返回false。

isNumber()
Return type:

布尔

如果此QJSValue是原始类型Number，则返回true；否则返回false。

另请参阅

toNumber()

isObject()
Return type:

布尔

如果这个QJSValue是对象类型，则返回true；否则返回false。

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

另请参阅

newObject()

isQMetaObject()
Return type:

布尔

如果这个QJSValue是一个QMetaObject，则返回true；否则返回false。

isQObject()
Return type:

布尔

如果这个QJSValue是一个QObject，则返回true；否则返回false。

注意：即使此QJSValue包装的QObject已被删除，此函数也会返回true。

另请参阅

toQObject() newQObject()

isRegExp()
Return type:

布尔

如果这个QJSValue是RegExp类的对象，则返回true；否则返回false。

isString()
Return type:

布尔

如果此QJSValue是原始类型字符串，则返回true；否则返回false。

另请参阅

toString()

isUndefined()
Return type:

布尔

如果此QJSValue是原始类型Undefined，或者如果托管值已被清除（通过删除引擎），则返回true。否则返回false。

isUrl()
Return type:

布尔

如果这个QJSValue是URL JavaScript类的对象，则返回true；否则返回false。

注意

对于一个包含QUrl的QJSValue，此函数返回false。然而，toVariant().value()在两种情况下都有效。

isVariant()
Return type:

布尔

注意

此函数已弃用。

如果这个QJSValue是一个变体值，则返回true；否则返回false。

警告

此函数可能会产生意外的结果。只有在非常有限的情况下，QJSEngine 才会构造一个变体值。在 Qt 5.14 之前，情况有所不同，toScriptValue 会为更多类型创建它们，而不是相应的 ECMAScript 类型。对于许多 isVariant 返回 false 的值，您可以通过 toVariant 获取有效的 QVariant。

另请参阅

toVariant()

property(name)
Parameters:

name – str

Return type:

QJSValue

返回此QJSValue的给定name属性的值。如果不存在这样的属性，则返回一个未定义的QJSValue。

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

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

property(arrayIndex)
Parameters:

arrayIndex – 整数

Return type:

QJSValue

这是一个重载函数。

返回给定arrayIndex处的属性。

可以通过两种方式访问数组中的元素。第一种是使用数组索引作为属性名：

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

第二种是使用带有索引的重载：

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

这两种方法都达到了相同的结果，除了后者：

  • 更容易使用（可以直接使用整数）

  • 更快（无需转换为整数）

如果这个 QJSValue 不是一个数组对象，这个函数的行为就像使用 arrayIndex 的字符串表示调用了 property() 一样。

prototype()
Return type:

QJSValue

如果这个QJSValue是一个对象，返回该对象的内部原型（__proto__属性）；否则返回一个未定义的QJSValue。

另请参阅

setPrototype() isObject()

setProperty(name, value)
Parameters:

将此QJSValue的属性值设置为给定的name和value。

如果这个QJSValue不是一个对象，这个函数不会执行任何操作。

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

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

setProperty(arrayIndex, value)
Parameters:

这是一个重载函数。

将给定arrayIndex处的属性设置为给定value。

可以通过两种方式修改数组中的元素。第一种是使用数组索引作为属性名：

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

第二种是使用带有索引的重载：

jsValueArray.setProperty(4, value);

这两种方法都达到了相同的结果，除了后者：

  • 更容易使用（可以直接使用整数）

  • 更快（无需转换为整数）

如果这个 QJSValue 不是一个数组对象，这个函数的行为就像使用 arrayIndex 的字符串表示调用了 setProperty() 一样。

另请参阅

property(quint32 arrayIndex) 使用数组

setPrototype(prototype)
Parameters:

原型 – QJSValue

如果这个QJSValue是一个对象，将这个对象的内部原型（__proto__属性）设置为prototype；如果QJSValue为null，则将原型设置为null；否则不做任何操作。

内部原型不应与名为“prototype”的公共属性混淆；公共原型通常仅设置在充当构造函数的函数上。

另请参阅

prototype() isObject()

strictlyEquals(other)
Parameters:

其他 – QJSValue

Return type:

布尔

如果这个QJSValue与other严格相等（不进行转换），则返回true，否则返回false。该比较遵循ECMA-262第11.9.6节“严格相等比较算法”中描述的行为。

如果这个QJSValue的类型与other值的类型不同，此函数返回false。如果类型相同，结果取决于类型，如下表所示：

类型

结果

未定义

true

空值

真

Boolean

如果两个值都为真，则为真，否则为假

数字

如果任一值为NaN（非数字），则为false；如果值相等，则为true，否则为false

String

如果两个值是完全相同的字符序列，则为 true，否则为 false

Object

如果两个值引用同一个对象，则为true，否则为false

另请参阅

equals()

toBool()
Return type:

布尔

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

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

另请参阅

isBool()

toDateTime()
Return type:

QDateTime

返回此值的QDateTime表示，使用本地时间。如果此QJSValue不是日期，或者日期的值是NaN（非数字），则返回无效的QDateTime。

另请参阅

isDate()

toInt()
Return type:

整数

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

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

另请参阅

toNumber() toUInt()

toNumber()
Return type:

浮点数

返回此QJSValue的数值，如ECMA-262第9.3节“ToNumber”中所定义。

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

另请参阅

isNumber() toInt() toUInt()

toPrimitive()
Return type:

QJSPrimitiveValue

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

注意

将托管值转换为字符串可能会抛出异常。特别是，符号不能被强制转换为字符串，或者自定义的toString()方法可能会抛出异常。在这种情况下，结果是未定义的值，并且引擎在转换后会携带一个错误。

toQMetaObject()
Return type:

QMetaObject

* 如果这个 QJSValue 是一个 QMetaObject，返回 QJSValue 所代表的 QMetaObject 指针；否则，返回 None。 * *

另请参阅

isQMetaObject()

toQObject()
Return type:

QObject

如果这个QJSValue是一个QObject，返回QJSValue所代表的QObject指针；否则，返回None。

如果此QJSValue包装的QObject已被删除，此函数将返回None（即，即使isQObject()返回true，toQObject()也可能返回None）。

另请参阅

isQObject()

toString()
Return type:

字符串

返回此QJSValue的字符串值，如ECMA-262第9.8节“ToString”中所定义。

请注意，如果这个QJSValue是一个对象，调用此函数会对脚本引擎产生副作用，因为引擎将调用对象的toString()函数（可能还有valueOf()）以尝试将对象转换为原始值（可能导致未捕获的脚本异常）。

另请参阅

isString()

toUInt()
Return type:

整数

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

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

另请参阅

toNumber() toInt()

toVariant()
Return type:

对象

这是一个重载函数。

返回 toVariant ( ConvertJSObjects )。

另请参阅

isVariant()

toVariant(behavior)
Parameters:

行为 – ObjectConversionBehavior

Return type:

对象

返回此QJSValue的QVariant值，如果它可以转换为QVariant；否则返回一个无效的QVariant。一些JavaScript类型和对象在Qt中有本地表达式。这些将被转换为其本地表达式。例如：

输入类型

结果

未定义

一个无效的 QVariant。

空

包含空指针的 QVariant（QMetaType::Nullptr）。

布尔值

包含布尔值的QVariant。

数字

包含数字值的 QVariant。

String

包含字符串值的 QVariant。

QVariant 对象

结果是对象的 QVariant 值（不进行转换）。

QObject 对象

一个包含指向 QObject 指针的 QVariant。

日期对象

包含日期值的QVariant（toDateTime()）。

正则表达式对象

包含正则表达式值的QVariant。

对于其他类型，behavior 参数是相关的。如果给出 ConvertJSObjects，则会尝试进行尽力但可能有损的转换。通用的 JavaScript 对象被转换为 QVariantMap。JavaScript 数组被转换为 QVariantList。每个属性或元素都会被递归地转换为 QVariant；不会跟随循环引用。JavaScript 函数对象会被丢弃。如果给出 RetainJSObjects，则 QJSValue 会通过 QVariant::fromValue() 包装成 QVariant。生成的转换是无损的，但对象的内部结构不能立即访问。

另请参阅

isVariant()