Класс QJSEngine

Класс QJSEngine предоставляет среду для оценки кода JavaScript. Подробнее...

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

Примечание: Все функции в этом классе являются реентерабельными.

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

Свойства

• uiLanguage : QString

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

Сигналы

Статические открытые члены

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

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

Оценивание скриптов

Используйте evaluate(), чтобы оценить скриптовый код.

QJSEngine myEngine;
QJSValue three = myEngine.evaluate("1 + 2");

evaluate() возвращает QJSValue, содержащую результат вычисления. Класс QJSValue предоставляет функции для преобразования результата в различные типы C++ (например, QJSValue::toString() и QJSValue::toNumber()).

Следующий фрагмент кода демонстрирует, как можно определить функцию скрипта и затем вызвать её из C++ с помощью QJSValue::call():

QJSValue fun = myEngine.evaluate("(function(a, b) { return a + b; })");
QJSValueList args;
args << 1 << 2;
QJSValue threeAgain = fun.call(args);

Как видно из приведенных фрагментов, скрипт предоставляется движку в виде строки. Один из распространённых способов загрузки скриптов — это чтение содержимого файла и передача его методу evaluate():

QString fileName = "helloworld.qs";
QFile scriptFile(fileName);
if (!scriptFile.open(QIODevice::ReadOnly))
    // handle error
QTextStream stream(&scriptFile);
QString contents = stream.readAll();
scriptFile.close();
myEngine.evaluate(contents, fileName);

Здесь мы передаём имя файла как второй аргумент методу evaluate(). Это никак не влияет на вычисление; второй аргумент — это строка общего назначения, хранящаяся в объекте Error для целей отладки.

Для более крупных функциональных блоков вы можете упаковать свой код и данные в модули. Модуль — это файл, содержащий скриптовый код, переменные и т. д., а также использующий операторы export для описания своего интерфейса для остальной части приложения. С помощью операторов import модуль может ссылаться на функциональность других модулей. Это позволяет строить скриптовое приложение из меньших взаимосвязанных строительных блоков безопасным способом. В отличие от подхода с использованием evaluate(), он несёт риск того, что внутренние переменные или функции одного вызова evaluate() случайно загрязнят глобальный объект и повлияют на последующие вычисления.

Следующий пример предоставляет модуль, который может складывать числа:

export function sum(left, right)
{
    return left + right
}

Этот модуль можно загрузить с помощью QJSEngine::import(), если он сохранён под именем math.mjs:

QJSvalue module = myEngine.importModule("./math.mjs");
QJSValue sumFunction = module.property("sum");
QJSValue result = sumFunction.call(args);

Модули также могут использовать функциональность других модулей с помощью операторов import:

import { sum } from "./math.mjs";
export function addTwice(left, right)
{
    return sum(left, right) * 2;
}

Модули не обязательно должны быть файлами. Они могут быть значениями, зарегистрированными с помощью QJSEngine::registerModule():

import version from "version";

export function getVersion()
{
    return version;
}

QJSValue version(610);
myEngine.registerModule("version", version);
QJSValue module = myEngine.importModule("./myprint.mjs");
QJSValue getVersion = module.property("getVersion");
QJSValue result = getVersion.call();

Поддерживаются именованные экспорты, но поскольку они обрабатываются как члены объекта, экспорт по умолчанию должен быть объектом ECMAScript. Большинство функций newXYZ в QJSValue вернут объект.

QJSValue name("Qt6");
QJSValue obj = myEngine.newObject();
obj.setProperty("name", name);
myEngine.registerModule("info", obj);

import { name } from "info";

export function getName()
{
    return name;
}

Настройка движка

Функция globalObject() возвращает глобальный объект, связанный с движком сценариев. Свойства глобального объекта доступны из любого кода сценария (то есть они являются глобальными переменными). Обычно, перед оценкой «пользовательских» сценариев, вы захотите настроить движок сценариев, добавив одну или несколько свойств в глобальный объект:

myEngine.globalObject().setProperty("myNumber", 123);
...
QJSValue myNumberPlusOne = myEngine.evaluate("myNumber + 1");

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

