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）的内置支持。

对于基于对象的类型（包括日期和时间），使用QJSEngine（例如newObject()）中的newT()函数来创建所需类型的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只会复制对象引用，而不会复制对象本身。如果您想要克隆对象（即复制对象的属性到另一个对象），您可以使用脚本代码中的QJSValueIterator或者在C++中使用脚本代码中的for-in语句。

处理数组#

要使用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

一个null值。
class ErrorType#

为此枚举提供JavaScript语言特定的Error对象类型。

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

常量

描述

QJSValue.GenericError

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

QJSValue.RangeError

一个值未匹配预期的集合或范围。

QJSValue.ReferenceError

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

QJSValue.SyntaxError

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

QJSValue.TypeError

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

QJSValue.URIError

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

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

常量

描述

QJSValue.ConvertJSObjects

尝试最佳尝试转换，可能存在数据丢失。符号转换为QString。

QJSValue.RetainJSObjects

值以QJSValue包装在QVariant中保持不变。

自6.1版本开始引入。

__init__(value)#
参数:

value – bool

使用布尔值创建一个新的QJSValue。

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

value – SpecialValue

创建一个新的带有特殊值的QJSValue

__init__(value)
参数:

value – int

使用数字值创建一个新的QJSValue

__init__(value)
参数:

value – int

使用数字值创建一个新的QJSValue

__init__(value)
参数:

value – float

使用数字值创建一个新的QJSValue

__init__(value)
参数:

value – str

使用字符串值创建一个新的QJSValue

__init__(value)
参数:

value – QLatin1String

使用字符串值创建一个新的QJSValue

__init__(other)
参数:

other – QJSValue

创建一个新的QJSValue，它是other的副本。

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

__init__(str)
参数:

str – 字符串

使用字符串值创建一个新的QJSValue

call([args=QJSValueList()])#
参数:

args – .的 QJSValue 列表

返回类型：

QJSValue

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

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

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

callAsConstructor([args=QJSValueList()])#
参数:

args – .的 QJSValue 列表

返回类型：

QJSValue

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

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

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

另请参阅

call() newObject()

callWithInstance(instance[, args=QJSValueList()])#
参数:

  • instance – QJSValue

  • args – .的 QJSValue 列表

返回类型：

QJSValue

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

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

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

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

另请参阅

call()

deleteProperty(name)#
参数:

name – 字符串

返回类型：

布尔值

尝试删除给定名称的此对象的属性。如果成功删除属性，则返回 true，否则返回 false。

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

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

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

  • 如果这个对象没有名为 name 的自有属性，但它的原型链中的某个对象有这个属性，原型对象的属性不会被删除，并且此函数返回 true。

另请参阅

setProperty() hasOwnProperty()

equals(other)#
参数:

other – QJSValue

返回类型：

布尔值

如果此 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()。

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

另请参阅

strictlyEquals()

errorType()#
返回类型：

错误类型

如果此 QJSValue 是错误对象，则返回它表示的错误类型。否则，返回 NoError."

另请参阅

isError() QJSEngine - 脚本异常

拥有属性
参数:

name – 字符串

返回类型：

布尔值

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

另请参阅

property() hasProperty()

拥有属性
参数:

name – 字符串

返回类型：

布尔值

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

数组
返回类型：

布尔值

如果该 QJSValue 是数组类的对象，则返回 true，否则返回 false。

另请参阅

创建数组

布尔值
返回类型：

布尔值

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

另请参阅

转换为布尔值

可调用
返回类型：

布尔值

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

另请参阅

call()

日期
返回类型：

布尔值

如果该 QJSValue 是日期类的对象，则返回 true，否则返回 false。

错误
返回类型：

布尔值

如果该 QJSValue 是错误类的对象，则返回 true，否则返回 false。

另请参阅

errorType() QJSEngine - 脚本异常

空值
返回类型：

布尔值

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

isNumber()#
返回类型：

布尔值

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

另请参阅

toNumber()

isObject()#
返回类型：

布尔值

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

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

另请参阅

newObject()

isQMetaObject()#
返回类型：

布尔值

如果此 QJSValue 是 QMetaObject，则返回 true；否则返回 false。

isQObject()#
返回类型：

布尔值

如果此 QJSValue 是 QObject，则返回 true；否则返回 false。

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

另请参阅

