Класс QJSEngine

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

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

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

Типы публичного доступа

Публичные функции

• 34 публичные функции, унаследованные от QObject

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

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 публичный слот, унаследованный от QObject
• 2 сигнала, унаследованные от QObject
• 1 публичная переменная, унаследованная от QObject
• 10 статические публичные члены, унаследованные от QObject
• 9 защищенные функции, унаследованные от QObject
• 2 защищенные переменные, унаследованные от QObject

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

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

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

Используйте 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 для целей отладки.

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

Функция 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(). Вы можете использовать функциональность, специфичную для объекта, в 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 — это typedef для QFlags<Extension>. Он хранит результат логического ИЛИ значений Extension.

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

QJSEngine::QJSEngine()

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

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

QJSEngine::QJSEngine(QObject *parent)

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

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

[override virtual] QJSEngine::~QJSEngine()

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

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

void QJSEngine::collectGarbage()

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

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

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

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

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

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

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

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

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

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

T QJSEngine::fromScriptValue(const QJSValue &value)

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

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

QJSValue QJSEngine::globalObject() const

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

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

void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

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

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

Несколько расширений можно установить одновременно, используя битовую операцию ИЛИ над значениями перечисления:

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

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

См. также Extension.

QJSValue QJSEngine::newArray(uint length = 0)

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

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

QJSValue QJSEngine::newObject()

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

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

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

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

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

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

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

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

QJSValue QJSEngine::newQMetaObject()

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

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

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

QJSValue QJSEngine::newQObject(QObject *object)

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

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

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

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

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

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

QJSValue QJSEngine::toScriptValue(const T &value)

Создаёт QJSValue со заданным значением value.

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