Исключения сценариев

evaluate() может вызывать исключение сценария (например, из-за синтаксической ошибки). Если это произойдёт, то evaluate() возвращает значение, которое было выброшено (обычно объект Error). Используйте QJSValue::isError(), чтобы проверить наличие исключений.

Для получения подробной информации об ошибке используйте QJSValue::toString() для получения сообщения об ошибке и QJSValue::property() для запроса свойств объекта Error. Доступны следующие свойства:

• name
• message
• fileName
• lineNumber
• stack

QJSValue result = myEngine.evaluate(...);
if (result.isError())
    qDebug()
            << "Uncaught exception at line"
            << result.property("lineNumber").toInt()
            << ":" << result.toString();

Создание объектов сценария

Используйте newObject() для создания объекта JavaScript; это эквивалент оператора сценария new Object() в C++. Вы можете использовать функции, специфичные для объекта, в QJSValue для работы с объектом сценария (например, QJSValue::setProperty()). Аналогично, используйте newArray() для создания объекта массива JavaScript.

Интеграция QObject

Используйте newQObject() для обертывания указателя на QObject (или подкласс). newQObject() возвращает прокси-объект сценария; свойства, дочерние объекты, сигналы и слоты QObject доступны в качестве свойств прокси-объекта. Код привязки не нужен, так как он динамически генерируется с помощью системы метаобъектов Qt.

QPushButton *button = new QPushButton;
QJSValue scriptButton = myEngine.newQObject(button);
myEngine.globalObject().setProperty("button", scriptButton);

myEngine.evaluate("button.checkable = true");

qDebug() << scriptButton.property("checkable").toBool();
scriptButton.property("show").call(); // call the show() slot

Используйте newQMetaObject() для обертывания QMetaObject; это даёт вам «представление сценария» класса, основанного на QObject. newQMetaObject() возвращает прокси-объект сценария; значения перечислений класса доступны в качестве свойств прокси-объекта.

Конструкторы, экспонированные в системе метаобъектов (с использованием Q_INVOKABLE), могут вызываться из сценария для создания нового экземпляра QObject с JavaScriptOwnership. Например, приведённое ниже определение класса:

class MyObject : public QObject
{
    Q_OBJECT

public:
    Q_INVOKABLE MyObject() {}
};

staticMetaObject класса может быть экспонирован в JavaScript следующим образом:

QJSValue jsMetaObject = engine.newQMetaObject(&MyObject::staticMetaObject);
engine.globalObject().setProperty("MyObject", jsMetaObject);

Экземпляры класса затем могут быть созданы в JavaScript:

engine.evaluate("var myObject = new MyObject()");

Динамические свойства QObject

Динамические свойства QObject не поддерживаются. Например, следующий код работать не будет:

QJSEngine engine;

QObject *myQObject = new QObject();
myQObject->setProperty("dynamicProperty", 3);

QJSValue myScriptQObject = engine.newQObject(myQObject);
engine.globalObject().setProperty("myObject", myScriptQObject);

qDebug() << engine.evaluate("myObject.dynamicProperty").toInt();

Расширения

QJSEngine предоставляет совместимую реализацию ECMAScript. По умолчанию такие привычные утилиты, как регистрация, недоступны, но их можно установить с помощью функции installExtensions().

См. также QJSValue, Делаем приложения исполняемыми сценариями и Список объектов и функций JavaScript.

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

перечисление QJSEngine::Extensionflags QJSEngine::Extensions

Это перечисление используется для указания расширений, которые необходимо установить с помощью installExtensions().

TranslationExtension

Взаимосвязь между функциями перевода сценария и функциями перевода C++ описывается в следующей таблице:

Этот флаг также добавляет функцию arg() к прототипу строки.

Дополнительную информацию см. в документации по Международной локализации с Qt.

ConsoleExtension

Объект console реализует подмножество Console API, предоставляя знакомые функции регистрации, такие как console.log().

Список добавленных функций:

