QWidgetAction Class
QWidgetAction 类通过提供一个接口，扩展了QAction ，该接口用于将自定义小部件插入到基于操作的容器（如工具栏）中。更多内容...
| 头文件： | #include <QWidgetAction> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 继承自： | QAction |
公共函数
| QWidgetAction(QObject *parent) | |
| virtual | ~QWidgetAction() |
| QWidget * | defaultWidget() const |
| void | releaseWidget(QWidget *widget) |
| QWidget * | requestWidget(QWidget *parent) |
| void | setDefaultWidget(QWidget *widget) |
受保护函数
| virtual QWidget * | createWidget(QWidget *parent) |
| QList<QWidget *> | createdWidgets() const |
| virtual void | deleteWidget(QWidget *widget) |
重新实现的受保护函数
| virtual bool | event(QEvent *event) override |
| virtual bool | eventFilter(QObject *obj, QEvent *event) override |
详细说明
应用程序中的大多数操作都以菜单中的项目或工具栏中的按钮的形式呈现。但有时需要更复杂的控件。 例如，文字处理器中的缩放操作可以使用QToolBar 中的QComboBox 来实现，从而提供一系列不同的缩放级别。QToolBar 提供了QToolBar::insertWidget()作为插入单个小部件的便捷函数。但是，如果您想实现一个使用自定义小部件在多个容器中进行可视化的操作，则必须继承QWidgetAction。
例如，如果将一个 QWidgetAction 添加到QToolBar 中，则会调用QWidgetAction::createWidget()。该函数的重写实现应创建一个具有指定父控件的新自定义控件。
如果将该操作从容器控件中移除，则会调用 `QWidgetAction::deleteWidget()`，并将之前创建的自定义控件作为参数传入。默认实现会隐藏该控件，并使用 `QObject::deleteLater()` 将其删除。
如果您只有一个自定义小部件，则可以使用setDefaultWidget() 将其设置为默认小部件。当该操作被添加到QToolBar 中，或者一般而言被添加到支持 QWidgetAction 的操作容器中时，系统将使用该小部件。 如果将一个仅包含默认小部件的 QWidgetAction 同时添加到两个工具栏中，则该默认小部件仅会在该动作被添加到的第一个工具栏中显示。QWidgetAction 会接管该默认小部件的所有权。
请注意，是否激活该操作由小部件自行决定，例如通过重写鼠标事件处理程序并调用QAction::trigger()来实现。
macOS：若在 macOS 上将小部件添加到应用程序菜单栏的菜单中，该小部件将被添加且能够正常工作，但存在以下限制：
另请参阅 QAction 、QActionGroup 和QWidget 。
成员函数文档
[explicit] QWidgetAction::QWidgetAction(QObject *parent)
使用parent 构建一个操作。
[virtual noexcept] QWidgetAction::~QWidgetAction()
销毁该对象并释放已分配的资源。
[virtual protected] QWidget *QWidgetAction::createWidget(QWidget *parent)
每当将该操作添加到支持自定义控件的容器控件时，都会调用此函数。如果不想让自定义控件在指定的parent 控件中作为该操作的表示，则应返回 0。
另请参阅 deleteWidget()。
[protected] QList<QWidget *> QWidgetAction::createdWidgets() const
返回已使用 `createWidget()` 且当前正被添加了该操作的小部件所使用的控件列表。
QWidget *QWidgetAction::defaultWidget() const
返回默认控件。
另请参阅 ` setDefaultWidget()`。
[virtual protected] void QWidgetAction::deleteWidget(QWidget *widget)
每当从显示该操作的容器控件中移除该操作时，都会调用此函数，该控件使用的是此前通过createWidget() 创建的自定义widget 。默认实现会隐藏widget ，并使用QObject::deleteLater() 将其排入删除队列。
另请参阅 createWidget()。
[override virtual protected] bool QWidgetAction::event(QEvent *event)
重写了：QAction::event(QEvent *e)。
[override virtual protected] bool QWidgetAction::eventFilter(QObject *obj, QEvent *event)
重写了：QObject::eventFilter(QObject *watched, QEvent *event)。
void QWidgetAction::releaseWidget(QWidget *widget)
释放指定的widget 。
支持操作的容器控件会在控件操作被移除时调用此函数。
另请参阅 requestWidget()、deleteWidget() 和defaultWidget()。
QWidget *QWidgetAction::requestWidget(QWidget *parent)
返回一个表示该操作的小部件，并使用给定的parent 。
支持操作的容器控件可以调用此函数，以请求一个用作该操作可视化表示的控件。
另请参阅 releaseWidget()、createWidget() 和defaultWidget()。
void QWidgetAction::setDefaultWidget(QWidget *widget)
将widget 设置为默认小部件。所有权转移给QWidgetAction 。除非子类重写了createWidget()方法以返回一个新的小部件，否则当容器小部件通过requestWidget()请求小部件时，将使用默认小部件。
另请参阅 defaultWidget()。
© 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.
