Qt的QTreeWidge的使用

在 Qt 中，QTreeWidget 是一个用于显示树形结构数据的控件（基于项视图模型），常用于文件浏览器、目录结构、分类导航等场景。以下是关于 QTreeWidget 的全面解析，包括基本用法、样式设置、信号与槽、高级功能等。

1. 基本用法

创建并添加项

// 创建 QTreeWidget
QTreeWidget *treeWidget = new QTreeWidget(this);
treeWidget->setColumnCount(2); // 设置列数
treeWidget->setHeaderLabels({"Name", "Value"}); // 设置表头// 添加根节点
QTreeWidgetItem *rootItem = new QTreeWidgetItem(treeWidget);
rootItem->setText(0, "Root");
rootItem->setText(1, "Data");// 添加子节点
QTreeWidgetItem *childItem = new QTreeWidgetItem(rootItem);
childItem->setText(0, "Child");
childItem->setText(1, "123");
childItem->setCheckState(0, Qt::Unchecked); // 添加复选框// 展开所有项
treeWidget->expandAll();

常用方法

addTopLevelItem(QTreeWidgetItem*): 添加根节点。
currentItem(): 获取当前选中项。
clear(): 清空所有项。
setColumnWidth(int column, int width): 设置列宽。

2. 样式设置（QSS）

基础样式

treeWidget->setStyleSheet(R"(QTreeWidget {background: #ffffff;border: 1px solid #d3d3d3;border-radius: 4px;}QTreeWidget::item {height: 25px;padding: 2px;border: 1px solid transparent;}QTreeWidget::item:hover {background: #e6f3ff;border: 1px solid #cce0ff;}QTreeWidget::item:selected {background: #0078d4;color: white;}
)");

自定义分支图标

/* 折叠时的分支图标 */
QTreeWidget::branch:closed:has-children {image: url(:/icons/arrow-right.png);
}/* 展开时的分支图标 */
QTreeWidget::branch:open:has-children {image: url(:/icons/arrow-down.png);
}

表头样式

QHeaderView::section {background: #f8f8f8;padding: 4px;border: none;border-bottom: 2px solid #0078d4;
}

3. 信号与槽

常用信号

itemClicked(QTreeWidgetItem*, int column): 项被点击。
itemDoubleClicked(QTreeWidgetItem*, int column): 项被双击。
itemSelectionChanged(): 选中项变化。
itemExpanded(QTreeWidgetItem*): 项展开。
itemCollapsed(QTreeWidgetItem*): 项折叠。

示例：响应项点击

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

4. 高级功能

自定义项委托

通过 QStyledItemDelegate 自定义项的绘制逻辑（如进度条、图标组合）：

class CustomDelegate : public QStyledItemDelegate {
public:void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override {// 自定义绘制逻辑}
};// 设置委托
treeWidget->setItemDelegate(new CustomDelegate());

拖放支持

启用拖放操作：

treeWidget->setDragEnabled(true);
treeWidget->setDragDropMode(QAbstractItemView::InternalDrag);
treeWidget->setDropIndicatorShown(true);

数据绑定

结合 QStandardItemModel 或自定义模型实现动态数据加载（QTreeWidget 本身是 QTreeView 的简化封装）。

5. 性能优化

懒加载：展开父节点时动态加载子节点（通过 itemExpanded 信号触发）。
批量操作：使用 setUpdatesEnabled(false) 和 setUpdatesEnabled(true) 包裹批量添加/删除操作。
虚拟化：对于海量数据，改用 QTreeView + QFileSystemModel 等模型视图架构。

6. 常见问题

样式不生效

检查父控件的样式是否覆盖了子控件。

使用 !important 强制样式优先级：

QTreeWidget::item { color: red !important; }

图标显示异常

确保资源路径正确（:/icons/... 需在 Qt 资源文件中定义）。
使用绝对路径或 Qt 资源系统。

复选框状态同步

通过 itemChanged 信号监听复选框变化：

connect(treeWidget, &QTreeWidget::itemChanged, [](QTreeWidgetItem *item, int column) {if (column == 0) { // 假设复选框在第0列qDebug() << "Check state:" << item->checkState(0);}
});

7. 完整示例

一个简单的文件树浏览器：

QTreeWidget *treeWidget = new QTreeWidget(this);
treeWidget->setColumnCount(2);
treeWidget->setHeaderLabels({"Name", "Size"});// 模拟添加文件/文件夹
QTreeWidgetItem *root = new QTreeWidgetItem(treeWidget);
root->setText(0, "Documents");
root->setIcon(0, QIcon(":/icons/folder.png"));QTreeWidgetItem *file = new QTreeWidgetItem(root);
file->setText(0, "report.pdf");
file->setText(1, "2.5 MB");
file->setIcon(0, QIcon(":/icons/file.png"));treeWidget->expandAll();