• console.assert()
• console.debug()
• console.exception()
• console.info()
• console.log() (эквивалент console.debug())
• console.error()
• console.time()
• console.timeEnd()
• console.trace()
• console.count()
• console.warn()
• print() (эквивалент console.debug())

Дополнительную информацию см. в документации по Console API.

GarbageCollectionExtension

Функция gc() эквивалентна вызову collectGarbage().

Тип Extensions является псевдонимом для QFlags<Extension>. Он хранит логическое ИЛИ значений Extension.

перечисление QJSEngine::ObjectOwnership

ObjectOwnership управляет тем, уничтожает ли менеджер памяти JavaScript объект QObject автоматически при сборе мусора соответствующего объекта JavaScript движком. Два варианта владения:

Как правило, приложению не нужно явно устанавливать владение объектом. Менеджер памяти JavaScript использует эвристику для установки значения по умолчанию. По умолчанию объект, созданный менеджером памяти JavaScript, имеет JavaScriptOwnership. Исключение составляют корневые объекты, созданные путём вызова QQmlComponent::create() или QQmlComponent::beginCreate(), которые по умолчанию имеют CppOwnership. Владение этими корневыми объектами считается переданным вызывающему коду C++.

Объекты, не созданные менеджером памяти JavaScript, по умолчанию имеют CppOwnership. Исключение составляют объекты, возвращённые из вызовов методов C++; их владение будет установлено в JavaScriptOwnership. Это применяется только к явным вызовам методов или слотов Q_INVOKABLE, но не к вызовам свойств-получателей.

Вызов setObjectOwnership() переопределяет владение по умолчанию.

См. также Владение данными.

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

QJSEngine::QJSEngine(QObject *parent)

Создаёт объект QJSEngine с заданным parent.

globalObject() инициализируется свойствами, описанными в ECMA-262, раздел 15.1.

QJSEngine::QJSEngine()

Создаёт объект QJSEngine.

globalObject() инициализируется свойствами, описанными в ECMA-262, раздел 15.1.

[override virtual] QJSEngine::~QJSEngine()

Уничтожает этот QJSEngine.

Мусор с постоянной кучи JS не собирается во время уничтожения QJSEngine. Если вам необходимо освободить всю память, вызовите collectGarbage вручную непосредственно перед уничтожением QJSEngine.

[since Qt 6.1] QJSValue QJSEngine::catchError()

Если ожидается исключение, ловит его и возвращает его как QJSValue. В противном случае возвращает undefined как QJSValue. После вызова этого метода hasError() возвращает false.

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

void QJSEngine::collectGarbage()

Выполняет сборщик мусора.

Сборщик мусора попытается освободить память, обнаружив и удалив объекты, которые больше не достижимы в среде сценария.

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

QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)

Вычисляет program, используя lineNumber в качестве базового номера строки и возвращает результат вычисления.

Код сценария будет вычислен в контексте глобального объекта.

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

lineNumber используется для указания начального номера строки для program; информация о номере строки, предоставляемая движком, относящаяся к этому вычислению, будет основана на этом аргументе. Например, если program состоит из двух строк кода, и оператор на второй строке вызывает исключение сценария, номер строки исключения будет lineNumber плюс один. Если начальный номер строки не указан, номера строк будут основаны на 1.

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

exceptionStackTrace используется для отчёта об неперехваченных исключениях. Если вы передаёте ненулевой указатель на QStringList в него, он установит его на список сообщений "кадра стека", если сценарий бросил необработанное исключение, или на пустой список в противном случае. Сообщение кадра стека имеет формат имя функции:номер строки:колонка:имя файла

template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)

Возвращает заданное value, преобразованное к шаблону типа T. Это работает с любым типом T, у которого есть QMetaType.

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

QJSValue QJSEngine::globalObject() const

Возвращает глобальный объект данного движка.

По умолчанию глобальный объект содержит встроенные объекты, которые являются частью ECMA-262, такие как Math, Date и String. Кроме того, вы можете установить свойства глобального объекта, чтобы сделать свои собственные расширения доступными для всего кода сценария. Нелокальные переменные в коде сценария будут созданы как свойства глобального объекта, а также локальные переменные в глобальном коде.

