主窗口(09)：【类】QAction [官翻]

最新推荐文章于 2025-04-28 10:00:00 发布

原创最新推荐文章于 2025-04-28 10:00:00 发布 · 1.3k 阅读

6 ·

CC 4.0 BY-SA版权

Qt Widgets 专栏收录该内容

67 篇文章

订阅专栏

QAction类提供了一种抽象的用户界面操作，可用于菜单、工具栏和快捷键。它可以包含图标、文本、快捷方式等，并通过连接到槽来执行相应操作。操作可以设置为可检查的，拥有不同优先级，并能在菜单中显示或隐藏图标。此外，QAction还支持自动重复、状态提示和‘这是什么’帮助文本等功能。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

QAction Class

QAction类提供了一个抽象的用户界面操作，可以插入到小部件中。

Header	#include < QAction >
qmake	QT += widgets
Inherits	QObject
Inherited By	QWidgetAction

详细说明

在应用程序中，可以通过菜单、工具栏按钮和键盘快捷键调用许多常用命令。由于用户希望每个命令都以相同的方式执行，因此不管使用什么用户界面，将每个命令表示为一个操作都是很有用的。

操作可以添加到菜单和工具栏，并将自动保持同步。例如，在字处理器中，如果用户按下粗体工具栏按钮，粗体菜单项将自动选中。

操作可以作为独立对象创建，但也可以在构建菜单期间创建；QMenu类包含方便的函数，用于创建适合用作菜单项的动作。

QAction可能包含图标、菜单文本、快捷方式、状态文本，“这是什么？”文本和工具提示。其中大部分可以在构造函数中设置。它们也可以通过setIcon() 、setText() 、setIconText() 、setShortcut() 、setStatusTip() 、setWhatsThis() 和setToolTip() 独立设置。对于菜单项，可以使用setFont() 设置单个字体。

使用QWidget::addAction() 或QGraphicsWidget::addAction() 将操作添加到小部件。请注意，必须先将操作添加到小部件中，然后才能使用它；当快捷方式应为全局快捷方式（即Qt::ApplicationShortcut as Qt::ShortcutContext）时，也是如此。

一旦创建了一个QAction，它应该被添加到相关的菜单和工具栏中，然后连接到执行该操作的插槽。例如:

     const QIcon openIcon = QIcon::fromTheme("document-open", QIcon(":/images/open.png"));
     QAction *openAct = new QAction(openIcon, tr("&Open..."), this);
     openAct->setShortcuts(QKeySequence::Open);
     openAct->setStatusTip(tr("Open an existing file"));
     connect(openAct, &QAction::triggered, this, &MainWindow::open);
     fileMenu->addAction(openAct);
     fileToolBar->addAction(openAct);

我们建议将操作创建为所用窗口的子级。在大多数情况下，操作将是应用程序主窗口的子窗口。

公共类型

enum ActionEvent

调用QAction::activate（）时使用此枚举类型

Constant	Value	Description
Trigger	0	这将导致发出QAction::triggered（）信号。
Hover	1	这将导致发出QAction::hovered（）信号。

enum MenuRole

此枚举描述如何将操作移动到 macOS 上的应用程序菜单中。

Constant	Value	Description
NoRole	0	此操作不应放入应用程序菜单
TextHeuristicRole	1	应根据QMenuBar文档中描述的操作文本，将此操作置于应用程序菜单中。
ApplicationSpecificRole	2	此操作应放在具有特定于应用程序角色的应用程序菜单中
AboutQtRole	3	此操作处理“About Qt”菜单项。
AboutRole	4	此操作应放置在应用程序菜单中“关于”菜单项的位置。菜单项的文本将设置为“关于< application name >”。应用程序名称是从信息列表应用程序包中的文件（参见Qt for macOS-Deployment）。
PreferencesRole	5	此操作应放置在应用程序菜单中“首选项…”菜单项的位置。
QuitRole	6	此操作应放置在应用程序菜单中“退出”菜单项的位置。

设置此值仅对菜单栏的即时菜单中的项目有效，而对这些菜单的子菜单无效。例如，如果菜单栏中有“文件”菜单，并且“文件”菜单有一个子菜单，则为该子菜单中的操作设置菜单栏将不起作用。他们永远不会被移动。

enum Priority

此枚举定义用户界面中操作的优先级。

Constant	Value	Description
LowPriority	0	在用户界面中不应优先考虑该操作。
NormalPriority	128
HighPriority	256	操作应该在用户界面中按优先级排列。

属性

autoRepeat: bool 操作是否可以自动重复

如果为true，则当按下键盘快捷键组合时，如果系统上启用了键盘自动重复，则操作将自动重复。默认值为true。
- bool autoRepeat() const
- void setAutoRepeat(bool)
Notifier signal:
- void changed()
checkable: bool 操作是否为可检查的操作

可检查的动作是具有开/关状态的动作。例如，在字处理器中，粗体工具栏按钮可以是开或关。不是切换操作的操作是命令操作；命令操作只是简单地执行，例如文件保存。默认情况下，此属性为false。