toQObject() newQObject()

isRegExp()#
返回类型：

布尔值

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

isString()#
返回类型：

布尔值

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

另请参阅

toString()

isUndefined()#
返回类型：

布尔值

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

isUrl()#
返回类型：

布尔值

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

注意

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

isVariant()#
返回类型：

布尔值

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

另请参阅

toVariant()

property(name)#
参数:

name – 字符串

返回类型：

QJSValue

返回具有给定 name 的属性值。如果不存在此类属性，将返回一个未定义的 QJSValue。

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

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

property(arrayIndex)
参数:

arrayIndex> – int

返回类型：

QJSValue

这是一个重载函数。

返回给定 arrayIndex 的属性。

可以通过两种方式访问数组中的元素。首先是通过将数组索引用作属性名

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

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

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

这两种方法都能达到相同的结果，但后者

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

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

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

prototype()#
返回类型：

QJSValue

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

另请参阅

setPrototype() isObject()

setProperty(name, value)#
参数:

将这个 QJSValue 的 name 属性的值设置为给定的 value。

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

如果这个 QJSValue 已经有名为 name 的属性，则创建一个新属性。

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

setProperty(arrayIndex, value)
参数:

这是一个重载函数。

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

有几种方式可以修改数组元素。第一种是使用数组索引作为属性名。

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

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

jsValueArray.setProperty(4, value);

这两种方法都能达到相同的结果，但后者

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

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

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

另请参阅

property(quint32 arrayIndex) 使用数组

setPrototype(prototype)#
参数:

原型 – QJSValue

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

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

另请参阅

prototype() isObject()

strictlyEquals(other)#
参数:

other – QJSValue

返回类型：

布尔值

如果此 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()

toBool()#
返回类型：

布尔值

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

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

另请参阅

isBool()

toDateTime()#
返回类型：

QDateTime

返回此值的局部时间QDateTime表示。如果此QJSValue不是日期或日期值是NaN（不是数字），则返回一个无效的QDateTime。

另请参阅

isDate()

toInt()#
返回类型：

int

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

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

另请参阅

toNumber() toUInt()

toNumber()#
返回类型：

float

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

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

另请参阅

isNumber() toInt() toUInt()

toPrimitive()#
返回类型：

QJSPrimitiveValue

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

注意

将受管理值转换为字符串可能会抛出异常。特别是，符号不能强制转换为字符串，或者自定义toString()方法可能会抛出。在这种情况下，结果是无定义的值，并在转换后将错误引擎保留。

toQMetaObject()#
返回类型：

QMetaObject

如果此QJSValue是QMetaObject，则返回它表示的QMetaObject指针；否则，返回None。*

另请参阅

isQMetaObject()

toQObject()#
返回类型：

QObject

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

如果此 QJSValue 包裹的 QObject 被删除，此函数返回 None（即在调用 isQObject() 返回 true 的情况下，toQObject() 也有可能返回 None）。

另请参阅

isQObject()

toString()#
返回类型：

str

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

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

另请参阅

isString()

toUInt()#
返回类型：

int

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

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

另请参阅

toNumber() toInt()

toVariant()#
返回类型：

object

这是一个重载函数。

返回 toVariant ( ConvertJSObjects )。

另请参阅

isVariant()

toVariant(behavior)
参数:

behavior – ObjectConversionBehavior

返回类型：

object

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

输入类型

结果

Undefined

无效的 QVariant。

Null

包含空指针 (QMetaType::Nullptr) 的 QVariant。

Boolean

包含布尔值值的QVariant。

Number

包含数字值的QVariant。

String

包含字符串值的QVariant。

QVariant对象

结果是对象的无转换QVariant值。

QObject对象

包含QObject指针的QVariant。

Date对象

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

正则表达式对象

包含正则表达式值的QVariant。

对于其他类型，behavior参数是有意义的。如果提供ConvertJSObjects，则尝试进行最佳但可能是有损的转换。通用JavaScript对象转换为QVariantMap。JavaScript数组转换为QVariantList。每个属性或元素都递归转换为QVariant；不跟循循环引用。JavaScript函数对象被丢弃。如果提供RetainJSObjects，则通过QVariant::fromValue()将QJSValue包装到QVariant中。 resulting conversion是无损的，但对象的内部结构不可立即访问。

另请参阅

isVariant()