[since Qt 6.1] bool QJSEngine::hasError() const

Возвращает true если последнее выполнение JavaScript привело к исключению или если была вызвана throwError(). В противном случае возвращает false. Имейте в виду, что evaluate() перехватывает любые исключения, сгенерированные в вычисляемом коде.

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

[since 5.12] QJSValue QJSEngine::importModule(const QString &fileName)

Импортирует модуль, расположенный в fileName, и возвращает объект пространства имён модуля, который содержит все экспортированные переменные, константы и функции в качестве свойств.

Если модуль импортируется в движок впервые, файл загружается из указанного расположения в локальной файловой системе или системе ресурсов Qt и вычисляется как модуль ECMAScript. Ожидается, что файл будет закодирован в UTF-8.

Последующие импорты того же модуля вернут ранее импортированный экземпляр. Модули являются синглтонами и остаются до тех пор, пока движок не будет уничтожен.

Указанное fileName будет внутренне нормализовано с помощью QFileInfo::canonicalFilePath(). Это означает, что несколько импортов одного и того же файла на диске с использованием разных относительных путей загрузит файл только один раз.

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

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

[since 5.6] void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

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

Расширения устанавливаются на заданный object или на глобальный объект, если объект не указан.

Несколько расширений могут быть установлены одновременно путём объединения значений перечисления:

installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);

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

См. также Extension.

[since 5.14] bool QJSEngine::isInterrupted() const

Возвращает значение true, если выполнение JavaScript в данный момент прервано.

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

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

QJSValue QJSEngine::newArray(uint length = 0)

Создаёт JavaScript-объект типа Массив с заданной длиной.

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

[since 5.12] QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())

Создаёт JavaScript-объект типа Error с message в качестве сообщения об ошибке.

Прототипом созданного объекта будет errorType.

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

См. также newObject(), throwError() и QJSValue::isError().

QJSValue QJSEngine::newObject()

Создаёт объект JavaScript класса Object.

Прототипом созданного объекта будет объект-прототип Object.

См. также newArray() и QJSValue::setProperty().

[since 5.8] QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

Создаёт объект JavaScript, оборачивающий данный QMetaObject. metaObject должен существовать дольше, чем движок сценариев. Рекомендуется использовать только со статическими метаобъектами.

При вызове в качестве конструктора будет создан новый экземпляр класса. Из движка сценариев будут видны только конструкторы, экспонированные с помощью Q_INVOKABLE.

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

См. также newQObject() и Интеграция QObject.

[since 5.8] template <typename T> QJSValue QJSEngine::newQMetaObject()

Создаёт объект JavaScript, оборачивающий статический QMetaObject, связанный с классом T.

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

См. также newQObject() и Интеграция QObject.

QJSValue QJSEngine::newQObject(QObject *object)

Создаёт объект JavaScript, оборачивающий данный QObject object, используя JavaScriptOwnership.

Сигналы и слоты, свойства и дети объекта object доступны как свойства созданного QJSValue.

Если object — нулевой указатель, эта функция возвращает нулевое значение.

Если для класса object (или его предков, рекурсивно) зарегистрирован прототип по умолчанию, прототип нового объекта сценария будет установлен на этот прототип по умолчанию.

Если заданный object удаляется вне управления движком, любая попытка обратиться к удалённым членам QObject через оболочку объекта JavaScript (как кодом сценария, так и на C++) приведёт к исключению сценария.

См. также QJSValue::toQObject().

[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)

Создаёт объект JavaScript класса Symbol со значением name.

Прототипом созданного объекта будет объект-прототип Symbol.

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

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

[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)

Возвращает тип владения объектом object.

См. также setObjectOwnership() и QJSEngine::ObjectOwnership.

bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)

Регистрирует QJSValue в качестве модуля. После вызова этой функции все модули, импортирующие moduleName, импортируют значение value вместо загрузки moduleName из файла.

