Класс QJSEngine

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

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

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

Типы общего доступа

Функции общего доступа

• 31 функция общего доступа унаследованная от QObject

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

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

• 1 свойство унаследованное от QObject
• 1 публичный слот унаследованный от QObject
• 2 сигналы унаследованные от QObject
• 11 статические публичные члены унаследованные от QObject
• 9 защищенные функции унаследованные от 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(QJSValue(), 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

Расширения

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

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

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

перечисление QJSEngine::Extensionфлаги QJSEngine::Расширения

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

РасширениеПеревода

Взаимосвязь между функциями перевода скриптов и функциями перевода 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::QJSEngine()

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

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

QJSEngine::QJSEngine(QObject *parent)

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

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

[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(Extensions extensions, const QJSValue &object = QJSValue())

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

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

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

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::newQObject(QObject *object)

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

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

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

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

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

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

QJSValue QJSEngine::toScriptValue(const T &value)

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

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