Класс 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() возвращает 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::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.

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

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

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

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

QObject *QJSValue::toQObject() const

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