class QAction#

类 QAction 为可以将用户命令添加到不同用户界面组件的抽象提供。

Inheritance diagram of PySide6.QtGui.QAction

继承自： QWidgetAction

概要#

属性#

方法#

槽函数#

信号#

注意

本文档可能包含从 C++ 自动翻译到 Python 的示例代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译中的问题，您也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 创建工单来告知我们。

详细描述#

在应用程序中，许多常用命令可以通过菜单、工具栏按钮和键盘快捷键来调用。由于用户期望无论使用何种用户界面，每个命令都能以相同的方式进行执行，因此将每个命令表示为 动作 是有用的。

可以将操作添加到用户界面元素，如菜单和工具栏中，这些操作将自动保持UI同步。例如，在一个文字处理程序中，如果用户按下粗体工具栏按钮，粗体菜单项将自动被勾选。

QAction 可能包含图标、描述性文本、图标文本、键盘快捷键、状态文本、“这是什么？”文本和工具提示。所有属性都可以使用 setIcon()、setText()、setIconText()、setShortcut()、setStatusTip()、setWhatsThis() 和 setToolTip() 方法独立设置。图标和文本，作为两个最重要的属性，也可以在构造函数中设置。可以使用 setFont() 方法设置单个字体，例如菜单在显示操作作为菜单项时将尊重它。

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

小部件应用程序中的QAction#

一旦创建了 QAction，应将其添加到相关菜单和工具栏中，然后再将其连接到执行操作的槽。

使用 QWidget::addAction() 或 QGraphicsWidget::addAction() 将操作添加到小部件中。注意，在可以使用之前必须将操作添加到小部件中。当快捷键应该是全局的（即，Qt::ApplicationShortcut 作为 Qt::ShortcutContext）时，这也是正确的。

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

另请参阅

QMenuQToolBar

class MenuRole#

这个枚举描述了如何在 macOS 上将操作移动到应用程序菜单中的方式。

常量

描述

QAction.NoRole

此操作不应放入应用程序菜单

QAction.TextHeuristicRole

根据 QMenuBar 文档中的描述，此操作应根据其文本放入应用程序菜单

QAction.ApplicationSpecificRole

此操作应使用应用程序特定角色放入应用程序菜单中

QAction.AboutQtRole

此操作处理“关于 Qt”菜单项

QAction.AboutRole

此动作应放置在应用程序菜单中的“关于”菜单项的位置。菜单项的文本设置为“关于 <应用程序名称>”。应用程序名称从应用程序包中的Info.plist文件中获取（参见Qt for macOS - 部署）。

QAction.PreferencesRole

此动作应放置在应用程序菜单中的“偏好设置...”菜单项位置。

QAction.QuitRole

此动作应放置在应用程序菜单中的“退出”菜单项位置。

仅对位于菜单栏直接菜单中的项设置此项才有效，而不是那些菜单的子菜单。例如，如果您在菜单栏中有“文件”菜单，且“文件”菜单有一个子菜单，设置该子菜单中动作的MenuRole将没有效果。它们永远不会移动。

class Priority#

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

常量

描述

QAction.LowPriority

动作在用户界面中不应优先排序。

QAction.NormalPriority

QAction.HighPriority

动作在用户界面中应优先排序。

另请参阅

优先级

新版本 4.6 中引入。

class ActionEvent#

此枚举类型在与activate() 方法一起调用时使用。

常量

描述

QAction.Trigger

这将导致 triggered() 信号发出。

QAction.Hover

这将导致 hovered() 信号发出。

注意

在使用 from __feature__ import true_property 时可以直接使用属性，否则通过访问函数。

property autoRepeatᅟ: bool#

此属性表示动作是否可以自动重复。

如果为真，则当按下键盘快捷键组合时，该动作将自动重复，前提是系统启用了键盘自动重复。默认值为 true。

访问函数
property checkableᅟ: bool#

此属性表示动作是否为可检查的动作。

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

