QJSValue Class

The https:// class acts as a container for Qt/JavaScript data types.

This class was introduced in Qt 5.0.

Article lu fois.

L'auteur

The Qt Company Ltd.

L'article

Publié le 27 décembre 2024 - Mis à jour le 27 décembre 2024

Liens sociaux

QJSValue Class▲

Header: QJSValue
Since: Qt 5.0
CMake:

find_package(Qt6 REQUIRED COMPONENTS Qml)

target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Group: QJSValue is part of qtjavascript

Detailed Description▲

https:// supports the types defined in the https:// standard: The primitive types, which are Undefined, Null, Boolean, Number, and String; and the Object and Array types. Additionally, built-in support is provided for Qt/C++ types such as https:// and https://.

For the object-based types (including Date and RegExp), use the newT() functions in https:// (e.g. https://()) to create a https:// of the desired type. For the primitive types, use one of the https:// constructor overloads. For other types, e.g. registered gadget types such as https://, you can use https://.

The methods named isT() (e.g. https://(), https://()) can be used to test if a value is of a certain type. The methods named toT() (e.g. https://(), https://()) can be used to convert a https:// to another type. You can also use the generic qjsvalue_cast() function.

Object values have zero or more properties which are themselves QJSValues. Use https://() to set a property of an object, and call https://() to retrieve the value of a property.

Sélectionnez

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

If you want to iterate over the properties of a script object, use the https:// class.

Object values have an internal prototype property, which can be accessed with https://() and https://().

Function objects (objects for which https://()) returns true) can be invoked by calling https://(). Constructor functions can be used to construct new objects by calling https://().

Use https://() or https://() to compare a https:// to another.

Note that a https:// for which https://() is true only carries a reference to an actual object; copying the https:// will only copy the object reference, not the object itself. If you want to clone an object (i.e. copy an object's properties to another object), you can do so with the help of a for-in statement in script code, or https:// in C++.

Working With Arrays▲

To create an array using https://, use https://():

Sélectionnez

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

To set individual elements in the array, use the setProperty(quint32 arrayIndex, const QJSValue &value) overload. For example, to fill the array above with integers:

Sélectionnez

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

To determine the length of the array, access the "length" property. To access array elements, use the property(quint32 arrayIndex) overload. The following code reads the array we created above back into a list:

Sélectionnez

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

Member Type Documentation▲

[since 5.12] enum QJSValue::ErrorType▲

Use this enum for JavaScript language-specific types of Error objects.

They may be useful when emulating language features in C++ requires the use of specialized exception types. In addition, they may help to more clearly communicate certain typical conditions, instead of throwing a generic JavaScript exception. For example, code that deals with networking and resource locators may find it useful to propagate errors related to malformed locators using the URIError type.

Constant	Value	Description
https://::GenericError	1	A generic Error object, but not of a specific sub-type.
https://::RangeError	3	A value did not match the expected set or range.
https://::ReferenceError	4	A non-existing variable referenced.
https://::SyntaxError	5	An invalid token or sequence of tokens was encountered that does not conform with the syntax of the language.
https://::TypeError	6	An operand or argument is incompatible with the type expected.
https://::URIError	7	A URI handling function was used incorrectly or the URI provided is malformed.

This enum was introduced or modified in Qt 5.12.

enum QJSValue::ObjectConversionBehavior▲

This enum is used to specify how JavaScript objects without an equivalent native Qt type should be treated when converting to https://.

Constant	Value	Description
https://::ConvertJSObjects	0	A best-effort, possibly lossy, conversion is attempted.
https://::RetainJSObjects	1	The value is retained as https:// wrapped in https://.

enum QJSValue::SpecialValue▲

This enum is used to specify a single-valued type.

Constant	Value	Description
https://::UndefinedValue	1	An undefined value.
https://::NullValue	0	A null value.

Member Function Documentation▲

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

Constructs a new https:// with a special value.

QJSValue::QJSValue(bool value)▲

Constructs a new https:// with a boolean value.

QJSValue::QJSValue(int value)▲

Constructs a new https:// with a number value.

QJSValue::QJSValue(uint value)▲

Constructs a new https:// with a number value.

QJSValue::QJSValue(double value)▲

Constructs a new https:// with a number value.

QJSValue::QJSValue(const QString &value)▲

Constructs a new https:// with a string value.

QJSValue::QJSValue(const QLatin1String &value)▲

Constructs a new https:// with a string value.

QJSValue::QJSValue(const char *value)▲

Constructs a new https:// with a string value.

QJSValue::QJSValue(const QJSValue &other)▲

Constructs a new https:// that is a copy of other.

Note that if other is an object (i.e., https://() would return true), then only a reference to the underlying object is copied into the new script value (i.e., the object itself is not copied).

QJSValue::QJSValue(QJSValue &&other)▲

Move constructor. Moves from other into this https:// object.

QJSValue::~QJSValue()▲

Destroys this https://.

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

Calls this https:// as a function, passing args as arguments to the function, and using the globalObject() as the "this"-object. Returns the value returned from the function.

If this https:// is not callable, call() does nothing and returns an undefined https://.

Calling call() can cause an exception to occur in the script engine; in that case, call() returns the value that was thrown (typically an Error object). You can call https://() on the return value to determine whether an exception occurred.

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

Creates a new Object and calls this https:// as a constructor, using the created object as the `this' object and passing args as arguments. If the return value from the constructor call is an object, then that object is returned; otherwise the default constructed object is returned.

If this https:// is not a function, callAsConstructor() does nothing and returns an undefined https://.

Calling this function can cause an exception to occur in the script engine; in that case, the value that was thrown (typically an Error object) is returned. You can call https://() on the return value to determine whether an exception occurred.

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

Calls this https:// as a function, using instance as the `this' object in the function call, and passing args as arguments to the function. Returns the value returned from the function.

If this https:// is not a function, https://() does nothing and returns an undefined https://.

Note that if instance is not an object, the global object (see https://()) will be used as the `this' object.

Calling https://() can cause an exception to occur in the script engine; in that case, https://() returns the value that was thrown (typically an Error object). You can call https://() on the return value to determine whether an exception occurred.

bool QJSValue::deleteProperty(const QString &name)▲

Attempts to delete this object's property of the given name. Returns true if the property was deleted, otherwise returns false.

The behavior of this function is consistent with the JavaScript delete operator. In particular:

Non-configurable properties cannot be deleted.
This function will return true even if this object doesn't have a property of the given name (i.e., non-existent properties are "trivially deletable").
If this object doesn't have an own property of the given name, but an object in the https://() chain does, the prototype object's property is not deleted, and this function returns true.

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

Returns true if this https:// is equal to other, otherwise returns false. The comparison follows the behavior described in https:// section 11.9.3, "The Abstract Equality Comparison Algorithm".

This function can return true even if the type of this https:// is different from the type of the other value; i.e. the comparison is not strict. For example, comparing the number 9 to the string "9" returns true; comparing an undefined value to a null value returns true; comparing a Number object whose primitive value is 6 to a String object whose primitive value is "6" returns true; and comparing the number 1 to the boolean value true returns true. If you want to perform a comparison without such implicit value conversion, use https://().

Note that if this https:// or the other value are objects, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possibly https://()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

[since 5.12] QJSValue::ErrorType QJSValue::errorType() const▲

Returns the error type this https:// represents if it is an Error object. Otherwise, returns NoError."

This function was introduced in Qt 5.12.

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

Returns true if this object has an own (not prototype-inherited) property of the given name, otherwise returns false.

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

Returns true if this object has a property of the given name, otherwise returns false.

bool QJSValue::isArray() const▲

Returns true if this https:// is an object of the Array class; otherwise returns false.

bool QJSValue::isBool() const▲

Returns true if this https:// is of the primitive type Boolean; otherwise returns false.

bool QJSValue::isCallable() const▲

Returns true if this https:// is a function, otherwise returns false.

bool QJSValue::isDate() const▲

Returns true if this https:// is an object of the Date class; otherwise returns false.

bool QJSValue::isError() const▲

Returns true if this https:// is an object of the Error class; otherwise returns false.

bool QJSValue::isNull() const▲

Returns true if this https:// is of the primitive type Null; otherwise returns false.

bool QJSValue::isNumber() const▲

Returns true if this https:// is of the primitive type Number; otherwise returns false.

bool QJSValue::isObject() const▲

Returns true if this https:// is of the Object type; otherwise returns false.

Note that function values, variant values, and https:// values are objects, so this function returns true for such values.

[since 5.8] bool QJSValue::isQMetaObject() const▲

Returns true if this https:// is a https://; otherwise returns false.

This function was introduced in Qt 5.8.

bool QJSValue::isQObject() const▲

Returns true if this https:// is a https://; otherwise returns false.

Note: This function returns true even if the https:// that this https:// wraps has been deleted.

bool QJSValue::isRegExp() const▲

Returns true if this https:// is an object of the RegExp class; otherwise returns false.

bool QJSValue::isString() const▲

Returns true if this https:// is of the primitive type String; otherwise returns false.

bool QJSValue::isUndefined() const▲

Returns true if this https:// is of the primitive type Undefined or if the managed value has been cleared (by deleting the engine). Otherwise returns false.

bool QJSValue::isUrl() const▲

Returns true if this https:// is an object of the URL class; otherwise returns false.

bool QJSValue::isVariant() const▲

Returns true if this https:// is a variant value; otherwise returns false.

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

Returns the value of this https://'s property with the given name. If no such property exists, an undefined https:// is returned.

If the property is implemented using a getter function (i.e. has the PropertyGetter flag set), calling property() has side-effects on the script engine, since the getter function will be called (possibly resulting in an uncaught script exception). If an exception occurred, property() returns the value that was thrown (typically an Error object).

To access array elements, use the setProperty(quint32 arrayIndex, const QJSValue &value) overload instead.

QJSValue QJSValue::property(quint32 arrayIndex) const▲

This is an overloaded function.

Returns the property at the given arrayIndex.

It is possible to access elements in an array in two ways. The first is to use the array index as the property name:

Sélectionnez

qDebug() &lt;&lt; jsValueArray.property(QLatin1String("4")).toString();

The second is to use the overload that takes an index:

Sélectionnez

qDebug() &lt;&lt; jsValueArray.property(4).toString();

Both of these approaches achieve the same result, except that the latter:

Is easier to use (can use an integer directly)
Is faster (no conversion to integer)

If this https:// is not an Array object, this function behaves as if https://() was called with the string representation of arrayIndex.

QJSValue QJSValue::prototype() const▲

If this https:// is an object, returns the internal prototype (__proto__ property) of this object; otherwise returns an undefined https://.

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

Sets the value of this https://'s property with the given name to the given value.

If this https:// is not an object, this function does nothing.

If this https:// does not already have a property with name name, a new property is created.

To modify array elements, use the setProperty(quint32 arrayIndex, const QJSValue &value) overload instead.

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

This is an overloaded function.

Sets the property at the given arrayIndex to the given value.

It is possible to modify elements in an array in two ways. The first is to use the array index as the property name:

Sélectionnez

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

The second is to use the overload that takes an index:

Sélectionnez

jsValueArray.setProperty(4, value);

Both of these approaches achieve the same result, except that the latter:

Is easier to use (can use an integer directly)
Is faster (no conversion to integer)

If this https:// is not an Array object, this function behaves as if https://() was called with the string representation of arrayIndex.

void QJSValue::setPrototype(const QJSValue &prototype)▲

If this https:// is an object, sets the internal prototype (__proto__ property) of this object to be prototype; if the https:// is null, it sets the prototype to null; otherwise does nothing.

The internal prototype should not be confused with the public property with name "prototype"; the public prototype is usually only set on functions that act as constructors.

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

Returns true if this https:// is equal to other using strict comparison (no conversion), otherwise returns false. The comparison follows the behavior described in https:// section 11.9.6, "The Strict Equality Comparison Algorithm".

If the type of this https:// is different from the type of the other value, this function returns false. If the types are equal, the result depends on the type, as shown in the following table:

Type	Result
Undefined	true
Null	true
Boolean	true if both values are true, false otherwise
Number	false if either value is NaN (Not-a-Number); true if values are equal, false otherwise
String	true if both values are exactly the same sequence of characters, false otherwise
Object	true if both values refer to the same object, false otherwise

bool QJSValue::toBool() const▲

Returns the boolean value of this https://, using the conversion rules described in https:// section 9.2, "ToBoolean".

Note that if this https:// is an object, calling this function has side effects on the script engine, since the engine will call the object's valueOf() function (and possibly https://()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

QDateTime QJSValue::toDateTime() const▲

Returns a https:// representation of this value, in local time. If this https:// is not a date, or the value of the date is NaN (Not-a-Number), an invalid https:// is returned.

qint32 QJSValue::toInt() const▲

Returns the signed 32-bit integer value of this https://, using the conversion rules described in https:// section 9.5, "ToInt32".

double QJSValue::toNumber() const▲

Returns the number value of this https://, as defined in https:// section 9.3, "ToNumber".

QJSPrimitiveValue QJSValue::toPrimitive() const▲

Converts the value to a https://. If the value holds a type supported by https://, the value is copied. Otherwise the value is converted to a string, and the string is stored in https://.

Conversion of a managed value to a string can throw an exception. In particular, symbols cannot be coerced into strings, or a custom https://() method may throw. In this case the result is the undefined value and the engine carries an error after the conversion.

[since 5.8] const QMetaObject *QJSValue::toQMetaObject() const▲

* If this https:// is a https://, returns the https:// pointer * that the https:// represents; otherwise, returns nullptr. * *

This function was introduced in Qt 5.8.

QObject *QJSValue::toQObject() const▲

If this https:// is a https://, returns the https:// pointer that the https:// represents; otherwise, returns nullptr.

If the https:// that this https:// wraps has been deleted, this function returns nullptr (i.e. it is possible for toQObject() to return nullptr even when https://() returns true).

QString QJSValue::toString() const▲

Returns the string value of this https://, as defined in https:// section 9.8, "ToString".

Note that if this https:// is an object, calling this function has side effects on the script engine, since the engine will call the object's toString() function (and possibly valueOf()) in an attempt to convert the object to a primitive value (possibly resulting in an uncaught script exception).

quint32 QJSValue::toUInt() const▲

Returns the unsigned 32-bit integer value of this https://, using the conversion rules described in https:// section 9.6, "ToUint32".

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

Returns the https:// value of this https://, if it can be converted to a https://; otherwise returns an invalid https://. Some JavaScript types and objects have native expressions in Qt. Those are converted to their native expressions. For example:

Input Type	Result
Undefined	An invalid https://.
Null	A https:// containing a null pointer (https://).
Boolean	A https:// containing the value of the boolean.
Number	A https:// containing the value of the number.
String	A https:// containing the value of the string.
https:// Object	The result is the https:// value of the object (no conversion).
https:// Object	A https:// containing a pointer to the https://.
Date Object	A https:// containing the date value (https://()).
https:// Object	A https:// containing the regular expression value.

For other types the behavior parameter is relevant. If ConvertJSObjects is given, a best effort but possibly lossy conversion is attempted. Generic JavaScript objects are converted to https://. JavaScript arrays are converted to https://. Each property or element is converted to a https://, recursively; cyclic references are not followed. JavaScript function objects are dropped. If RetainJSObjects is given, the https:// is wrapped into a https:// via https://(). The resulting conversion is lossless but the internal structure of the objects is not immediately accessible.

QVariant QJSValue::toVariant() const▲

This is an overloaded function.

Returns https://(https://).

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

Move-assigns other to this https:// object.

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

Assigns the other value to this https://.

Note that if other is an object (https://() returns true), only a reference to the underlying object will be assigned; the object itself will not be copied.

Related Non-Members▲

QJSValueList▲

This is a typedef for a https://<https://>.

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants :

QJSValue Class

L'auteur

L'article

Liens sociaux

QJSValue Class▲

Detailed Description▲

Working With Arrays▲

See Also▲

Member Type Documentation▲

[since 5.12] enum QJSValue::ErrorType▲

enum QJSValue::ObjectConversionBehavior▲

enum QJSValue::SpecialValue▲

Member Function Documentation▲

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

QJSValue::QJSValue(bool value)▲

QJSValue::QJSValue(int value)▲

QJSValue::QJSValue(uint value)▲

QJSValue::QJSValue(double value)▲

QJSValue::QJSValue(const QString &value)▲

QJSValue::QJSValue(const QLatin1String &value)▲

QJSValue::QJSValue(const char *value)▲

QJSValue::QJSValue(const QJSValue &other)▲

QJSValue::QJSValue(QJSValue &&other)▲

QJSValue::~QJSValue()▲

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

See Also▲

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

See Also▲

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

See Also▲

bool QJSValue::deleteProperty(const QString &name)▲

See Also▲

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

See Also▲

[since 5.12] QJSValue::ErrorType QJSValue::errorType() const▲

See Also▲

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

See Also▲

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

See Also▲

bool QJSValue::isArray() const▲

See Also▲

bool QJSValue::isBool() const▲

See Also▲

bool QJSValue::isCallable() const▲

See Also▲

bool QJSValue::isDate() const▲

bool QJSValue::isError() const▲

See Also▲

bool QJSValue::isNull() const▲

bool QJSValue::isNumber() const▲

See Also▲

bool QJSValue::isObject() const▲

See Also▲

[since 5.8] bool QJSValue::isQMetaObject() const▲

See Also▲

bool QJSValue::isQObject() const▲

See Also▲

bool QJSValue::isRegExp() const▲

bool QJSValue::isString() const▲

See Also▲

bool QJSValue::isUndefined() const▲

bool QJSValue::isUrl() const▲

bool QJSValue::isVariant() const▲

See Also▲

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

See Also▲

QJSValue QJSValue::property(quint32 arrayIndex) const▲

QJSValue QJSValue::prototype() const▲

See Also▲

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

See Also▲

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

See Also▲

void QJSValue::setPrototype(const QJSValue &prototype)▲

See Also▲

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

See Also▲

bool QJSValue::toBool() const▲

See Also▲