Класс QJSValue

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

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

Публичные типы

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

Связанные нечлены

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

Класс 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().

Значения объектов имеют ноль или более свойств, которые сами являются QJSValue. Используйте 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.

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

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

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

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

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

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

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

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

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

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

QJSValue::QJSValue(const QJSValue &other)

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

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

QJSValue::QJSValue(QJSValue &&other)

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

QJSValue::QJSValue(bool value)

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

QJSValue::QJSValue(int value)

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

QJSValue::QJSValue(uint value)

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

QJSValue::QJSValue(double value)

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

QJSValue::QJSValue(const QString &value)

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

QJSValue::QJSValue(const QLatin1String &value)

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

QJSValue::QJSValue(const char *value)

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

QJSValue::~QJSValue()

Уничтожает этот QJSValue.

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

Вызывает этот QJSValue как функцию, передавая args в качестве аргументов функции и используя globalObject() в качестве объекта «this». Возвращает значение, возвращенное функцией.

Если этот QJSValue не является вызываемым, call() ничего не делает и возвращает неопределенный QJSValue.

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

См. также isCallable(), callWithInstance() и callAsConstructor().

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

Создает новый Object и вызывает этот QJSValue как конструктор, используя созданный объект в качестве объекта `this' и передавая args в качестве аргументов. Если возвращаемое значение от вызова конструктора является объектом, то этот объект возвращается; в противном случае возвращается объект по умолчанию.

Если этот QJSValue не является функцией, callAsConstructor() ничего не делает и возвращает неопределенный QJSValue.

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

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

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

Вызывает этот 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.

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

• Ненастраиваемые свойства удалить нельзя.
• Эта функция вернёт true даже если у этого объекта нет свойства с данным именем name (т.е. несуществующие свойства «тривиально удаляемы»).
• Если у этого объекта нет собственного свойства с данным именем 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 не является объектом Array, эта функция ведёт себя так, как будто вызывалась 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 не является объектом Array, эта функция ведет себя так, как будто была вызвана 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. Сравнение соответствует поведению, описанному в разделе 11.9.6 стандарта ECMA-262 «Алгоритм строгого сравнения».

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

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

bool QJSValue::toBool() const

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

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

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

QDateTime QJSValue::toDateTime() const

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

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

qint32 QJSValue::toInt() const

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

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

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

double QJSValue::toNumber() const

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

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

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

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, как определено в разделе 9.8 стандарта ECMA-262 «Преобразование в строку».

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

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

quint32 QJSValue::toUInt() const

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

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

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

QVariant QJSValue::toVariant() const

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

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

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

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

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

Присваивает значение other данному объекту QJSValue.

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