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

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

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

enum QJSValue::SpecialValue

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

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

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(QV4::ExecutionEngine *e, quint64 val)

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

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

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

bool QJSValue::deleteProperty(const QString &name)

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

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

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

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

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

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

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

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

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

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 является объектом класса Массив; в противном случае возвращает 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 является объектом класса Дата; в противном случае возвращает false.

bool QJSValue::isError() const

Возвращает true, если этот QJSValue является объектом класса Ошибка; в противном случае возвращает false.

См. также QJSEngine - Ошибки сценариев.

bool QJSValue::isNull() const

Возвращает true, если этот QJSValue является примитивного типа Null; в противном случае возвращает false.

bool QJSValue::isNumber() const

Возвращает true, если этот QJSValue является примитивного типа Число; в противном случае возвращает false.

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

bool QJSValue::isObject() const

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

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

bool QJSValue::isUndefined() const

Возвращает true, если этот QJSValue является примитивного типа Неопределённое; в противном случае возвращает 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 не является объектом Массив, эта функция ведёт себя так, как будто вызвана 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; в противном случае возвращает 0. * *

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

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

QObject *QJSValue::toQObject() const

Если этот QJSValue представляет QObject, возвращает указатель на QObject, представленный QJSValue; в противном случае возвращает 0.

Если QObject, оборачиваемый этим QJSValue, был удалён, функция возвращает 0 (т. е. возможно, что toQObject() вернёт 0, даже когда 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().

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

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

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

Присваивает значение other этому QJSValue.

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