Qt QTreeWidget 总结

1. 概述

• QTreeWidget 是 Qt 中用于显示树形结构的控件，继承自 QTreeView，但提供了更简单的接口。
• 适合展示层级数据（如文件目录、组织结构）。
• 每个节点是 QTreeWidgetItem 对象，支持文本、图标、复选框等。

---

2. 基本使用

创建与初始化

QTreeWidget *treeWidget = new QTreeWidget(parent);
treeWidget->setColumnCount(2); // 设置列数
treeWidget->setHeaderLabels({"Name", "Type"}); // 设置表头

添加项

// 添加顶层项
QTreeWidgetItem *topItem = new QTreeWidgetItem(treeWidget);
topItem->setText(0, "Root");
topItem->setIcon(0, QIcon(":/icon.png"));

// 添加子项
QTreeWidgetItem *childItem = new QTreeWidgetItem(topItem);
childItem->setText(0, "Child");
childItem->setCheckState(0, Qt::Checked); // 复选框

---

3. 常用方法

方法	描述
addTopLevelItem(QTreeWidgetItem*)	添加顶层项
insertTopLevelItem(int, QTreeWidgetItem*)	插入顶层项到指定位置
takeTopLevelItem(int)	移除并返回顶层项
currentItem()	获取当前选中项
expandItem(QTreeWidgetItem*)	展开节点
collapseItem(QTreeWidgetItem*)	折叠节点
setItemWidget(QTreeWidgetItem*, int, QWidget*)	为项添加自定义控件（如按钮）

遍历项

QTreeWidgetItemIterator it(treeWidget);
while (*it) {
    qDebug() << (*it)->text(0);
    ++it;
}

---

4. 信号与槽

• 常用信号：
  • itemClicked(QTreeWidgetItem*, int)：点击项触发。
  • itemDoubleClicked(QTreeWidgetItem*, int)：双击项触发。
  • itemChanged(QTreeWidgetItem*, int)：项内容变化触发（如复选框状态）。

示例：响应点击事件

connect(treeWidget, &QTreeWidget::itemClicked, [](QTreeWidgetItem *item, int column) {
    qDebug() << "Clicked:" << item->text(column);
});

---

5. 样式与定制

使用 QSS 美化

treeWidget->setStyleSheet(
    "QTreeWidget { background: #f0f0f0; }"
    "QTreeWidget::item:hover { background: yellow; }"
    "QTreeWidget::item:selected { background: blue; color: white; }"
);

自定义项外观

QTreeWidgetItem *item = new QTreeWidgetItem();
item->setForeground(0, QBrush(Qt::red)); // 设置文本颜色
item->setBackground(1, QBrush(Qt::lightGray)); // 设置背景色

---

6. 完整示例

QTreeWidget *treeWidget = new QTreeWidget();
treeWidget->setColumnCount(2);
treeWidget->setHeaderLabels({"Name", "Value"});

// 添加顶层项
QTreeWidgetItem *root = new QTreeWidgetItem(treeWidget);
root->setText(0, "Settings");
root->setExpanded(true); // 默认展开

// 添加子项
QTreeWidgetItem *child = new QTreeWidgetItem(root);
child->setText(0, "Language");
child->setText(1, "English");

// 响应双击
connect(treeWidget, &QTreeWidget::itemDoubleClicked, [](QTreeWidgetItem *item, int col) {
    QMessageBox::information(nullptr, "Info", item->text(col));
});

treeWidget->show();

---

7. 高级功能

• 拖放操作：通过重写 dragEnterEvent 和 dropEvent 实现。
• 排序：treeWidget->setSortingEnabled(true);
• 自定义委托：继承 QStyledItemDelegate 实现复杂渲染或编辑。

---

8. 总结

• 适用场景：快速实现树形结构展示，适合简单层级数据。
• 性能注意：数据量过大时建议使用 QTreeView + QFileSystemModel 等模型/视图架构。
• 扩展性：通过信号/槽和样式表灵活定制交互与外观。