Класс 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-специфических ошибок.

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

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

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

Это перечисление используется для указания того, как объекты JavaScript без эквивалентного типа Qt должны обрабатываться при преобразовании в QVariant.

перечисление 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 не является объектом, в качестве объекта `this` будет использован глобальный объект (см. QJSEngine::globalObject()).

Вызов call() может вызвать исключение в движке сценариев; в этом случае call() возвращает значение, которое было выброшено (обычно объект Error). Вы можете вызвать isError() на возвращаемом значении, чтобы определить, произошла ли ошибка.

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

bool QJSValue::deleteProperty(const QString &name)

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

Поведение этой функции соответствует оператору JavaScript delete. В частности:

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

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

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

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

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

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

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

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.

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

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

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 является значением variant; иначе возвращает 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().

QJSPrimitiveValue QJSValue::toPrimitive() const

Преобразует значение в QJSPrimitiveValue. Если значение содержит тип, поддерживаемый QJSPrimitiveValue, значение копируется. В противном случае значение преобразуется в строку, и строка хранится в QJSPrimitiveValue.

Примечание: Преобразование управляемого значения в строку может вызвать исключение. В частности, символы не могут быть преобразованы в строки, или пользовательский метод toString() может выбросить исключение. В этом случае результатом является неопределённое значение, и движок содержит ошибку после преобразования.

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, используя правила преобразования, описанные в разделе 9.6 стандарта ECMA-262 «ToUint32».

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

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

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

Возвращает значение QVariant этого QJSValue, если его можно преобразовать в QVariant; в противном случае возвращает недействительный QVariant. Некоторые типы и объекты JavaScript имеют родные выражения в Qt. Они преобразуются в их родные выражения. Например:

Для других типов параметр behavior имеет значение. Если задано ConvertJSObjects, производится преобразование с лучшими усилиями, но, возможно, с потерями. Общие объекты JavaScript преобразуются в QVariantMap. Массивы JavaScript преобразуются в QVariantList. Каждая свойство или элемент преобразуется в QVariant рекурсивно; циклические ссылки не отслеживаются. Объекты функций JavaScript отбрасываются. Если задано RetainJSObjects, QJSValue обертывается в QVariant с помощью QVariant::fromValue(). Полученное преобразование является без потерь, но внутренняя структура объектов не сразу доступна.

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

QVariant QJSValue::toVariant() const

Это перегруженная функция.

Возвращает toVariant(ConvertJSObjects).

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