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

QDesignerCustomWidgetInterface Class

QDesignerCustomWidgetInterface 类使Qt Widgets Designer 能够访问和构建自定义控件。更多内容...

头文件： #include <QDesignerCustomWidgetInterface>
CMake： find_package(Qt6 REQUIRED COMPONENTS Designer)
target_link_libraries(mytarget PRIVATE Qt6::Designer)
qmake： QT += designer

公共函数

virtual ~QDesignerCustomWidgetInterface()
virtual QString codeTemplate() const
virtual QWidget *createWidget(QWidget *parent) = 0
virtual QString domXml() const
virtual QString group() const = 0
virtual QIcon icon() const = 0
virtual QString includeFile() const = 0
virtual void initialize(QDesignerFormEditorInterface *formEditor)
virtual bool isContainer() const = 0
virtual bool isInitialized() const
virtual QString name() const = 0
virtual QString toolTip() const = 0
virtual QString whatsThis() const = 0

宏

QDESIGNER_WIDGET_EXPORT

详细说明

QDesignerCustomWidgetInterface 为自定义控件提供了一个接口。该类包含一组函数，子类必须重写这些函数以返回控件的基本信息，例如其类名和头文件名。 还必须实现其他函数，以便在加载插件时对其进行初始化，并为Qt Widgets Designer 构建自定义小部件的实例以供其使用。

在实现自定义控件时，必须继承 QDesignerCustomWidgetInterface，以便将您的控件暴露给Qt Widgets Designer 。例如，以下是“自定义控件插件”示例中使用的插件声明，该插件使Qt Widgets Designer 能够使用模拟时钟自定义控件：

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;
};

请注意，类定义中唯一与该特定自定义控件相关的部分是类名。此外，由于我们正在实现一个接口，因此必须通过Q_INTERFACES()宏确保该接口被元对象系统所识别。这使得Qt Widgets Designer 能够仅通过一个QObject 指针，使用qobject_cast()函数查询支持的接口。

Qt Widgets Designer 加载自定义控件插件后，会调用该接口的initialize() 函数，以便其配置可能需要的任何资源。该函数的调用会传入一个QDesignerFormEditorInterface 参数，该参数为插件提供了访问Qt Widgets Designer 所有 API 的入口。

Qt Widgets Designer 通过向插件的createWidget()函数传入合适的父控件来构建自定义控件的实例。插件必须使用指定的父控件构建并返回一个自定义控件的实例。

使用Q_PLUGIN_METADATA()宏将自定义控件插件导出到Qt Widgets Designer 。例如，如果名为libcustomwidgetplugin.so （在Unix系统上）或libcustomwidget.dll （在Windows系统上）的库中包含一个名为MyCustomWidget 的控件类，我们可以通过在包含插件头文件中添加以下行来导出它：

Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")

该宏可确保Qt Widgets Designer 能够访问并构建该自定义控件。如果没有此宏，Qt Widgets Designer 将无法使用它。

在实现自定义控件插件时，需将其构建为独立的库。若要在同一个库中包含多个自定义控件插件，还必须继承QDesignerCustomWidgetCollectionInterface 类。

警告：如果 您的自定义控件插件包含QVariant 属性，请注意仅支持以下types ：

  • QVariant::ByteArray
  • QVariant::Bool
  • QVariant::Color
  • QVariant::Cursor
  • QVariant::Date
  • QVariant::DateTime
  • QVariant::Double
  • QVariant::Int
  • QVariant::Point
  • QVariant::Rect
  • QVariant::Size
  • QVariant::SizePolicy
  • QVariant::String
  • QVariant::Time
  • QVariant::UInt

有关使用 QDesignerCustomWidgetInterface 类的完整示例，请参阅“自定义控件示例”。该示例演示了如何为Qt Widgets Designer 创建自定义控件插件。

另请参阅 QDesignerCustomWidgetCollectionInterface 以及《为Qt Widgets Designer 创建自定义控件》。

成员函数文档

[virtual constexpr noexcept default] QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()

销毁自定义小部件界面。

[virtual] QString QDesignerCustomWidgetInterface::codeTemplate() const

此函数预留供Qt Widgets Designer 将来使用。

[pure virtual] QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)

返回自定义控件的新实例，并使用给定的parent 。

[virtual] QString QDesignerCustomWidgetInterface::domXml() const

返回用于向Qt Widgets Designer 描述自定义小部件属性的 XML。

[pure virtual] QString QDesignerCustomWidgetInterface::group() const

返回自定义控件所属的组名称。

[pure virtual] QIcon QDesignerCustomWidgetInterface::icon() const

返回用于在Qt Widgets Designer 的控件框中表示自定义控件的图标。

[pure virtual] QString QDesignerCustomWidgetInterface::includeFile() const

返回uic在为自定义控件生成代码时所使用的头文件路径。

对于在 C++ 中使用的自定义小部件以及 Qt for Python中使用的自定义控件，请使用前缀在返回的字符串中指定特定于语言的信息，如下所示：

"C++:myheader.h,Python:MyModule"

[virtual] void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)

初始化该控件，以便与指定的formEditor 接口配合使用。

另请参阅 isInitialized()。

[pure virtual] bool QDesignerCustomWidgetInterface::isContainer() const

如果自定义控件旨在用作容器，则返回 true；否则返回 false。

大多数自定义控件并不用于容纳其他控件，因此它们对此函数的实现将返回 false；但自定义容器会返回 true，以确保它们在 `Qt Widgets Designer` 中能正常工作。

[virtual] bool QDesignerCustomWidgetInterface::isInitialized() const

如果小部件已初始化，则返回 true；否则返回 false。

另请参阅 initialize()。

[pure virtual] QString QDesignerCustomWidgetInterface::name() const

返回接口提供的自定义控件的类名。

返回的名称必须与自定义控件所使用的类名完全一致。

[pure virtual] QString QDesignerCustomWidgetInterface::toolTip() const

返回该控件的简短描述，Qt Widgets Designer 可在工具提示中使用该描述。

[pure virtual] QString QDesignerCustomWidgetInterface::whatsThis() const

返回该控件的描述，Qt Widgets Designer 可在该控件的“这是什么？”帮助中使用该描述。

宏文档

QDESIGNER_WIDGET_EXPORT

在定义自定义小部件时使用此宏，以确保它们能从插件中正确导出，以便与Qt Widgets Designer 配合使用。

在某些平台上，构建系统会从插件中移除Qt Widgets Designer 创建新小部件所需的符号，导致这些小部件无法使用。使用此宏可确保在这些平台上保留这些符号，且对其他平台不会产生任何副作用。

例如，“自定义控件插件”示例通过以下声明导出一个自定义控件类：

class QDESIGNER_WIDGET_EXPORT AnalogClock : public QWidget
{
    Q_OBJECT
    ...
};

另请参阅 《为Qt Widgets Designer 创建自定义控件》。

© 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.