Класс QQmlEngineExtensionPlugin

Класс QQmlEngineExtensionPlugin предоставляет абстрактный базовый класс для пользовательских плагинов расширения QML. Подробнее...

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

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

Переопределённые открытые функции

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

QQmlEngineExtensionPlugin — это интерфейс плагина, который позволяет создавать расширения QML, которые могут динамически загружаться в приложения QML. Эти расширения позволяют предоставлять доступ к пользовательским типам QML для движка QML.

Для написания плагина расширения QML:

1. Унаследуйте от QQmlEngineExtensionPlugin и используйте макрос Q_PLUGIN_METADATA(), чтобы зарегистрировать плагин в системе метаобъектов Qt.
2. Используйте макросы QML_ELEMENT и QML_NAMED_ELEMENT(), чтобы объявить типы QML.
3. Напишите файл проекта для плагина. Добавьте:
   • CONFIG += qmltypes для указания системе сборки генерировать типы QML.
   • QML_IMPORT_NAME = <my.import.name> для указания имени импорта.
   • QML_IMPORT_MAJOR_VERSION = <version> для указания основной версии импорта.
4. Создайте файл qmldir для описания плагина.

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

Компилятор может ошибочно удалить сгенерированную функцию регистрации типов как оптимизацию. Вы можете предотвратить это, объявив синтетический непостоянный указатель на функцию где-нибудь в вашем коде. Если ваш модуль называется "my.module", вы добавите объявление в глобальной области видимости:

void qml_register_types_my_module();

Затем добавьте следующий фрагмент кода в реализацию любой функции, которая является частью того же двоичного файла, что и регистрация:

volatile auto registration = &qml_register_types_my_module;
Q_UNUSED(registration);

Плагин расширения TimeExample QML

Предположим, есть новый TimeModel класс C++, который должен быть доступен как новый тип QML. Он предоставляет текущее время через hour и minute свойства. Он объявляет тип QML Time с помощью QML_NAMED_ELEMENT().

class TimeModel : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int hour READ hour NOTIFY timeChanged)
    Q_PROPERTY(int minute READ minute NOTIFY timeChanged)
    QML_NAMED_ELEMENT(Time)
    ...

Чтобы сделать этот тип доступным, мы создаём класс плагина под названием QExampleQmlPlugin, который является подклассом QQmlEngineExtensionPlugin. Он использует макрос Q_PLUGIN_METADATA() в определении класса, чтобы зарегистрировать плагин в системе метаобъектов Qt с помощью уникального идентификатора для плагина.

class QExampleQmlPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
};

Настройки проекта для плагина

Кроме того, файл проекта (.pro) определяет проект как библиотеку плагинов, указывает, что он должен быть скомпилирован в каталог imports/TimeExample, и регистрирует имя целевого плагина, а также другие детали:

TEMPLATE = lib
CONFIG += qt plugin qmltypes
QT += qml

QML_IMPORT_NAME = TimeExample
QML_IMPORT_MAJOR_VERSION = 1

DESTDIR = imports/$$QML_IMPORT_NAME
TARGET  = qmlqtimeexampleplugin

SOURCES += qexampleqmlplugin.cpp

Это регистрирует класс TimeModel с импортом TimeExample 1.0, как тип QML под названием Time. Статья Определение типов QML из C++ содержит дополнительную информацию о регистрации типов C++ для использования в QML.

Определение плагина в qmldir

Наконец, требуется файл qmldir в каталоге imports/TimeExample для описания плагина и типов, которые он экспортирует. Плагин включает файл Clock.qml наряду с файлом qmlqtimeexampleplugin, который создаётся проектом (как показано выше в файле .pro). Поэтому оба этих файла должны быть указаны в файле qmldir:

module TimeExample
Clock 1.0 Clock.qml
plugin qmlqtimeexampleplugin

Для упрощения примера, директория исходного кода TimeExample находится в imports/TimeExample, и мы собираем его в исходном коде. Однако структура директории исходного кода не так важна, поскольку файл qmldir может указывать пути к установленным файлам QML.

Важно имя каталога, в который устанавливается qmldir. Когда пользователь импортирует наш модуль, движок QML использует идентификатор модуля (TimeExample) для поиска плагина, и поэтому каталог, в котором он установлен, должен соответствовать идентификатору модуля.

После сборки и установки проекта новый компонент Time доступен любому компоненту QML, который импортирует модуль TimeExample.

import TimeExample 1.0 // import types from the plugin

Clock { // this class is defined in QML (imports/TimeExample/Clock.qml)

    Time { // this class is defined in C++ (plugin.cpp)
        id: time
    }

    hours: time.hour
    minutes: time.minute

}

Полный исходный код доступен в примере плагинов.

В руководстве Написание расширений QML с помощью C++ также есть глава о создании плагинов QML.

См. также QQmlEngine::importPlugin() и Как создать плагины Qt.

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

QQmlEngineExtensionPlugin::QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Конструктор плагина расширения QML с указанным parent.

Обратите внимание, что этот конструктор вызывается автоматически макросом Q_PLUGIN_METADATA(), поэтому нет необходимости вызывать его явно.

[override virtual] void QQmlEngineExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)

Инициализирует расширение из uri с помощью engine. Здесь плагин приложения может, например, экспонировать данные или объекты в QML в качестве свойств контекста в корневом контексте движка.