QPushButton Class
QPushButton 控件提供了一个命令按钮。更多内容...
| 头文件： | #include <QPushButton> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QAbstractButton |
| 被继承者： |
属性
- autoDefault : bool
- default : bool
- flat : bool
公共函数
| QPushButton(QWidget *parent = nullptr) | |
| QPushButton(const QString &text, QWidget *parent = nullptr) | |
| QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr) | |
| virtual | ~QPushButton() |
| bool | autoDefault() const |
| bool | isDefault() const |
| bool | isFlat() const |
| QMenu * | menu() const |
| void | setAutoDefault(bool) |
| void | setDefault(bool) |
| void | setFlat(bool) |
| void | setMenu(QMenu *menu) |
重新实现的公共函数
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
公共槽
| void | showMenu() |
受保护函数
| virtual void | initStyleOption(QStyleOptionButton *option) const |
重新实现的受保护函数
| virtual bool | event(QEvent *e) override |
| virtual void | focusInEvent(QFocusEvent *e) override |
| virtual void | focusOutEvent(QFocusEvent *e) override |
| virtual bool | hitButton(const QPoint &pos) const override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
详细说明
按钮（或称命令按钮）可能是任何图形用户界面中使用最广泛的控件。按下（单击）按钮可命令计算机执行某项操作，或对某个问题作出回应。典型的按钮包括“确定”、“应用”、“取消”、“关闭”、“是”、“否”和“帮助”。
命令按钮呈矩形，通常显示一个描述其操作的文本标签。若要在文本中指定快捷键，只需在目标字符前添加一个“&”符号即可。例如：
QPushButton *button = new QPushButton("&Download", this);在此示例中，快捷键为Alt+D。详情请参阅QShortcut 文档（若要显示实际的“&”符号，请使用“&&”）。
按压按钮会显示一个文本标签，并可选地显示一个小图标。这些属性可通过构造函数设置，并可在后续使用setText() 和setIcon() 进行修改。如果按钮处于禁用状态，文本和图标的外观将根据 GUI 样式进行调整，以使按钮呈现“禁用”状态。
当按钮被鼠标、空格键或键盘快捷键激活时，会发出clicked() 信号。连接此信号以执行按钮的操作。按钮还提供一些较少使用的信号，例如pressed() 和released()。
connect(dispenseButton, &QPushButton::clicked, this, &IceCreamMaker::dispense);对话框中的命令按钮默认是自动默认按钮，即当它们获得键盘输入焦点时，会自动成为默认按钮。 默认按钮是指当用户在对话框中按下 Enter 或 Return 键时会被激活的按钮。您可以通过setAutoDefault() 来更改此设置。请注意，自动默认按钮会预留出一点额外空间，这是绘制默认按钮指示符所必需的。如果您不希望按钮周围有此空间，请调用setAutoDefault(false)。
由于其核心地位，按钮控件在过去十年中不断发展，以适应多种多样的变化。微软风格指南目前展示了 Windows 按钮的约十种不同状态，而从文本描述来看，若将所有功能组合考虑在内，其状态数量可能还有数十种之多。
最重要的模式或状态包括：
- 是否可用（灰显、禁用）。
- 标准按钮、切换按钮或菜单按钮。
- 开启或关闭（仅适用于切换式按钮）。
- 默认或正常状态。对话框中的默认按钮通常可通过按下 Enter 或 Return 键来“单击”。
- 是否自动重复。
- 是否被按下。
一般而言，当应用程序或对话框窗口在用户单击时执行某项操作（例如“应用”、“取消”、“关闭”和“帮助”），以及当控件应具有宽阔的矩形形状并带有文本标签时，应使用按钮。 那些体积较小、通常为正方形、仅用于改变窗口状态而非执行操作的按钮（例如QFileDialog 右上角的按钮），不属于命令按钮，而是工具按钮。Qt 为这些按钮提供了一个专门的类（QToolButton ）。
如果您需要切换行为（参见setCheckable()），或者需要一个在按下时自动重复激活信号的按钮（如滚动条中的箭头，参见setAutoRepeat()），那么命令按钮可能并不适合您的需求。如有疑问，请使用工具按钮。
注意：在 macOS上 ，当按压按钮的宽度小于 50 或高度小于 30 时，按钮的圆角会变为直角。请使用setMinimumSize() 函数来防止这种行为。
菜单按钮是命令按钮的一种变体。它们不仅提供一个命令，而是多个命令，因为点击时会弹出一个选项菜单。使用setMenu() 方法将弹出菜单与按钮关联起来。
其他类型的按钮包括选项按钮（参见QRadioButton ）和复选框（参见QCheckBox ）。
在 Qt 中，基类 `QAbstractButton ` 提供了大多数模式和其他 API，而 `QPushButton` 则提供了 GUI 逻辑。有关 API 的更多信息，请参阅QAbstractButton 。
另请参阅 QToolButton 、QRadioButton 以及QCheckBox 。
属性文档
autoDefault : bool
该属性用于指定该按钮是否为自动默认按钮
如果该属性设置为 true，则该按钮为自动默认按钮。
在某些 GUI 样式中，默认按钮周围会绘制一个额外的边框，宽度最多为 3 像素或更多。Qt GUI 会自动在自动默认按钮周围保留这一空间，也就是说，自动默认按钮的尺寸提示可能会略大一些。
对于父对象为QDialog 的按钮，此属性的默认值为true；否则，默认值为false。
有关“default ”与“auto-default”如何交互的详细信息，请参阅default 属性。
访问函数：
| bool | autoDefault() const |
| void | setAutoDefault(bool) |
default : bool
该属性用于指定该按钮是否为默认按钮
默认按钮和自动默认按钮决定了用户在对话框中按下回车键时会发生什么。
当此属性设置为 true 的按钮（即对话框的默认按钮）在用户按下回车键时会自动被选中，但有一种例外情况：如果当前焦点位于“autoDefault ”按钮上，则会选中“autoDefault ”按钮。 当对话框包含autoDefault 按钮但没有默认按钮时，按下回车键将触发当前拥有焦点的autoDefault 按钮；如果没有任何按钮拥有焦点，则触发焦点链中下一个autoDefault 按钮。
在对话框中，每次只能有一个按钮作为默认按钮。该按钮将显示一个额外的边框（具体取决于 GUI 样式）。
默认按钮的行为仅在对话框中提供。当按钮获得焦点时，始终可以通过按空格键从键盘点击该按钮。
如果在对话框可见时，将当前默认按钮的 default 属性设置为 false，则下次对话框中的某个按钮获得焦点时，系统会自动指定一个新的默认按钮。
该属性的默认值为 false。
访问函数：
| bool | isDefault() const |
| void | setDefault(bool) |
flat : bool
该属性控制按钮边框是否呈凸起状
该属性的默认值为 false。如果设置了此属性，大多数样式在按钮未被按下时不会绘制按钮背景。可使用 `setAutoFillBackground()` 确保使用 `QPalette::Button ` 画笔填充背景。
访问函数：
| bool | isFlat() const |
| void | setFlat(bool) |
成员函数文档
[explicit] QPushButton::QPushButton(QWidget *parent = nullptr)
创建一个无文本且具有parent 的按钮。
[explicit] QPushButton::QPushButton(const QString &text, QWidget *parent = nullptr)
创建一个按钮，其父元素为parent ，文本为text 。
QPushButton::QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr)
创建一个带有icon 、text 和parent 的按钮。
请注意，您还可以将QPixmap 对象作为图标传入（得益于C++提供的隐式类型转换）。
[virtual noexcept] QPushButton::~QPushButton()
破坏了按钮。
[override virtual protected] bool QPushButton::event(QEvent *e)
重写了：QAbstractButton::event(QEvent *e)。
[override virtual protected] void QPushButton::focusInEvent(QFocusEvent *e)
重写了：QAbstractButton::focusInEvent(QFocusEvent *e)。
[override virtual protected] void QPushButton::focusOutEvent(QFocusEvent *e)
重写了：QAbstractButton::focusOutEvent(QFocusEvent *e)。
[override virtual protected] bool QPushButton::hitButton(const QPoint &pos) const
重写了：QAbstractButton::hitButton(const QPoint &pos) const。
[virtual protected] void QPushButton::initStyleOption(QStyleOptionButton *option) const
使用QPushButton 中的值初始化option 。当子类需要一个QStyleOptionButton 时，但又不希望自己填写所有信息，此方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual protected] void QPushButton::keyPressEvent(QKeyEvent *e)
重写了：QAbstractButton::keyPressEvent(QKeyEvent *e)。
QMenu *QPushButton::menu() const
返回该按钮关联的弹出菜单；如果未设置弹出菜单，则返回nullptr 。
另请参阅 setMenu()。
[override virtual] QSize QPushButton::minimumSizeHint() const
重新实现了属性QWidget::minimumSizeHint 的访问函数。
[override virtual protected] void QPushButton::mouseMoveEvent(QMouseEvent *e)
重写了：QAbstractButton::mouseMoveEvent(QMouseEvent *e)。
[override virtual protected] void QPushButton::paintEvent(QPaintEvent *)
重写了：QAbstractButton::paintEvent(QPaintEvent *e)。
void QPushButton::setMenu(QMenu *menu)
将弹出菜单“menu ”与该按钮关联。这会将该按钮转换为菜单按钮，在某些样式下，按钮文字右侧会显示一个小三角形。
菜单的所有权不会转移给该按钮。
采用Fusion 小部件样式的带弹出菜单的按钮。
另请参阅 menu()。
[slot] void QPushButton::showMenu()
显示（弹出）相应的弹出菜单。如果不存在此类菜单，则该函数不执行任何操作。在用户关闭弹出菜单之前，该函数不会返回。
[override virtual] QSize QPushButton::sizeHint() const
重新实现了属性QWidget::sizeHint 的访问函数。
© 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.
