Класс QJSEngine

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

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

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

Типы public

Свойства

• uiLanguage : QString

Функции public

Сигналы

Статические public члены

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

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

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

Используйте 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;
}

Конфигурация движка

Функция 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()");

Примечание: В настоящее время поддерживаются только классы, использующие макрос Q_OBJECT; невозможно экспортировать staticMetaObject класса Q_GADGET в JavaScript.

Динамические свойства 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::Extensionфлаги QJSEngine::Extensions

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

TranslationExtension

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

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

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

ConsoleExtension

Объект 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())

Дополнительную информацию можно найти в документации по 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, он установит его в список "сообщений стека вызовов", если скрипт бросил необработанное исключение, или в пустой список в противном случае. Сообщение стека вызовов имеет формат имя_функции:номер_строки:номер_колонки:имя_файла

Примечание: В некоторых случаях, например, для нативных функций, имя функции и имя файла могут быть пустыми, а номер строки и колонки — -1.

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

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

Возвращает заданное value, преобразованное к типу шаблона T.

См. также 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(). Это означает, что несколько импортов одного и того же файла на диске с использованием разных относительных путей загрузят файл только один раз.

Примечание: Если во время загрузки модуля возникнет исключение, возвращаемое значение будет исключением (обычно объект Error; см. QJSValue::isError()).

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

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

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

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

Несколько расширений можно установить одновременно, OR-я значения перечисления:

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

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

См. также Extension.

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

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

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

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

QJSValue QJSEngine::newArray(uint length = 0)

Создаёт JavaScript-объект класса Array с заданной length.

См. также 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. QMetaObject должен существовать дольше, чем движок скрипта. Рекомендуется использовать только эту функцию со статическими метаобъектами.

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

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

См. также newQObject() и QObject Integration.

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

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

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

См. также newQObject() и QObject Integration.

QJSValue QJSEngine::newQObject(QObject *object)

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

Сигналы и слоты, свойства и дочерние элементы object доступны как свойства созданного QJSValue.

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

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

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

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

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

Возвращает владение object.

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

[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.

См. также 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.

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