在某些情况下，一个切换动作的状态应该依赖于其他动作的状态。例如，“左对齐”、“居中”和“右对齐”切换动作是相互排斥的。要实现独家切换，请将相关的切换动作添加到一个设置了QActionGroup::exclusive属性为true的QActionGroup中。

另请参阅

setChecked()

访问函数
属性checked: bool

此属性表示该动作是否被选中。

只有可切换的动作才能被选中。默认情况下，这个值为false（动作未被选中）。

注意

此属性的信号为toggled() 。当切换一个QAction会改变其状态，它也会发射一个changed()信号。

另请参阅

checkable toggled()

访问函数
属性enabled: bool

此属性表示动作是否启用。

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

这是什么？禁用动作的帮助依然可用，前提是设置了whatsThis属性。

当所有添加到其中的小部件（使用QWidget::addAction()）都被禁用或不可见时，一个动作将处于禁用状态。当动作被禁用时，通过其快捷键无法触发它。

默认情况下，此属性为true（动作是启用的）。

另请参阅

text

访问函数
属性font: QFont

此属性持有动作的字体。

字体属性用于渲染设置在QAction 上的文本。字体可以被视为一种提示，因为在某些情况下，根据应用程序和样式，可能不会查阅它。

默认情况下，此属性包含应用程序的默认字体。

另请参阅

setText()

访问函数
属性icon:QIcon#

此属性持有动作的图标。

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

如果将空图标（ isNull() ）传递给此函数，则会清除动作的图标。

访问函数
属性iconText:str#

此属性持有动作的描述性图标文本。

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

如果动作未使用setText() 或setToolTip() 定义，则它还用作菜单和工具提示的默认文本，如果没有使用setIcon() 定义图标，它也将用于工具栏按钮。

如果没有显式设置图标文本，则将使用动作的正常文本作为图标文本。

默认情况下，此属性包含一个空字符串。

访问函数
属性iconVisibleInMenu:bool#

警告

本节包含自动从C++翻译到Python的代码片段，可能包含错误。

此属性用于保留动作是否应在菜单中显示图标。

在某些应用程序中，可能需要在工具栏中显示具有图标的动作，但不在菜单中显示。如果为true，则会显示（如果有效）菜单中的图标；如果为false，则不会显示。

默认情况下，将遵循是否已为应用程序设置Qt::AA_DontShowIconsInMenus属性。明确定义此属性将覆盖属性的（存在或不存在）。

例如

app = QApplication([])
app.setAttribute(Qt.AA_DontShowIconsInMenus) # Icons are no longer shown in menus
# ...
myAction = QAction()
# ...
myAction.setIcon(SomeIcon)
myAction.setIconVisibleInMenu(True) # Icon will be shown in menus for this action.

另请参阅

icon setAttribute()

访问函数
属性 menuRole: QAction.MenuRole#

此属性存储动作的菜单角色。

这表示动作在macOS应用程序菜单中的角色。默认情况下，所有动作都有TextHeuristicRole ，这意味着动作是根据其文本添加的（有关更多信息，请参阅QMenuBar）。

此菜单角色只能在将动作放入macOS菜单栏之前进行更改（通常是在第一个应用程序窗口显示之前）。

访问函数
属性 priority: QAction.Priority#

此属性存储动作的优先级。

可以设置此属性以指示如何对动作进行优先级排序。

例如，当工具栏设置为Qt::ToolButtonTextBesideIcon模式时，则具有LowPriority 的动作不会显示文本标签。

访问函数
属性 shortcut: QKeySequence#

此属性存储动作的主要快捷键。

此属性的合法键编码可以在Qt::Key和Qt::Modifier中找到。没有默认快捷键。

访问函数
属性 shortcutContext: Qt ShortcutContext#

此属性存储动作快捷键的上下文。

此属性的合法值可以在Qt::ShortcutContext中找到。默认值是Qt::WindowShortcut。

访问函数
属性 shortcutVisibleInContextMenu: bool#

此属性存储是否在上下文菜单中显示动作的快捷键。

在某些应用程序中，在上下文菜单中显示具有快捷键的动作可能是合理的。如果为真，则当通过上下文菜单显示动作时，将显示快捷键（如果有效）；如果为假，则不会显示。

