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

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

• Ненастраиваемые свойства удалить нельзя.
• Эта функция вернет 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 не является объектом массива, эта функция ведет себя так, как если бы была вызвана 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. Сравнение следует поведению, описанному в разделе 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

Возвращает представление этого значения в виде 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().