【Qt】QToolBar、QToolButton的常用用法

一、QToolBar 常用用法

QToolBar 是 Qt 中用于创建工具栏的控件，可快速放置常用功能按钮、分隔符或自定义控件，并支持拖动停靠、浮动等特性。

1. 基础创建与添加到主窗口

// 在 QMainWindow 中创建工具栏
QToolBar *toolBar = new QToolBar(tr("主工具栏"), this);
addToolBar(toolBar); // 将工具栏添加到主窗口（默认停靠在顶部）

2. 添加动作（QAction）与控件

工具栏的核心元素是 QAction（可同时用于菜单和工具栏），也可直接添加自定义控件（如 QComboBox、QLineEdit）。

// 示例：添加“新建”“打开”动作 + 搜索框
QAction *actionNew = new QAction(tr("&New"), this);
QAction *actionOpen = new QAction(tr("&Open"), this);
toolBar->addAction(actionNew);   // 添加动作
toolBar->addAction(actionOpen);
toolBar->addSeparator();         // 添加分隔符

QLineEdit *searchBox = new QLineEdit();
searchBox->setPlaceholderText("搜索...");
toolBar->addWidget(searchBox);   // 添加自定义控件

3. 停靠与浮动控制

工具栏支持拖动到窗口的上、下、左、右区域，或脱离成为浮动窗口。

toolBar->setMovable(true);       // 允许拖动（默认 true）
toolBar->setFloatable(true);     // 允许浮动（默认 true）
toolBar->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea); // 仅允许停靠在顶部/底部

设置初始停靠位置

m_pMainToolBar = new QToolBar(tr("MainToolBar"), this); // 先new出QToolBar实例
this->addToolBar(Qt::LeftToolBarArea, m_pMainToolBar);  // 传入默认停靠位置 Qt::LeftToolBarArea

注意：工具栏停靠位置只能在主窗口 add时进行设置，后边无法通过编码更改初始停靠位置。

4. 外观定制

控制图标大小、按钮文本与图标的布局、方向等。

toolBar->setIconSize(QSize(24, 24));  // 图标大小
toolBar->setToolButtonStyle(Qt::ToolButtonTextUnderIcon); // 文本在图标下方
toolBar->setOrientation(Qt::Vertical); // 垂直排列（默认水平）

5. 信号与交互

响应工具栏动作的触发事件。

// 连接动作的 triggered 信号到槽函数
connect(actionOpen, &QAction::triggered, this, &MainWindow::openFile);

// 连接工具栏的 actionTriggered 信号（触发任意动作时发射）
connect(toolBar, &QToolBar::actionTriggered, this, &MainWindow::handleAction);

二、QToolButton 常用用法

QToolButton 是专为工具栏设计的按钮控件，比 QPushButton 更紧凑，支持图标、文本、下拉菜单、可切换状态等特性。

1. 基础创建与添加到工具栏

QToolButton *toolBtn = new QToolButton(this);
toolBtn->setIcon(QIcon(":/icons/save.png")); // 设置图标
toolBtn->setText("保存");                    // 设置文本
toolBar->addWidget(toolBtn);                 // 添加到工具栏

注意：toolButtonStyle 仅作用于工具栏自动生成的按钮（通过 addAction），手动添加的 QToolButton（addWidget）需自行管理样式。详细解释如下：

1.1 两种添加方法的关键区别：样式继承机制

• addAction 的按钮：
  • 工具栏内部为每个 QAction 生成一个 QToolButton，并将 toolButtonStyle（如 Qt::ToolButtonTextUnderIcon）强制应用到这些自动生成的按钮上。
  • 示例：

QAction* action = new QAction(QIcon("icon.png"), "按钮", this);

// 自动生成的 QToolButton 会继承 toolBar 的 toolButtonStyle
toolBar->addAction(action);  

• addWidget**的按钮 ：
  • 手动创建的 QToolButton（如 new QToolButton()）是独立控件，工具栏的 toolButtonStyle 不会自动作用于它。
  • 原因：这些按钮可能已自定义样式（如设置了专属的图标、文本布局），Qt 避免强制覆盖用户的自定义逻辑。
  • 示例：

