一、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：專注于工具欄內的按鈕交互，支持圖標、文本、下拉菜單、可切換狀態等特性，是構建復雜工具欄的核心組件。

兩者結合可實現靈活、專業的工具欄界面，提升用戶操作效率。