Класс QQmlExtensionPlugin

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

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

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

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

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

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

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

Чтобы написать плагин расширения QML:

1. Подклассируйте QQmlExtensionPlugin
   • Используйте макрос Q_PLUGIN_METADATA() для регистрации плагина в системе метаобъектов Qt
   • Переопределите метод registerTypes() и вызовите qmlRegisterType(), чтобы зарегистрировать типы, которые экспортирует плагин
2. Напишите файл проекта для плагина
3. Создайте файл qmldir для описания плагина

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

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

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

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

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

class QExampleQmlPlugin : public QQmlExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlExtensionInterface_iid)

public:
    void registerTypes(const char *uri) override
    {
        Q_ASSERT(uri == QLatin1String("TimeExample"));
        qmlRegisterType<TimeModel>(uri, 1, 0, "Time");
    }
};

Это регистрирует класс TimeModel с версией 1.0 этой библиотеки плагинов как тип QML с именем Time. Макрос Q_ASSERT() может гарантировать, что пространство имён типа импортировано правильно всеми компонентами QML, которые используют этот плагин. В статье Определение типов QML из C++ содержится более подробная информация о регистрации типов C++ в runtime.

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

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

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

DESTDIR = imports/TimeExample
TARGET = qmlqtimeexampleplugin
SOURCES += qexampleqmlplugin.cpp

Определение плагина в файле 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.

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

QQmlExtensionPlugin::QQmlExtensionPlugin(QObject *parent = nullptr)

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

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

QUrl QQmlExtensionPlugin::baseUrl() const

Возвращает URL-адрес каталога, из которого загружается расширение.

Это полезно, когда плагин также должен загружать файлы QML или другие ресурсы из того же каталога.

Эта функция была представлена в Qt 5.1.

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

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

[override pure virtual] void QQmlExtensionPlugin::registerTypes(const char *uri)

Регистрирует типы QML в заданном uri. Подклассы должны реализовать это, чтобы вызвать qmlRegisterType() для всех типов, предоставляемых плагином расширения.

uri — это идентификатор плагина, сгенерированный движком QML на основе имени и пути к библиотеке плагина расширения.