默认情况下，将根据是否为应用程序设置了Qt::AA_DontShowShortcutsInContextMenus属性来决定。显式设置此属性将覆盖该属性。

另请参阅

shortcut setAttribute()

访问函数
属性 statusTip: str#

此属性包含动作的状态提示。

状态提示将显示在由动作的顶级父窗口提供的所有状态栏中。

默认情况下，此属性包含一个空字符串。

访问函数
属性 text: str#

此属性包含动作的描述性文本。

如果动作被添加到菜单中，菜单选项将包含图标（如果有），文本和快捷键（如果有）。如果未在构造函数中明确设置文本，或者使用 setText()，则将使用动作的描述性图标文本作为文本。没有默认文本。

某些 UI 元素，如菜单或按钮，可以在字符前使用‘&’来自动为该字符创建一个快捷键（别名）。例如，“&File”将创建快捷键 Alt+F，打开文件菜单。“E’xit”将为按钮创建 Alt+X 的快捷键，或允许在菜单中通过按“x”导航到菜单项。（使用‘&&’显示实际的和符号）。小部件可能会消耗和处理特定的快捷键。

另请参阅

iconText

访问函数
属性 toolTip: str#

此属性包含动作的工具提示。

此文本用于工具提示。如果没有指定工具提示，则使用动作的文本。

默认情况下，此属性包含动作的文本。

访问函数
属性 visible: bool#

此属性包含动作是否可见（例如在菜单和工具栏中）。

如果“visible”为 true，动作将可见（例如在菜单和工具栏中）并由用户选择；如果“visible”为 false，则动作不可见或不可选。

不可见的动作不会变灰；它们根本不会显示。

默认情况下，此属性为 true（动作是可见的）。

访问函数
属性 whatsThis: str#

该属性保存动作的“这是什么？”帮助文本。

“这是什么？”文本用于提供动作的简要描述。该文本可以包含富文本。没有默认的“这是什么？”文本。

另请参阅

QWhatsThis

访问函数
__init__(icon, text[, parent=None])#
参数：

使用图标、一些文本和父级构造动作。如果父级是动作组，则动作将自动插入到该组中。

除非您使用setToolTip()或setIconText()指定不同的文本，否则将使用文本的简化版本（例如，“&菜单选项…”将变为“菜单选项”）用于工具提示和图标文本。

另请参阅

text icon

__init__([parent=None])
参数：

parent – QObject

具有父级的动作构造函数。如果父级是动作组，则动作将自动插入该组。

注意

从Qt 5.7开始，父级参数是可选的。

__init__(text[, parent=None])
参数：

具有文本和父级的动作构造函数。如果父级是动作组，则动作将自动插入该组。

除非您使用setToolTip()或setIconText()指定不同的文本，否则将使用文本的简化版本（例如，“&菜单选项…”将变为“菜单选项”）用于工具提示和图标文本。

另请参阅

text

actionGroup()#
返回类型：

QActionGroup

返回该动作的动作组。如果没有动作组管理此动作，则返回None。

activate(event)#
参数：

event – ActionEvent

发送与 ActionEvent 事件相关的信号。

基于动作的控件使用此API来使 QAction 发出信号，并同时发出自己的信号。

associatedObjects()#
返回类型：

. 对象的列表 QObject

返回此动作已被添加到的对象的列表。

另请参阅

addAction()

autoRepeat()#
返回类型：

布尔值

另请参阅

setAutoRepeat()

属性 autoRepeatᅟ 的获取器。

changed()#

当动作发生变化时，会发出此信号。如果你只对给定小部件中的动作感兴趣，可以监听与 QEvent::ActionChanged 一起发送的 QWidget::actionEvent()。

另请参阅

actionEvent()

属性 iconᅟ 的通知信号。

checkableChanged(checkable)#
参数：

checkable – 布尔值

属性 checkableᅟ 的通知信号。

data()#
返回类型：

对象

返回在 setData 中设置的用户数据。