Можно зарегистрировать любое допустимое QJSValue, но именованные экспорты (т.е. import { name } from "info") обрабатываются как члены объекта, поэтому экспорт по умолчанию должен быть создан с помощью одного из методов newXYZ класса QJSEngine.

Поскольку это позволяет импортировать модули, которых нет в файловой системе, приложения сценариев могут использовать это для предоставления встроенных модулей, аналогично Node.js.

Возвращает true при успехе, false в противном случае.

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

[since 5.14] void QJSEngine::setInterrupted(bool interrupted)

Прерывает или возобновляет выполнение JavaScript.

Если interrupted равно true, любое выполнение JavaScript этим движком немедленно прерывается и возвращает объект ошибки, пока эта функция не будет снова вызвана со значением false для interrupted.

Эта функция потокобезопасна. Вы можете вызвать её из другого потока, чтобы прервать, например, бесконечный цикл в JavaScript.

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

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

[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)

Устанавливает тип владения объектом object.

Объект с JavaScriptOwnership не собирается сборщиком мусора до тех пор, пока у него есть родитель, даже если на него нет ссылок.

См. также objectOwnership() и QJSEngine::ObjectOwnership.

[since Qt 5.12] void QJSEngine::throwError(const QString &message)

Выбрасывает ошибку выполнения (исключение) с заданным сообщением message.

Этот метод является C++ аналогом выражения throw() в JavaScript. Он позволяет коду C++ сообщать об ошибках выполнения движку QJSEngine. Поэтому его следует вызывать только из кода C++, вызванного функцией JavaScript через QJSEngine.

При возвращении из C++, движок прервёт нормальный поток выполнения и вызовет следующий зарегистрированный обработчик исключений с объектом ошибки, содержащим заданное сообщение message. Объект ошибки будет указывать на расположение самого верхнего контекста в стеке вызова JavaScript; конкретно, он будет иметь свойства lineNumber, fileName и stack. Эти свойства описаны в Исключения сценария.

В следующем примере метод C++ в FileAccess.cpp выбрасывает ошибку в qmlFile.qml в позиции, где вызывается readFileAsText().

// qmlFile.qml
function someFunction() {
  ...
  var text = FileAccess.readFileAsText("/path/to/file.txt");
}

// FileAccess.cpp
// Assuming that FileAccess is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// readFileAsText()

QJSValue FileAccess::readFileAsText(const QString & filePath) {
  QFile file(filePath);

  if (!file.open(QIODevice::ReadOnly)) {
    jsEngine->throwError(file.errorString());
    return QString();
  }

  ...
  return content;
}

Также возможно перехватить выброшенную ошибку в JavaScript:

// qmlFile.qml
function someFunction() {
  ...
  var text;
  try {
    text = FileAccess.readFileAsText("/path/to/file.txt");
  } catch (error) {
    console.warn("In " + error.fileName + ":" + "error.lineNumber" +
                 ": " + error.message);
  }
}

Если вам нужна более специфическая ошибка выполнения для описания исключения, вы можете использовать перегрузку throwError(QJSValue::ErrorType errorType, const QString &message).

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

См. также Исключения сценария.

[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())

Эта функция перегружает throwError().

Выбрасывает ошибку выполнения (исключение) с заданным errorType и message.

// Assuming that DataEntry is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// setAge().

void DataEntry::setAge(int age) {
  if (age < 0 || age > 200) {
    jsEngine->throwError(QJSValue::RangeError,
                         "Age must be between 0 and 200");
  }
  ...
}

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

См. также Исключения сценария и newErrorObject().

[since 6.1] void QJSEngine::throwError(const QJSValue &error)

Эта функция перегружает throwError().

Выбрасывает предварительно сконструированную ошибку выполнения error (исключение). Таким образом, вы можете использовать newErrorObject() для создания ошибки и настройки её по мере необходимости.

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

См. также Исключения сценария и newErrorObject().

template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)

Создаёт QJSValue с заданным значением value. Это работает с любым типом T, который имеет QMetaType.

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