如何创建 Qt 插件

Qt 为创建插件提供了 2 个 API：

A high-level API for writing extensions to Qt itself, such as custom database drivers, image formats, text codecs, and custom styles.
用于扩展 Qt 应用程序的低级 API。

例如：若想要编写自定义 QStyle 子类并让 Qt 应用程序动态加载它，将使用更高级 API。

由于更高级 API 建立在更低级 API 之上，因此有一些问题是两者公共的。

If you want to provide plugins for use with Qt Designer, see Creating Custom Widget Plugins .

高级 API：编写 Qt 扩展

编写扩展 Qt 本身的插件是通过子类化适当插件基类、实现一些函数、及添加宏达成的。

有几个插件基类。默认情况下，派生插件存储在标准插件目录的子目录下。Qt 将找不到插件，若未将它们存储在适当目录下。

下表汇总了插件基类。某些类是私有的，因此未文档化。可以使用它们，但不承诺兼容更高 Qt 版本。

基类	目录名	Qt 模块	键区分大小写
QAccessibleBridgePlugin	`accessiblebridge`	Qt GUI	区分大小写
QImageIOPlugin	`imageformats`	Qt GUI	区分大小写
QPictureFormatPlugin (obsolete)	`pictureformats`	Qt GUI	区分大小写
QBearerEnginePlugin	`bearer`	Qt Network	区分大小写
QPlatformInputContextPlugin	`platforminputcontexts`	Qt Platform Abstraction	不区分大小写
QPlatformIntegrationPlugin	`platforms`	Qt Platform Abstraction	不区分大小写
QPlatformThemePlugin	`platformthemes`	Qt Platform Abstraction	不区分大小写
QPlatformPrinterSupportPlugin	`printsupport`	Qt Print Support	不区分大小写
QSGContextPlugin	`scenegraph`	Qt Quick	区分大小写
QSqlDriverPlugin	`sqldrivers`	Qt SQL	区分大小写
QIconEnginePlugin	`iconengines`	Qt SVG	不区分大小写
QAccessiblePlugin	`accessible`	Qt Widgets	区分大小写
QStylePlugin	`styles`	Qt Widgets	不区分大小写

若有新样式类称为 MyStyle 想要将其用作插件，则需要按以下方式定义类 ( mystyleplugin.h ):

class MyStylePlugin : public QStylePlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QStyleFactoryInterface" FILE "mystyleplugin.json")
public:
    QStyle *create(const QString &key);
};

确保类实现位于 .cpp 文件：

#include "mystyleplugin.h"
QStyle *MyStylePlugin::create(const QString &key)
{
    if (key.toLower() == "mystyle")
        return new MyStyle;
    return 0;
}

(注意， QStylePlugin 不区分大小写，且小写键版本可用于我们的 create () implementation; most other plugins are case sensitive.)

此外，JSON 文件 ( mystyleplugin.json ) 包含大多数插件所需的插件描述元数据。对于样式插件，它仅仅包含可以由插件创建的样式列表：

{ "Keys": [ "mystyleplugin" ] }

The type of information that needs to be provided in the json file is plugin dependent. See the class documentation for details on the information that needs to be contained in the file.

对于数据库驱动程序、图像格式、文本编解码器及大多数其它插件类型，明确创建对象不是必需的。Qt 将根据需要查找并创建它们。样式例外，由于可能想要在代码中明确设置样式。要应用样式，使用代码像这样：

QApplication::setStyle(QStyleFactory::create("MyStyle"));

某些插件类要求实现其它功能。见类文档编制，了解各插件类型必须重实现的虚函数的有关细节。

The 样式插件范例 shows如何实现插件以扩展 QStylePlugin 基类。

低级 API：扩展 Qt 应用程序

In addition to Qt itself, Qt applications can be extended through plugins. This requires the application to detect and load plugins using QPluginLoader . In that context, plugins may provide arbitrary functionality and are not limited to database drivers, image formats, text codecs, styles, and other types of plugins that extend Qt's functionality.

透过插件使应用程序可扩展，涉及以下步骤：

定义一组用于对话插件的接口 (仅具有纯虚函数的类)。
使用 Q_DECLARE_INTERFACE () 宏告诉 Qt 的元对象系统关于接口。
使用 QPluginLoader 在应用程序中加载插件。
使用 qobject_cast () 测试插件是否有实现给定接口。

编写插件涉及这些步骤：

声明插件类继承 QObject 及插件想要提供的接口。
使用 Q_INTERFACES () 宏告诉 Qt 的元对象系统关于接口。
导出插件使用 Q_PLUGIN_METADATA () 宏。

例如，这里是接口类的定义：

class FilterInterface
{
public:
    virtual ~FilterInterface() {}
    virtual QStringList filters() const = 0;
    virtual QImage filterImage(const QString &filter, const QImage &image,
                               QWidget *parent) = 0;
};

这里是实现该接口的插件类的定义：

