Класс QJSValue

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

Этот класс был введен в Qt 5.0.

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

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

Открытые функции

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

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

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.

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

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

Используйте это перечисление для типов ошибок, специфичных для языка JavaScript.

Они могут быть полезны, когда эмуляция функций языка в 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())

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

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

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

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

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

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

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

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

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

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

Вызывает этот 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, но есть в цепочке прототипов, свойство объекта прототипа не удаляется, и функция возвращает 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, "The Strict Equality Comparison Algorithm".

Если тип этого 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().

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().