另请参阅

setData()

enabledChanged(enabled)#
参数：

enabled – 布尔值

属性 enabledᅟ 的通知信号。

font()#
返回类型：

QFont

另请参阅

setFont()

属性 fontᅟ 的获取器。

hover()#

这是一个便利槽，它调用 activate(Hover)。

hovered()#

当用户突出显示某个动作时，会发出此信号；例如，当用户将光标悬停在菜单选项、工具栏按钮或按动作的快捷键组合上时。

另请参阅

activate()

icon()#
返回类型：

QIcon

另请参阅

setIcon()

属性 icon 的获取器。

iconText()#
返回类型：

str

另请参阅

setIconText()

属性 iconText 的获取器。

isCheckable()#
返回类型：

布尔值

属性 checkable 的获取器。

isChecked()#
返回类型：

布尔值

属性 checked 的获取器。

isEnabled()#
返回类型：

布尔值

属性 enabled 的获取器。

isIconVisibleInMenu()#
返回类型：

布尔值

属性 iconVisibleInMenu 的获取器。

isSeparator()#
返回类型：

布尔值

如果此动作是分隔符动作，则返回 true；否则返回 false。

另请参阅

setSeparator()

isShortcutVisibleInContextMenu()
返回类型：

布尔值

属性 shortcutVisibleInContextMenu 的获取器。

isVisible()#
返回类型：

布尔值

属性 visible 的获取器。

menu()#
返回类型：

QObject

menuRole()#
返回类型：

MenuRole

另请参阅

setMenuRole（）

属性 menuRole 的获取器。

priority()#
返回类型：

Priority

另请参阅

setPriority（）

属性 priority 的获取器。

resetEnabled()#

属性 enabled 的重置函数。

setActionGroup(group)#
参数：

group – QActionGroup

将此操作组设置为 group。操作将被自动添加到组的动作列表中。

组内的操作将是互斥的。

另请参阅

QActionGroup 的 actionGroup

setAutoRepeat(arg__1)#
参数：

arg__1 – bool

另请参阅

autoRepeat()

属性 autoRepeat 的设置器。

setCheckable(arg__1)#
参数：

arg__1 – bool

另请参阅

isCheckable()

属性 checkable 的设置器。

setChecked(arg__1)#
参数：

arg__1 – bool

另请参阅

isChecked()

属性 checked 的设置器。

setData(var)#
参数：

var – object

将动作的内部数据设置为给定的 data。

另请参阅

data()

setDisabled(b)#
参数：

b – bool

这是一个为 enabled 属性提供的便利函数，它对信号-槽连接很有用。如果 b 为真，则操作将被禁用；否则它将启用。

setEnabled(arg__1)#
参数：

arg__1 – bool

另请参阅

isEnabled()

属性 enabledᅟ 的设置器。

setFont(font)#
参数：

font – QFont

另请参阅

font()

属性 fontᅟ 的设置器。

setIcon(icon)#
参数：

icon – QIcon

另请参阅

icon()

属性 iconᅟ 的设置器。

setIconText(text)#
参数：

text – str

另请参阅

iconText()

属性 iconTextᅟ 的设置器。

setIconVisibleInMenu(visible)#
参数：

visible – bool

另请参阅

isIconVisibleInMenu()

属性 iconVisibleInMenuᅟ 的设置器。

setMenu(arg__1)#
参数：

arg__1 – QObject

将此动作包含的菜单设置为指定的 menu。

另请参阅

menu()

setMenuRole(menuRole)#
参数：

menuRole – MenuRole

另请参阅

menuRole（）

属性 menuRoleᅟ 的设置器。

setPriority(priority)#
参数：

priority – Priority

另请参阅

priority（）

属性 priorityᅟ 的设置器。

setSeparator(b)#
参数：

b – bool

如果 b 为 true，则此操作将被视为分隔符。

分隔符的表示取决于它插入的部件。在大多数情况下，文本、子菜单和图标将忽略分隔符操作。

另请参阅

isSeparator()

