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

Для сравнения QJSValue с другим значением используйте equals() или strictlyEquals().

Обратите внимание, что 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.

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

• Неизменяемые свойства удалить нельзя.
• Функция вернёт true даже если у этого объекта нет свойства с заданным именем name (т.е. несуществующие свойства "тривиально удаляемы").
• Если у этого объекта нет собственного свойства с заданным именем name, но оно есть в цепочке прототипов, свойство объекта прототипа не удаляется, и эта функция возвращает 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().

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

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::isUrl() const

Возвращает true, если этот QJSValue является объектом класса URL; в противном случае возвращает 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 не является объектом 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. Сравнение следует поведению, описанному в 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.

const QMetaObject *QJSValue::toQMetaObject() const

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

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

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

QObject *QJSValue::toQObject() const

Если этот QJSValue представляет QObject, возвращает указатель на QObject; в противном случае возвращает 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(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().