Класс QQmlEngineExtensionPlugin

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

Этот класс был представлен в Qt 5.14.

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

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

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

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

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

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

void qml_register_types_my_module();
\code

Then add the following snippet of code in the implementation of any function
that's part of the same binary as the registration:

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

\section1 TimeExample QML extension plugin

Suppose there is a new \c TimeModel C++ class that should be made available
as a new QML type. It provides the current time through \c hour and \c minute
properties. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT().

\snippet qmlextensionplugins/timemodel.h 0
\dots

To make this type available, we create a plugin class named \c QExampleQmlPlugin
which is a subclass of \l QQmlEngineExtensionPlugin. It uses the
Q_PLUGIN_METADATA() macro in the class definition to register the plugin with the
Qt meta object system using a unique identifier for the plugin.

\snippet qmlextensionplugins/plugin.cpp plugin

\section1 Project settings for the plugin

Additionally, the project file (\c .pro) defines the project as a plugin library,
specifies it should be built into the \c imports/TimeExample directory, and registers
the plugin target name and various other details:

\code
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

Наконец, в каталоге imports/TimeExample требуется файл qmldir для описания плагина и типов, которые он экспортирует. Плагин включает файл 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, как свойства контекста в корневом контексте движка.