QToolButton* btn = new QToolButton();
btn->setToolButtonStyle(Qt::ToolButtonIconOnly); // 自定义样式
toolBar->addWidget(btn); // 工具栏的 toolButtonStyle 不会影响此按钮 

• 如何让 addWidget 的按钮继承样式？

  若需手动添加的按钮（addWidget）也遵循工具栏的样式，需手动同步属性：

// 工具栏样式设置
toolBar->setToolButtonStyle(Qt::ToolButtonTextUnderIcon);

// 手动创建按钮并同步样式 QToolButton* customBtn = new QToolButton();
customBtn->setToolButtonStyle(toolBar->toolButtonStyle()); // 显式继承
toolBar->addWidget(customBtn); 

• 总结：
  • 通过 addWidget()方法手动添加的QToolButton需自行管理样式。
    • 适合快速创建统一风格的按钮（如标准的 “新建”“保存”），减少重复代码。
  • 不同的是，通过addAction()方法添加 QAction 动作，工具栏会自动创建 QToolButton，并绑定动作，按钮样式由工具栏的toolButtonStyle统一控制。
    • 适合复杂场景（如带下拉菜单的按钮、自定义组合控件），允许完全控制按钮样式。

2. 图标与文本布局

通过 Qt::ToolButtonStyle 控制图标和文本的显示方式。

toolBtn->setToolButtonStyle(Qt::ToolButtonTextUnderIcon); // 文本在图标下方
// 可选值：IconOnly（仅图标）、TextOnly（仅文本）、TextBesideIcon（文本在图标旁）等

3. 下拉菜单与弹出模式

QToolButton 可关联下拉菜单，支持三种弹出模式：

QMenu *menu = new QMenu(this);
menu->addAction("保存", this, &MainWindow::save);
menu->addAction("另存为", this, &MainWindow::saveAs);

toolBtn->setMenu(menu);
toolBtn->setPopupMode(QToolButton::MenuButtonPopup); // 右侧显示箭头，点击箭头弹出菜单
// 其他模式：InstantPopup（点击立即弹菜单）、DelayedPopup（长按弹菜单，默认）

4. 可切换状态（类似复选框）

设置为“可检查”模式后，按钮可保持“按下/释放”状态。

toolBtn->setCheckable(true); // 启用可检查状态
connect(toolBtn, &QToolButton::toggled, this, &MainWindow::toggleTool); // 连接切换信号

5. 自动提升与箭头样式

• 自动提升：鼠标悬停时按钮呈现 3D 凸起效果。
• 箭头样式：可显示箭头（替代图标）。

toolBtn->setAutoRaise(true);  // 启用自动提升（无边框，悬停时凸起）
toolBtn->setArrowType(Qt::DownArrow); // 显示下箭头（替代图标）

6. 设置提示

toolBtn->setToolTip(tr("这是系统设置按钮"));

鼠标停留在工具按钮上方，会有如下效果：

三、结合使用示例

将 QToolButton 与 QToolBar 配合，实现带下拉菜单的保存按钮：

QMainWindow window;
QToolBar *toolBar = new QToolBar(&window);
window.addToolBar(toolBar);

QToolButton *saveBtn = new QToolButton(&window);
saveBtn->setIcon(QIcon(":/save.png"));
saveBtn->setText("保存");
saveBtn->setToolButtonStyle(Qt::ToolButtonTextUnderIcon);

QMenu *saveMenu = new QMenu(&window);
saveMenu->addAction("保存", &window, []() { qDebug() << "保存文件"; });
saveMenu->addAction("另存为", &window, []() { qDebug() << "另存为..."; });

saveBtn->setMenu(saveMenu);
saveBtn->setPopupMode(QToolButton::MenuButtonPopup);

toolBar->addWidget(saveBtn);
window.show();

四、总结

• QToolBar：负责工具栏的整体容器管理，支持停靠、浮动、布局定制，通过 addAction()/addWidget() 填充内容。
• QToolButton：专注于工具栏内的按钮交互，支持图标、文本、下拉菜单、可切换状态等特性，是构建复杂工具栏的核心组件。

两者结合可实现灵活、专业的工具栏界面，提升用户操作效率。