Qt 學習之路 (40)：QTreeWidget 樹狀元件完整指南

編輯：關於C語言

繼上一篇介紹 QListWidget 後，本篇將帶領讀者認識另一個重要的 Item View 類別 —— QTreeWidget。顧名思義，它專門用於呈現樹狀結構資料。與 QListWidget 類似，QTreeWidget 需搭配輔助類別 QTreeWidgetItem 使用。雖然樹狀結構看似複雜，但透過這層封裝，開發者仍能以簡潔的程式碼快速建構樹狀介面；若不需要 QTreeView 進階特性，QTreeWidget 即為最佳選擇。

基本架構與標頭檔

#ifndef TREEWIDGET_H
#define TREEWIDGET_H

#include <QtGui>

class TreeWidget : public QWidget
{
public:
    TreeWidget();

private:
    QTreeWidget *tree;
};

#endif // TREEWIDGET_H

建立樹狀結構：逐步解析

TreeWidget::TreeWidget()
{
    tree = new QTreeWidget(this);
    tree->setColumnCount(1);                 // 設定單欄

    // 建立根節點
    QTreeWidgetItem *root = new QTreeWidgetItem(tree, QStringList(QString("Root")));

    // 建立子節點 Leaf 1
    QTreeWidgetItem *leaf = new QTreeWidgetItem(root, QStringList(QString("Leaf 1")));
    root->addChild(leaf);

    // 建立子節點 Leaf 2 並設為預設勾選
    QTreeWidgetItem *leaf2 = new QTreeWidgetItem(root, QStringList(QString("Leaf 1")));
    leaf2->setCheckState(0, Qt::Checked);
    root->addChild(leaf2);

    // 將根節點加入頂層項目清單
    QList<QTreeWidgetItem *> rootList;
    rootList << root;
    tree->insertTopLevelItems(0, rootList);
}

關鍵點說明

QTreeWidgetItem 建構子：最常用的多載為 QTreeWidgetItem(QTreeWidget *parent, const QStringList &strings, int type = Type)。第二個參數為 QStringList 而非 QString，是為了支援多欄顯示（每欄一個字串）。
父子關係：傳入 QTreeWidgetItem* 作為 parent 即建立父子層級；傳入 QTreeWidget* 則為頂層項目。
多根節點：insertTopLevelItems 接受 QList，允許樹狀元件擁有多個根節點（嚴格來說已非單一樹狀結構，但 Qt 仍以 TreeWidget 稱之）。

多欄進階：打造類似檔案總管的介面

將 setColumnCount(2) 並傳入雙元素 QStringList，即可實現「名稱/編號」雙欄顯示：

tree->setColumnCount(2);
QStringList headers;
headers << "Name" << "Number";
tree->setHeaderLabels(headers);

QStringList rootTextList;
rootTextList << "Root" << "0";
QTreeWidgetItem *root = new QTreeWidgetItem(tree, rootTextList);

QStringList leafTextList;
leafTextList << "Leaf 1" << "1";
QTreeWidgetItem *leaf = new QTreeWidgetItem(root, leafTextList);
root->addChild(leaf);
// ... 後續同單欄邏輯

執行結果將呈現雙欄表頭與對應資料，輕鬆實現 Windows 檔案總管風格的樹狀列表。若不需表頭，可呼叫 setHeaderHidden(true) 隱藏。