Back to Qt.io
Contact Us Blog Download Qt
本页内容

自定义小工具插件

为Qt Widgets Designer 创建自定义小部件插件。

Qt Widgets Designer 中模拟时钟小部件的屏幕截图

在此示例中，所使用的自定义小部件基于“模拟时钟”示例，且未提供任何自定义信号或槽。

准备工作

要提供一个可与Qt Widgets Designer 配合使用的自定义控件，我们需要提供一个自包含的实现，并提供一个插件接口。出于方便起见，本例中我们复用了“模拟时钟”示例。

项目文件

CMake

项目文件需要声明将构建一个链接到Qt Widgets Designer 库的插件：

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)

target_link_libraries(customwidgetplugin PUBLIC
    Qt::Core
    Qt::Gui
    Qt::UiPlugin
    Qt::Widgets
)

链接库列表中指定了Qt::UiPlugin 。这表明该插件仅使用抽象接口QDesignerCustomWidgetInterface 和QDesignerCustomWidgetCollectionInterface ，且与Qt Widgets Designer 库没有链接关系。当访问Qt Widgets Designer 中具有链接关系的其他接口时，应改用Designer ；这可确保插件动态链接到Qt Widgets Designer 库，并在运行时依赖于这些库。

以下示例展示了如何添加该小部件的头文件和源文件：

target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)

我们提供了一个插件接口的实现，以便Qt Widgets Designer 能够使用该自定义控件。

此外，务必确保插件安装在Qt Widgets Designer 会搜索的位置。我们通过为项目指定目标路径并将其添加到待安装项列表中来实现这一点：

   set(INSTALL_EXAMPLEDIR "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}/designer")
install(TARGETS customwidgetplugin
    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
)

自定义小部件以库的形式创建。当项目被安装时（使用ninja install 或等效的安装流程），它将与其他Qt Widgets Designer 插件一同安装。

有关插件的更多信息，请参阅《如何创建 Qt 插件》文档。

qmake

以下示例演示了如何将插件链接到Qt Widgets Designer 库：

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

QT 变量包含关键字uiplugin ，它等同于Qt::UiPlugin 库。

以下示例展示了如何添加该控件的头文件和源文件：

HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

以下示例演示了如何将插件安装到Qt Widgets Designer 的插件路径中：

TARGET = $$qtLibraryTarget($$TARGET)

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

AnalogClock 类的定义与实现

AnalogClock 类的定义和实现方式与“模拟时钟”示例中描述的完全一致。由于该类是自包含的，且无需任何外部配置，因此可直接作为Qt Widgets Designer 中的自定义控件使用，无需进行任何修改。

AnalogClockPlugin 类定义

AnalogClock 类通过AnalogClockPlugin 类向Qt Widgets Designer 公开。该类同时继承自QObject 和QDesignerCustomWidgetInterface 类，并实现了由QDesignerCustomWidgetInterface 定义的接口。

为了确保 Qt 将该控件识别为插件，请通过添加Q_PLUGIN_METADATA() 宏来导出该控件的相关信息：

class AnalogClockPlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)
public:
    explicit AnalogClockPlugin(QObject *parent = nullptr);

    bool isContainer() const override;
    bool isInitialized() const override;
    QIcon icon() const override;
    QString domXml() const override;
    QString group() const override;
    QString includeFile() const override;
    QString name() const override;
    QString toolTip() const override;
    QString whatsThis() const override;
    QWidget *createWidget(QWidget *parent) override;
    void initialize(QDesignerFormEditorInterface *core) override;

private:
    bool initialized = false;
};

这些函数提供有关小部件的信息，Qt Widgets Designer 可在小部件框中使用这些信息。私有成员变量initialized 用于记录该插件是否已被Qt Widgets Designer 初始化。

请注意，类定义中唯一特定于此自定义控件的部分是类名。

AnalogClockPlugin 的实现

