Класс 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++ в среде выполнения.

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

Кроме того, файл проекта (.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() для всех типов, которые предоставляются плагином расширения QML.

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