Класс QJSEngine

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

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

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

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

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

• 32 открытые функции, унаследованные от 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

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

[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 или на глобальный объект, если объект не указан.

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

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().