函数 setShortcut(arg__1)#
参数：

arg__1 – Key

函数 setShortcut(shortcut)
参数：

shortcut – QKeySequence

设置 shortcut 为触发操作的唯一快捷键。

另请参阅

shortcut setShortcuts()

属性 shortcut 的设置器。

setShortcutContext(context)#
参数：

context – ShortcutContext

另请参阅

shortcutContext（）

属性 shortcutContext 的设置器。

setShortcutVisibleInContextMenu(show)#
参数：

show – bool

另请参阅

isShortcutVisibleInContextMenu（）

属性 shortcutVisibleInContextMenu 的设置器。

setShortcuts(arg__1)#
参数：

arg__1 – StandardKey

根据指定的 key 设置平台相关的快捷键列表。调用此函数的结果将取决于当前运行的平台。请注意，此操作可以分配多个快捷键。如果只需要主快捷键，请使用 setShortcut。

另请参阅

keyBindings()

setShortcuts(shortcuts)
参数：

shortcuts – .QKeySequence 列表

将 shortcuts 设置为触发操作的快捷键列表。列表的第一个元素是主快捷键。

setStatusTip(statusTip)#
参数：

statusTip – 字符串

另请参阅

statusTip()

属性 statusTip 的设置器。

setText(text)#
参数：

text – str

另请参阅

text()

属性 text 的设置器。

setToolTip(tip)#
参数：

tip – 字符串

另请参阅

toolTip()

属性 toolTip 的设置器。

setVisible(arg__1)#
参数：

arg__1 – bool

另请参阅

isVisible()

属性 visible 的设置器。

setWhatsThis(what)#
参数：

what – 字符串

另请参阅

whatsThis()

属性 whatsThis 的设置器。

shortcut()#
返回类型：

QKeySequence

返回主快捷键。

另请参阅

setShortcuts()

属性 shortcut 的获取器。

shortcutContext()#
返回类型：

ShortcutContext

另请参阅

setShortcutContext（）

属性 shortcutContext 的获取器。

shortcuts()#
返回类型：

. QKeySequence 的列表

返回快捷键列表，其中主快捷键为列表中的第一个元素。

另请参阅

setShortcuts()

showStatusText([object=None])#
参数：

object – QObject

返回类型：

布尔值

通过发送一个 QStatusTipEvent 更新由 object 表示的 UI 的相关状态栏。如果发送了事件，则返回 true，否则返回 false。

如果指定了空小部件，则事件发送到动作的父元素。

另请参阅

statusTip

statusTip()#
返回类型：

str

另请参阅

setStatusTip()

属性 statusTip属性 的获取器。

text()#
返回类型：

str

另请参阅

setText()

属性 text属性 的获取器。

toggle()#

这是一个方便函数，用于的 checked 属性。连接到此以将其检查状态切换为相反状态。

toggled(arg__1)#
参数：

arg__1 – bool

每当可检查的动作改变其 isChecked() 状态时，就会发出此信号。这可能是由用户交互或调用 setChecked() 所导致的结果。由于 setChecked() 改变了 QAction ，除了 toggled() ，它还会发出 changed() 。

checked 为真，如果动作被选中，如果动作未被选中则为假。

另请参阅

activate() triggered() checked

属性 checked属性 的通知信号。

toolTip()#
返回类型：

str

另请参阅

setToolTip()

属性 toolTip的属性 的获取器。

trigger()#

这是一个便捷槽，它调用 activate(触发器)。

triggered([checked=False])#
参数：

checked – bool

当用户激活操作时发出此信号，例如，当用户点击菜单选项、工具栏按钮或按操作的关键键组合，或者当调用 trigger() 时。值得注意的是，它不会在调用 setChecked() 或 toggle() 时发出。

如果操作可勾选，则当操作被勾选时 checked 为 true，或为未勾选时的 false。

另请参阅

activate() toggled() checked

visibleChanged()#

属性 visible的属性 的通知信号。

whatsThis()#
返回类型：

str

另请参阅

setWhatsThis()

属性 whatsThis的属性 的获取器。