在某些情况下，一个切换动作的状态应该取决于其他动作的状态。例如，“左对齐”、“居中”和“右对齐”切换动作是互斥的。要实现独占切换，请将相关的切换操作添加到QActionGroup，并将QActionGroup::exclusive属性设置为true。
- bool isCheckable() const
- void setCheckable(bool)
**Notifier signal: **
- void changed()
checked: bool 是否选中该操作

只能检查可检查的操作。默认情况下，这是false（该操作未选中）。

注意:此属性的通知程序信号为toggled（）。当切换一个QAction改变它的状态时，它也会发出一个changed（）信号。
- bool isChecked() const
- void setChecked(bool)
**Notifier signal: **
- void toggled(bool checked)
enabled: bool 是否已启用该操作

用户无法选择禁用的操作。它们不会从菜单或工具栏中消失，但它们的显示方式表明它们不可用。例如，它们可能仅使用灰度显示。

这是什么？如果设置了QAction::whatsThis属性，则有关禁用操作的帮助仍然可用。

当添加到其中的所有小部件（使用QWidget::addAction（））被禁用或不可见时，操作将被禁用。当某个操作被禁用时，无法通过其快捷方式触发它。

默认情况下，此属性为true（启用操作）。
- bool isEnabled() const
- void setEnabled(bool)
**Notifier signal: **
- void changed()
font: QFont 操作的字体

font属性用于呈现QAction上的文本集。字体将被视为一个提示，因为它不会在所有情况下根据应用程序和样式进行查询。

默认情况下，此属性包含应用程序的默认字体。
- QFont font() const
- void setFont(const QFont &font)
**Notifier signal: **
- void changed()
icon: QIcon 操作的图标

在工具栏中，图标用作工具按钮图标；在菜单中，它显示在菜单文本的左侧。没有默认图标。

如果将空图标（QIcon::isNull（））传递到此函数中，则清除操作的图标。
- QIcon icon() const
- void setIcon(const QIcon &icon)
**Notifier signal: **
- void changed()
iconText: QString 操作的描述性图标文本

如果将QToolBar::toolButtonStyle设置为允许显示文本的值，则此属性中定义的文本将作为标签显示在相关的工具按钮中。

如果没有使用setText（）或setToolTip（）定义操作，它也将作为菜单和工具提示中的默认文本，如果没有使用setIcon（）定义图标，它也将用于工具栏按钮中。

如果未显式设置图标文本，则操作的普通文本将用于图标文本。

默认情况下，此属性包含空字符串。
- QString iconText() const
- void setIconText(const QString &text)
**Notifier signal: **
- void changed()
iconVisibleInMenu: bool 操作是否应在菜单中显示图标

在某些应用程序中，在工具栏中有图标的操作可能是有意义的，但在菜单中没有。如果为true，则在菜单中显示图标（如果有效），如果为false，则不显示图标。

默认值是遵循是否为应用程序设置了Qt::AA_DontShowIconsInMenus属性。显式设置此属性将覆盖属性的存在（或不存在）。

例如:
```
 QApplication app(argc, argv);
 app.setAttribute(Qt::AA_DontShowIconsInMenus);  // Icons are *no longer shown* in menus
 // ...
 QAction *myAction = new QAction();
 // ...
 myAction->setIcon(SomeIcon);
 myAction->setIconVisibleInMenu(true);   // Icon *will* be shown in menus for *this* action.
```
Access functions:
- bool isIconVisibleInMenu() const
- void setIconVisibleInMenu(bool visible)
**Notifier signal: **
- void changed()
menuRole: MenuRole 操作的菜单角色
这表示该操作在macOS上的应用程序菜单中所起的作用。默认情况下，所有操作都具有TextHeuristicRole，这意味着操作是基于其文本添加的（有关详细信息，请参阅QMenuBar）。
菜单角色只能在操作放入macOS中的菜单栏之前更改（通常在显示第一个应用程序窗口之前）。
- QAction::MenuRole menuRole() const
- void setMenuRole(QAction::MenuRole menuRole)
**Notifier signal: **
- void changed()
priority: Priority 用户界面中保留操作的优先级

可以设置此属性以指示操作在用户界面中的优先级。
例如，当工具栏设置了Qt::ToolButtonTextBesideIcon模式时，低优先级的操作将不会显示文本标签。
- QAction::Priority priority() const
- void setPriority(QAction::Priority priority)
shortcut: QKeySequence 操作的主快捷键

此属性的有效键码可以在Qt::Key和Qt::Modifier中找到。没有默认的快捷键。
- QKeySequence shortcut() const
- void setShortcut(const QKeySequence &shortcut)
**Notifier signal: **
- void changed()
shortcutContext: Qt::ShortcutContext 操作快捷方式的上下文

