Класс QJSValue

Класс QJSValue выступает в качестве контейнера для типов данных Qt/JavaScript. Подробнее...

• Список всех членов, включая унаследованные

Открытые типы

Публичные функции

Связанные нечленные функции

Подробное описание

QJSValue поддерживает типы, определённые в стандарте ECMA-262: примитивные типы (Undefined, Null, Boolean, Number, String); а также типы Object и Array. Также предоставлена встроенная поддержка типов Qt/C++, таких как QVariant и QObject.

Для объектных типов (включая Date и RegExp) используйте функции newT() в QJSEngine (например, QJSEngine::newObject()), чтобы создать QJSValue нужного типа. Для примитивных типов используйте одну из перегрузок конструктора QJSValue. Для других типов, например, зарегистрированных типов гаджетов, таких как QPoint, вы можете использовать QJSEngine::toScriptValue.

Методы с именем isT() (например, isBool(), isUndefined()) могут быть использованы для проверки, является ли значение определенного типа. Методы с именем toT() (например, toBool(), toString()) могут быть использованы для преобразования QJSValue в другой тип. Вы также можете использовать общую функцию qjsvalue_cast().

Объектные значения имеют ноль или более свойств, которые сами являются QJSValues. Используйте 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 скопирует только ссылку на объект, а не сам объект. Если вы хотите клонировать объект (т.е. скопировать свойства объекта в другой объект), вы можете сделать это с помощью оператора for-in в коде сценария или QJSValueIterator в C++.

Работа с массивами

Для создания массива с помощью 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());
}

См. также QJSEngine и QJSValueIterator.

Документация по типу членов

[since 5.12] перечисление QJSValue::ErrorType

Используйте это перечисление для JavaScript-специфических типов объектов Error.

Они могут быть полезны, когда эмуляция функций языка в C++ требует использования специализированных типов исключений. Кроме того, они могут помочь более ясно передать определенные типичные условия, вместо того, чтобы выбрасывать общее JavaScript-исключение. Например, код, работающий с сетевыми соединениями и локаторами ресурсов, может найти полезным распространять ошибки, связанные с неправильно сформированными локаторами, используя тип URIError.

Это перечисление было добавлено или изменено в Qt 5.12.

перечисление QJSValue::SpecialValue

Это перечисление используется для указания однозначного типа.

Документация по функциям-членам

QJSValue::QJSValue(const char *value)

Создает новый QJSValue со строкой value.

QJSValue::QJSValue(const QLatin1String &value)

Создает новый QJSValue со строкой value.

QJSValue::QJSValue(const QString &value)

Создает новый QJSValue со строкой value.

QJSValue::QJSValue(double value)

Создает новый QJSValue с числом value.

QJSValue::QJSValue(uint value)

Создает новый QJSValue с числом value.

QJSValue::QJSValue(int value)

Создает новый QJSValue с числом value.

QJSValue::QJSValue(bool value)

Создает новый QJSValue с булевым значением value.

QJSValue::QJSValue(QJSValue &&other)

Конструктор перемещения. Перемещает из other в этот объект QJSValue.

QJSValue::QJSValue(const QJSValue &other)

Создает новый QJSValue, являющийся копией other.

Обратите внимание, что если other является объектом (т.е. isObject() вернёт true), то в новое значение скрипта копируется только ссылка на базовый объект (т.е. сам объект не копируется).

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

Создает новый QJSValue со специальным значением value.

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

Присваивает значение other этому QJSValue.

Обратите внимание, что если other является объектом (isObject() возвращает true), то будет присвоена только ссылка на базовый объект; сам объект не будет скопирован.

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

Перемещает присвоение other этому объекту QJSValue.

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

Создаёт новый 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 delete. В частности:

• Неизменяемые свойства не могут быть удалены.
• Эта функция вернёт true, даже если у этого объекта нет свойства с данным именем name (т.е. несуществующие свойства "тривиально удаляемы").
• Если у этого объекта нет собственного свойства с данным именем name, но у объекта в цепочке prototype() есть, то свойство объекта прототипа не удаляется, и эта функция возвращает true.

