正确写法是：先用new QTreeWidgetItem(treeWidget)或new QTreeWidgetItem(parent)创建节点，再显式调用addTopLevelItem()添加顶层节点，或addChild()添加子节点；若省略add操作，节点不会显示。
QTreeWidget 添加根节点和子节点的正确写法
直接 new QTreeWidgetItem(treeWidget) 创建的节点不会自动显示，必须显式调用 addTopLevelItem() 或 addChild() 才能进树结构。很多人卡在这一步，以为构造完就自动挂载了。
常见错误：写成 new QTreeWidgetItem(treeWidget); 后没加任何 add 操作，结果界面空空如也。
- 添加顶层节点：用
treeWidget->addTopLevelItem(new QTreeWidgetItem(QStringList() - 添加子节点：先获取父节点指针（比如
QTreeWidgetItem *parent = treeWidget->topLevelItem(0);），再调用parent->addChild(new QTreeWidgetItem(QStringList() - 注意：
addChild()只能对已有父子关系的节点调用；insertChild()可指定插入位置，适合动态排序场景
设置列数、表头和单元格内容的坑点
QTreeWidget 默认只有 1 列，不设列数或表头会导致 setText() 无效或只显示第一列。很多用户发现 setHeaderLabels() 没反应，其实是忘了调用 setColumnCount()。
- 必须先调用
treeWidget->setColumnCount(3);，再调用treeWidget->setHeaderLabels(QStringList() - 设置某行某列文本：用
item->setText(1, "文件夹");，索引从 0 开始，超出列数会静默失败 - 如果想让某列可编辑，需设置标志：
item->setFlags(item->flags() | Qt::ItemIsEditable);，否则双击不会弹出编辑框
响应点击/双击事件时为什么槽函数收不到信号？
默认情况下 itemClicked() 和 itemDoubleClicked() 只在用户真正点击到有文字的区域才触发，空白处、图标区、展开箭头都不算“点击 item”。更隐蔽的问题是：如果节点没有设置文本（setText() 为空字符串），即使点了也收不到信号。
- 确保每个
QTreeWidgetItem至少有一列设置了非空文本，例如item->setText(0, " ");（空格也行） - 推荐监听
itemSelectionChanged()配合selectedItems()，它对选中逻辑更稳定，尤其在多选模式下 - 如果用了自定义 delegate，要确认 delegate 的
editorEvent()没拦截掉鼠标事件，否则信号链会被截断
性能差？大数据量下卡顿怎么办
当节点超过 500 个，尤其是带图标、多列、嵌套深时，QTreeWidget 默认渲染效率明显下降——它不是为海量数据设计的，底层仍是基于 QWidget 的逐项绘制。
- 禁用动画和样式影响：调用
treeWidget->setAnimated(false);和treeWidget->setHeaderHidden(true);（如果不需要表头）能小幅提速 - 避免在循环中频繁调用
addTopLevelItem()，改用invisibleRootItem()->addChild()批量构建后一次性 attach - 真要处理上万节点？换
QTreeView + QStandardItemModel，后者支持惰性加载和更细粒度的刷新控制，QTreeWidget在这里只是语法糖，别硬扛
最常被忽略的是：节点对象本身持有大量额外数据（比如存了 QImage、QFile、QObject 子类）——这些不参与显示但占内存，也会拖慢 expand/collapse 动画。把业务数据剥离到外部 map 或 model 中，只在 item 上存 ID 或指针。