此属性的有效值可以在Qt:：ShortcutContext中找到。默认值为Qt:：WindowShortcut。
- Qt::ShortcutContext shortcutContext() const
- void setShortcutContext(Qt::ShortcutContext context)
**Notifier signal: **
- void changed()
shortcutVisibleInContextMenu: bool 操作是否应在上下文菜单中显示快捷方式

在某些应用程序中，在上下文菜单中使用带有快捷方式的操作可能是有意义的。如果为true，则在通过关联菜单显示操作时显示快捷方式（如果有效），如果为false，则不显示快捷方式。

默认值是遵循是否为应用程序设置了Qt：：AA_DontShowShortcutsInContextMenus属性，返回到小部件样式提示。显式设置此属性将覆盖属性的存在（或不存在）。
- bool isShortcutVisibleInContextMenu() const
- void setShortcutVisibleInContextMenu(bool show)
**Notifier signal: **
- void changed()
statusTip: QString 操作的状态提示

状态提示显示在操作的顶级父窗口小部件提供的所有状态栏上。

默认情况下，此属性包含空字符串。
- QString statusTip() const
- void setStatusTip(const QString &statusTip)
**Notifier signal: **
- void changed()
text: QString 操作的描述性文本

如果操作被添加到菜单中，菜单选项将由图标（如果有）、文本和快捷方式（如果有）组成。如果未在构造函数中显式设置文本，或使用setText（），则操作的描述图标文本将用作文本。没有默认文本。
- QString text() const
- void setText(const QString &text)
**Notifier signal: **
- void changed()
toolTip: QString 操作的工具提示

此文本用于工具提示。如果未指定工具提示，则使用操作的文本。
默认情况下，此属性包含操作的文本。
- QString toolTip() const
- void setToolTip(const QString &tip)
**Notifier signal: **
- void changed()
visible: bool 是否可以看到操作（例如，在菜单和工具栏中）

如果visible为true，则用户可以看到（例如在菜单和工具栏中）并选择操作；如果visible为false，则用户无法看到或选择操作。
不可见的操作不会灰显；它们根本不会出现。
默认情况下，此属性为true（操作可见）。
- bool isVisible() const
- void setVisible(bool)
**Notifier signal: **
- void changed()
whatsThis: QString 操作的“这是什么？”帮助文本
“这是什么？”文本用于简要描述操作。文本可能包含富文本。没有默认的“这是什么？”文本。
- QString whatsThis() const
- void setWhatsThis(const QString &what)
**Notifier signal: **
- void changed()

公共函数

构造和析构

QAction(const QIcon &icon, const QString &text, QObject *parent = nullptr)
QAction(const QString &text, QObject *parent = nullptr)
QAction(QObject *parent = nullptr)
virtual ~QAction()

属性相关

bool autoRepeat() const
void setAutoRepeat(bool)
bool isCheckable() const
void setCheckable(bool)
bool isChecked() const
void setChecked(bool)
bool isEnabled() const
void setEnabled(bool)
QFont font() const
void setFont(const QFont &font)
QIcon icon() const
void setIcon(const QIcon &icon)
QString iconText() const
void setIconText(const QString &text)
bool isIconVisibleInMenu() const
void setIconVisibleInMenu(bool visible)
QAction::MenuRole menuRole() const
void setMenuRole(QAction::MenuRole menuRole)
QAction::Priority priority() const
void setPriority(QAction::Priority priority)
QKeySequence shortcut() const
void setShortcut(const QKeySequence &shortcut)
Qt::ShortcutContext shortcutContext() const
void setShortcutContext(Qt::ShortcutContext context)
bool isShortcutVisibleInContextMenu() const
void setShortcutVisibleInContextMenu(bool show)
QString statusTip() const
void setStatusTip(const QString &statusTip)
QString text() const
void setText(const QString &text)
QString toolTip() const
void setToolTip(const QString &tip)
bool isVisible() const
void setVisible(bool)
QString whatsThis() const
void setWhatsThis(const QString &what)

其它

QActionGroup * actionGroup() const
void setActionGroup(QActionGroup *group) 将此操作组设置为组
该操作将自动添加到组的操作列表中。组内的操作将相互排斥。
void activate(QAction::ActionEvent event) 发送ActionEvent的相关信号

基于操作的小部件使用这个API使QAction在发出自己的信号的同时发出信号。
QList<QGraphicsWidget *> associatedGraphicsWidgets() const
QList<QWidget *> associatedWidgets() const
QWidget * parentWidget() const 返回父窗口小部件
QVariant data() const
void setData(const QVariant &userData)
bool isSeparator() const
void setSeparator(bool b)
QMenu * menu() const
void setMenu(QMenu *menu)
QList< QKeySequence > shortcuts() const
void setShortcuts(const QList< QKeySequence > &shortcuts)
void setShortcuts(QKeySequence::StandardKey key)
bool showStatusText(QWidget *widget = nullptr)
通过向其父小部件发送QStatusTipEvent来更新指定小部件的相关状态栏
如果发送了事件，则返回true；否则返回false。如果指定了null小部件，则将事件发送到操作的父级。