См. также setProperty() и hasOwnProperty().

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

Возвращает true, если этот QJSValue равен other, в противном случае возвращает false. Сравнение следует поведению, описанному в ECMA-262 разделе 11.9.3, "Алгоритм абстрактного сравнения по равенству".

Эта функция может возвращать true, даже если тип этого QJSValue отличается от типа значения other; т.е. сравнение не строгое. Например, сравнение числа 9 со строкой "9" возвращает true; сравнение неопределённого значения с null возвращает true; сравнение объекта Number, чьё примитивное значение равно 6, с объектом String, чьё примитивное значение равно "6", возвращает true; и сравнение числа 1 с логическим значением true возвращает true. Если вы хотите выполнить сравнение без такого неявного преобразования значений, используйте strictlyEquals().

Обратите внимание, что если этот QJSValue или значение other являются объектами, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию valueOf() объекта (и, возможно, toString()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также strictlyEquals().

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

Возвращает тип ошибки, представленный этим QJSValue, если это объект Error. В противном случае возвращает NoError."

Эта функция была добавлена в Qt 5.12.

См. также isError() и QJSEngine - Исключение сценариев.

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

Возвращает true, если у этого объекта есть собственное (не унаследованное от прототипа) свойство с заданным именем name, в противном случае возвращает false.

См. также property() и hasProperty().

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

Возвращает true, если у этого объекта есть свойство с заданным именем name, в противном случае возвращает false.

См. также property() и hasOwnProperty().

bool QJSValue::isArray() const

Возвращает true, если этот QJSValue является объектом класса Array; в противном случае возвращает false.

См. также QJSEngine::newArray().

bool QJSValue::isBool() const

Возвращает true, если этот QJSValue имеет примитивный тип Boolean; в противном случае возвращает false.

См. также toBool().

bool QJSValue::isCallable() const

Возвращает true, если этот QJSValue является функцией, в противном случае возвращает false.

См. также call().

bool QJSValue::isDate() const

Возвращает true, если этот QJSValue является объектом класса Date; в противном случае возвращает false.

bool QJSValue::isError() const

Возвращает true, если этот QJSValue является объектом класса Error; в противном случае возвращает false.

См. также errorType() и QJSEngine - Исключение сценариев.

bool QJSValue::isNull() const

Возвращает true, если этот QJSValue имеет примитивный тип Null; в противном случае возвращает false.

bool QJSValue::isNumber() const

Возвращает true, если этот QJSValue имеет примитивный тип Number; в противном случае возвращает false.

См. также toNumber().

bool QJSValue::isObject() const

Возвращает true, если этот QJSValue имеет тип Object; в противном случае возвращает false.

Обратите внимание, что значения функций, значения вариантов и значения QObject являются объектами, поэтому эта функция возвращает true для таких значений.

См. также QJSEngine::newObject().

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

Возвращает true, если этот QJSValue является QMetaObject; в противном случае возвращает false.

Эта функция была добавлена в Qt 5.8.

См. также toQMetaObject() и QJSEngine::newQMetaObject().

bool QJSValue::isQObject() const

Возвращает true, если этот QJSValue является QObject; в противном случае возвращает false.

Примечание: Эта функция возвращает true, даже если QObject, который оборачивает этот QJSValue, был удалён.

См. также toQObject() и QJSEngine::newQObject().

bool QJSValue::isRegExp() const

Возвращает true, если этот QJSValue является объектом класса RegExp; в противном случае возвращает false.

bool QJSValue::isString() const

Возвращает true, если этот QJSValue имеет примитивный тип String; в противном случае возвращает false.

См. также toString().

bool QJSValue::isUndefined() const

Возвращает true, если этот QJSValue имеет примитивный тип Undefined или если управляемое значение было очищено (удалением движка). В противном случае возвращает false.

bool QJSValue::isVariant() const

Возвращает true, если этот QJSValue является значением варианта; в противном случае возвращает false.

См. также toVariant().

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

Возвращает значение свойства этого QJSValue с заданным именем name. Если такого свойства не существует, возвращается неопределённый 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 не является объектом массива, эта функция ведёт себя так, как если бы функция setProperty() была вызвана со строковым представлением arrayIndex.

См. также property(quint32 arrayIndex) и Работа с массивами.

void QJSValue::setPrototype(const QJSValue &prototype)

Если этот QJSValue является объектом, устанавливает внутренний прототип (свойство __proto__ ) этого объекта на prototype; если QJSValue равен null, устанавливает прототип на null; в противном случае ничего не делает.

Внутренний прототип не следует путать с общедоступным свойством с именем «prototype»; общедоступный прототип обычно устанавливается только для функций, которые действуют как конструкторы.

См. также prototype() и isObject().

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

Возвращает true, если этот QJSValue равен other с использованием строгого сравнения (без преобразования), иначе возвращает false. Сравнение соответствует поведению, описанному в ECMA-262 разделе 11.9.6, «Алгоритм строгого сравнения».

Если тип этого QJSValue отличается от типа значения other, эта функция возвращает false. Если типы равны, результат зависит от типа, как показано в следующей таблице:

См. также equals().

bool QJSValue::toBool() const

Возвращает логическое значение этого QJSValue по правилам преобразования, описанным в ECMA-262 разделе 9.2, «ToBoolean».

Обратите внимание, что если этот QJSValue является объектом, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию valueOf() объекта (и, возможно, toString()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также isBool().

QDateTime QJSValue::toDateTime() const

Возвращает представление QDateTime этого значения в локальном времени. Если этот QJSValue не является датой или значение даты равно NaN (Not-a-Number), возвращается недопустимая QDateTime.

См. также isDate().

qint32 QJSValue::toInt() const

Возвращает значение целого числа со знаком 32-бита этого QJSValue, используя правила преобразования, описанные в ECMA-262 разделе 9.5, «ToInt32».

Обратите внимание, что если этот QJSValue является объектом, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию valueOf() объекта (и, возможно, toString()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также toNumber() и toUInt().

double QJSValue::toNumber() const

Возвращает числовое значение этого QJSValue, как определено в ECMA-262 разделе 9.3, «ToNumber».

Обратите внимание, что если этот QJSValue является объектом, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию valueOf() объекта (и, возможно, toString()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также isNumber(), toInt() и toUInt().

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

* Если этот QJSValue является QMetaObject, возвращает указатель на QMetaObject * который представляет QJSValue; в противном случае возвращает nullptr. * *

Эта функция была добавлена в Qt 5.8.

См. также isQMetaObject().

QObject *QJSValue::toQObject() const

Если этот QJSValue является QObject, возвращает указатель на QObject, который представляет QJSValue; в противном случае возвращает nullptr.

Если QObject, на который ссылается этот QJSValue, был удалён, эта функция возвращает nullptr (т. е. возможно, что toQObject() вернёт nullptr даже тогда, когда isQObject() возвращает true).

См. также isQObject().

QString QJSValue::toString() const

Возвращает строковое значение этого QJSValue, как определено в ECMA-262 разделе 9.8, «ToString».

Обратите внимание, что если этот QJSValue является объектом, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию toString() объекта (и, возможно, valueOf()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также isString().

quint32 QJSValue::toUInt() const

Возвращает значение беззнакового 32-битного целого числа этого QJSValue, используя правила преобразования, описанные в ECMA-262 разделе 9.6, «ToUint32».

Обратите внимание, что если этот QJSValue является объектом, вызов этой функции имеет побочные эффекты в движке сценариев, поскольку движок вызовет функцию valueOf() объекта (и, возможно, toString()), чтобы попытаться преобразовать объект в примитивное значение (что может привести к необработанному исключению сценария).

См. также toNumber() и toInt().

QVariant QJSValue::toVariant() const

Возвращает значение QVariant этого QJSValue, если оно может быть преобразовано в QVariant; в противном случае возвращает недействительный QVariant. Преобразование выполняется в соответствии со следующей таблицей:

См. также isVariant().