该类的构造函数仅调用基类QObject 的构造函数，并将initialized 变量设置为false 。

AnalogClockPlugin::AnalogClockPlugin(QObject *parent)
    : QObject(parent)
{
}

Qt Widgets Designer 将在需要时通过调用initialize() 函数来初始化该插件：

void AnalogClockPlugin::initialize(QDesignerFormEditorInterface * /* core */)
{
    if (initialized)
        return;

    initialized = true;
}

在此示例中，会检测私有变量 `initialized `，仅当插件尚未初始化时，才将其设置为 `true `。尽管该插件在初始化时无需执行任何特殊代码，但我们仍可在初始化检测之后加入此类代码。

isInitialized() 函数用于告知Qt Widgets Designer 该插件是否已准备就绪：

bool AnalogClockPlugin::isInitialized() const
{
    return initialized;
}

自定义小部件的实例由 `createWidget() ` 函数提供。模拟时钟的实现非常简单：

QWidget *AnalogClockPlugin::createWidget(QWidget *parent)
{
    return new AnalogClock(parent);
}

在此情况下，自定义控件仅需指定parent 函数。如果需要向控件提供其他参数，可以在此处引入。

以下函数为 `Qt Widgets Designer ` 提供信息，以便其在控件框中呈现该控件。name() 函数返回提供该自定义控件的类名：

QString AnalogClockPlugin::name() const
{
    return u"AnalogClock"_s;
}

group() 函数用于描述该自定义小部件所属的小部件类型：

QString AnalogClockPlugin::group() const
{
    return u"Display Widgets [Examples]"_s;
}

该小部件插件将被放置在Qt Widgets Designer 的小部件框中，其位置由所属组名标识。用于在小部件框中表示该小部件的图标由icon() 函数返回：

QIcon AnalogClockPlugin::icon() const
{
    return {};
}

在此情况下，我们返回一个 null 图标，以表示没有可用于表示该小部件的图标。

可以在小工具框中为自定义小工具的条目提供工具提示和“这是什么？”帮助信息。toolTip() 函数应返回一条简短消息来描述该小工具：

QString AnalogClockPlugin::toolTip() const
{
    return {};
}

whatsThis() 函数可以返回更长的描述：

QString AnalogClockPlugin::whatsThis() const
{
    return {};
}

isContainer() 函数用于告知Qt Widgets Designer 该控件是否应作为其他控件的容器。若非如此，Qt Widgets Designer 将不允许用户在其内部放置控件。

bool AnalogClockPlugin::isContainer() const
{
    return false;
}

Qt Widgets 中的大多数小部件都可以包含子小部件，但在Qt Widgets Designer 中，仅对专门的容器小部件使用此功能才有意义。通过返回false ，我们表明该自定义小部件无法容纳其他小部件；如果返回 true，Qt Widgets Designer 将允许在模拟时钟内部放置其他小部件并定义布局。

domXml() 函数提供了一种方式，可在Qt Widgets Designer 所使用的标准 XML 格式中包含控件的默认设置。在此情况下，我们仅需指定控件的几何属性：

QString AnalogClockPlugin::domXml() const
{
    return uR"(
<ui language="c++">
  <widget class="AnalogClock" name="analogClock">
)"
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
R"(
    <property name="toolTip">
      <string>The current time</string>
    </property>
    <property name="whatsThis">
      <string>The analog clock widget displays the current time.</string>
    </property>
  </widget>
</ui>
)"_s;
}

如果小部件提供了合理的大小提示，则无需在此处定义。此外，返回空字符串而非 `<widget> ` 元素，将指示Qt Widgets Designer 不要将该小部件安装到小部件框中。

为了使模拟时钟小部件可供应用程序使用，我们实现了includeFile() 函数，使其返回包含自定义小部件类定义的头文件名称：

QString AnalogClockPlugin::includeFile() const
{
    return u"analogclock.h"_s;
}

示例项目 @ code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.