#include <QObject>
#include <QtPlugin>
#include <QStringList>
#include <QImage>
#include <plugandpaint/interfaces.h>
class ExtraFiltersPlugin : public QObject, public FilterInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.PlugAndPaint.FilterInterface" FILE "extrafilters.json")
    Q_INTERFACES(FilterInterface)
public:
    QStringList filters() const;
    QImage filterImage(const QString &filter, const QImage &image,
                       QWidget *parent);
};

You can take a look at the 回显插件范例 which is a trivial example on how to implement a plugin that extends Qt applications. Note that a QCoreApplication instance must be initialized before plugins can be loaded.

另请参阅创建自定义 Widget 为 Qt Designer for information about issues that are specific to Qt Designer.

定位插件

Qt applications automatically know which plugins are available, because plugins are stored in the standard plugin subdirectories. Because of this, applications don't require any code to find and load plugins, since Qt handles them automatically.

在开发期间，插件目录为 QTDIR/plugins (在哪里 QTDIR 是 Qt 的安装目录)，各种类型的插件在该类型的子目录下，例如， styles 。若想要应用程序使用插件但又不想使用标准插件路径，让安装进程确定想要使用的插件路径并保存路径，例如，通过使用 QSettings ，供应用程序运行时读取。然后，应用程序可以调用 QCoreApplication::addLibraryPath () 采用此路径，您的插件将可用于应用程序。注意，最后部分的路径 (例如， styles ) 无法更改。

If you want the plugin to be loadable, one approach is to create a subdirectory under the application, and place the plugin in that directory. If you distribute any of the plugins that come with Qt (the ones located in the plugins 目录)，必须拷贝其子目录在 plugins 插件，位于应用程序根文件夹下 (即：不包括 plugins 目录)。

有关部署的更多信息，见部署 Qt 应用程序 and 部署插件文档编制。

静态插件

将插件包括在应用程序中的正常且最灵活方式，是将其编译成单独随附的动态库，并在运行时检测并加载。

可以将插件静态链接到应用程序。若构建静态版本的 Qt，这是包括 Qt 预定义插件的唯一选项。使用静态插件可使部署不易出错，但有缺点：无法添加插件功能，当不完整重新构建和重新分发应用程序时。

CMake and qmake automatically add the plugins that are typically needed by the Qt modules that are used, while more specialized plugins need to be added manually. The default list of automatically added plugins can be overridden per type.

The defaults are tuned towards an optimal out-of-the-box experience, but may unnecessarily bloat the application. It is recommended to inspect the linker command line and eliminate unnecessary plugins.

为促使实际链接并实例化静态插件， Q_IMPORT_PLUGIN () macros are also needed in application code, but those are automatically generated by the build system and added to your application project.

在 CMake 中导入静态插件

To statically link plugins in a CMake project, you need to call the qt_import_plugins 命令。

For example, the Linux libinput plugin is not imported by default. The following command imports it:

qt_import_plugins(myapp INCLUDE Qt::QLibInputPlugin)

To link the minimal platform integration plugin instead of the default Qt platform adaptation plugin, use:

qt_import_plugins(myapp
    INCLUDE_BY_TYPE platforms Qt::MinimalIntegrationPlugin
)

Another typical use case is to link only a certain set of imageformats plugins:

qt_import_plugins(myapp
    INCLUDE_BY_TYPE imageformats Qt::QJpegPlugin Qt::QGifPlugin
)

If you want to prevent the linking of any imageformats plugin, use:

qt_import_plugins(myapp
    EXCLUDE_BY_TYPE imageformats
)

If you want to turn off the addition of any default plugin, use the NO_DEFAULT option of qt_import_plugins .

在 qmake 中导入静态插件

In a qmake project, you need to add the required plugins to your build using QTPLUGIN :

QTPLUGIN += qlibinputplugin

For example, to link the minimal plugin instead of the default Qt platform adaptation plugin, use:

QTPLUGIN.platforms = qminimal

若不想链接默认，也不想自动链接 minimal QPA 插件，使用：

QTPLUGIN.platforms = -

若不想要添加到 QTPLUGIN 的所有插件被自动链接，移除 import_plugins 从 CONFIG 变量：

CONFIG -= import_plugins

创建静态插件

It is also possible to create your own static plugins by following these steps:

传递 STATIC 选项到 qt_add_plugin command in your CMakeLists.txt . For a qmake project, add CONFIG += static 到插件的 .pro 文件。
使用 Q_IMPORT_PLUGIN () 宏在应用程序中。
使用 Q_INIT_RESOURCE () 宏在应用程序中，若插件随附 qrc 文件。
链接应用程序与插件库，使用 target_link_libraries 在您的 CMakeLists.txt or LIBS 在您的 .pro 文件。

见插件和描绘范例和关联的基本工具插件，了解如何做到这的有关细节。

注意： If you are not using CMake or qmake to build your plugin, you need to make sure that the QT_STATICPLUGIN 预处理器宏有定义。

部署和调试插件

The 部署插件文档涵盖采用应用程序部署插件和调试它们 (当出现问题时) 的过程。

另请参阅 QPluginLoader and QLibrary .