【Qt开发】多元素类控件（三）-＞ QTreeWidget

[1 -> 概述](#1 -> 概述)

[1.1 -> 核心概念：树与项](#1.1 -> 核心概念：树与项)

[2 -> 关于 QTreeWidget](#2 -> 关于 QTreeWidget)

[2.1 -> QTreeWidget 核心方法](#2.1 -> QTreeWidget 核心方法)

[2.2 -> QTreeWidget 核心信号](#2.2 -> QTreeWidget 核心信号)

[3 -> 关于 QTreeWidgetItem](#3 -> 关于 QTreeWidgetItem)

[3.1 -> QTreeWidgetItem 核心属性](#3.1 -> QTreeWidgetItem 核心属性)

[3.2 -> QTreeQWidget 核心方法](#3.2 -> QTreeQWidget 核心方法)

[4 -> 核心功能与特性](#4 -> 核心功能与特性)

[5 -> 典型应用场景](#5 -> 典型应用场景)

[6 -> 代码示例](#6 -> 代码示例)

[7 -> 总结](#7 -> 总结)

1 -> 概述

在Qt丰富的控件库中，QTreeWidget 是一个强大且灵活的多元素展示组件。它以其清晰的层级结构和直观的视觉表现，成为构建复杂用户界面的中坚力量。无论是用于文件浏览器、配置面板，还是数据分类展示，QTreeWidget 都能优雅地胜任。

1.1 -> 核心概念：树与项

理解QTreeWidget的关键在于把握其"树形结构"的核心思想。它就像我们电脑中的文件资源管理器，由根节点、分支节点和叶子节点构成。

树（Tree）：整个控件本身就是一个容器，承载着这棵"树"的所有内容。
项（Item） ：树中的每一个节点都是一个QTreeWidgetItem对象。项不仅可以显示文本，还可以承载图标、复选框、状态信息等多种元素。
层级关系：项与项之间通过父子关系建立层级。一个项（父项）可以包含零个或多个子项，从而形成展开或折叠的分支。没有父项的项则被视为顶层项（根项）。

这种层级模型使得QTreeWidget天生适合展示任何具有从属或分类关系的数据。

2 -> 关于 QTreeWidget

2.1 -> QTreeWidget 核心方法

|-------------------------------------------------|-------------------------------------------------|
| 方法 | 说明 |
| clear | 清空所有子节点 |
| addTopLevelItem(QTreeWidgetItem* item) | 新增顶层节点 |
| topLevelItem(int index) | 获取指定下标的顶层节点 |
| topLevelItemCount() | 获取顶层节点个数 |
| indexOfTopLevelItem(QTreeWidgetItem* item) | 查询指定节点是顶层节点中的下标 |
| takeTopLevelItem(int index) | 删除指定的顶层节点 返回 QTreeWidgetItem* 表示被删除的元素 |
| currentItem() | 获取到当前选中的节点，返回 QTreeWidgetItem* |
| setCurrentItem(QTreeWidgetItem* item) | 选中指定节点 |
| setExpanded(bool) | 展开/关闭节点 |
| setHeaderLabel(const QString& text) | 设置 TreeWidget 的 header 名称 |

2.2 -> QTreeWidget 核心信号

|--------------------------------------------------------------------------|---------------|
| 信号 | 说明 |
| currentItemChanged(QTreeWidgetItem* current, QTreeWIdgetItem* old) | 切换选中元素时触发 |
| itemClicked(QTreeWidgetItem* item, int col) | 点击元素时触发 |
| itemDoubleClicked(QTreeWidgetItem* item, int col) | 双击元素时触发 |
| itemEntered(QTreeWidgetItem* item, int col) | 鼠标进入时触发 |
| itemExpanded(QTreeWidgetItem* item) | 元素被展开时触发 |
| itemCollapsend(QTreeWidgetItem* item) | 元素被折叠时触发 |

3 -> 关于 QTreeWidgetItem

3.1 -> QTreeWidgetItem 核心属性

|-------------------|------------|
| 属性 | 说明 |
| text | 持有的文本 |
| textAlignment | 文本对齐方式 |
| icon | 持有的图表 |
| font | 文本字体 |
| hidden | 是否隐藏 |
| disabled | 是否禁用 |
| expand | 是否展开 |
| sizeHint | 尺寸大小 |
| selected | 是否选中 |

3.2 -> QTreeQWidget 核心方法

|------------------------------------------|-----------------------------------------|
| 方法 | 说明 |
| addChild(QTreeWidgetItem* child) | 新增子节点 |
| childCount() | 子节点的个数 |
| child(int index) | 获取指定下标的子节点 返回 QTreeWidgetItem* |
| takeChild(int index) | 删除对应下标的子节点 |
| removeChild(QTreeWidgetItem* child) | 删除对应的子节点 |
| parent() | 获取该元素的父节点 |

4 -> 核心功能与特性

QTreeWidget的强大之处在于它提供了一套完整的功能集，让开发者能够轻松实现复杂的交互需求。

多列支持
与简单的列表不同，QTreeWidget支持多列（或称多栏）显示。每一列都可以有自己的标题，形成一个微型的表格树。这使得单个项可以同时展示多种相关信息。例如，在一个文件管理器中，第一列显示文件名，第二列显示文件大小，第三列显示修改日期，而树形结构则通过第一列的缩进来体现。
丰富的项内容
每个QTreeWidgetItem都是一个信息的容器：
- 文本与图标：可以为每一列设置不同的文本和图标，使界面更加生动。
- 复选框：项可以自带复选框，方便用户进行多项选择或状态设置，无需额外添加控件。
- 状态图标：可以自定义项在不同状态（如展开、折叠、被选中）下显示的图标。
交互与编辑
- 选择模式：控件提供了灵活的选择模式，可以设置为单选、多选、扩展选择等，以适应不同的应用场景。
- 排序：支持按任意列进行升序或降序排序，用户只需点击列标题即可。开发者也可以自定义排序规则。
- 项编辑：可以设置项为可编辑模式，允许用户双击（或通过特定操作）直接修改项的文本内容。
- 拖拽操作 ： QTreeWidget内置了对拖拽（Drag & Drop）的支持。开发者可以启用项的内部拖拽、跨控件拖拽，并精确控制拖拽的行为和效果，这对于实现诸如重新组织项目列表或文件移动等功能至关重要。
信号与槽
Qt的信号与槽机制在QTreeWidget中得到了充分应用。当用户与树控件交互时，它会发出各种信号，例如：项被单击、双击、展开、折叠、选择改变、内容被编辑等。开发者可以连接这些信号到自定义的槽函数，从而实时响应用户操作，更新程序状态或执行其他逻辑。

5 -> 典型应用场景

QTreeWidget的适用场景非常广泛：

文件系统浏览器：最经典的例子，完美展示目录和文件的层级关系。
配置对话框：将设置选项按功能分类，组织成树形结构，用户可逐级深入查找和修改。
数据分类展示：如产品分类、组织结构图、图书目录等，任何需要按类别逐级细分的场景。
项目大纲或导航面板：在IDE或复杂软件中，用作项目文件导航或功能模块的快速切换。

6 -> 代码示例

1. 在界面上创建一个 TreeView，右键 -> 变形为 -> TreeWidget，再创建一个 lineEdit 和两个 pushButton

注意：TreeWidget 是 TreeView 的子类，功能比 TreeView 更丰富

2. 编写代码，构造初始数据

cpp 复制代码

#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    // 设置根节点名称
    ui->treeWidget->setHeaderLabel("One Piece");

    // 设置顶层节点
    QTreeWidgetItem* item1 = new QTreeWidgetItem();
    item1->setText(0, "海贼");
    // 添加到顶层节点
    ui->treeWidget->addTopLevelItem(item1);

    // 设置顶层节点
    QTreeWidgetItem* item2 = new QTreeWidgetItem();
    item2->setText(0, "革命军");
    // 添加到顶层节点
    ui->treeWidget->addTopLevelItem(item2);

    // 设置顶层节点
    QTreeWidgetItem* item3 = new QTreeWidgetItem();
    item3->setText(0, "海军");
    // 添加到顶层节点
    ui->treeWidget->addTopLevelItem(item3);

    // 添加子节点
    QTreeWidgetItem* item4 = new QTreeWidgetItem();
    item4->setText(0, "草帽海贼团");
    item1->addChild(item4);

    QTreeWidgetItem* item5 = new QTreeWidgetItem();
    item5->setText(0, "红发海贼团");
    item1->addChild(item5);

    QTreeWidgetItem* item6 = new QTreeWidgetItem();
    item6->setText(0, "黑胡子海贼团");
    item1->addChild(item6);

    QTreeWidgetItem* item7 = new QTreeWidgetItem();
    item7->setText(0, "龙");
    item2->addChild(item7);

    QTreeWidgetItem* item8 = new QTreeWidgetItem();
    item8->setText(0, "萨博");
    item2->addChild(item8);

    QTreeWidgetItem* item9 = new QTreeWidgetItem();
    item9->setText(0, "赤犬");
    item3->addChild(item9);

    QTreeWidgetItem* item10 = new QTreeWidgetItem();
    item10->setText(0, "黄猿");
    item3->addChild(item10);

    QTreeWidgetItem* item11 = new QTreeWidgetItem();
    item11->setText(0, "绿牛");
    item3->addChild(item11);

}

Widget::~Widget()
{
    delete ui;
}

3. 编写代码，实现按钮的 slot 函数

cpp 复制代码

void Widget::on_pushButton_insertTopLevelItem_clicked()
{
    // 获取到输入框中的内容
    const QString text = ui->lineEdit->text();

    // 构造一个 QTreeWidgetItem
    QTreeWidgetItem* item = new QTreeWidgetItem();
    item->setText(0, text);

    // 添加到顶层节点中
    ui->treeWidget->addTopLevelItem(item);

}

void Widget::on_pushButton_insertItem_clicked()
{
    // 获取到当前选中的节点
    QTreeWidgetItem* curItem = ui->treeWidget->currentItem();
    if (curItem == nullptr)
    {
        return ;
    }

    // 获取到输入框的内容
    const QString text = ui->lineEdit->text();

    // 构造一个 QTreeWidgetItem
    QTreeWidgetItem* item = new QTreeWidgetItem();
    item->setText(0, text);

    // 插入到选中节点的子节点中
    curItem->addChild(item);

}


void Widget::on_pushButton_deleteItem_clicked(){
    // 获取到选中的元素
    QTreeWidgetItem* curItem = ui->treeWidget->currentItem();
    if (curItem == nullptr)
    {
        return ;
    }

    // 删除选中的元素, 需要先获取到父元素, 通过父元素进行删除
    QTreeWidgetItem* parent = curItem->parent();
    if (parent == nullptr)
    {
        // 顶层元素
        int index = ui->treeWidget->indexOfTopLevelItem(curItem);
        ui->treeWidget->takeTopLevelItem(index);
    }
    else
    {
        // 普通元素
        parent->removeChild(curItem);
    }


}

4. 执行程序，可以针对树形框进行编辑

7 -> 总结

QTreeWidget是Qt工具包中一个功能全面、上手迅速的重量级控件。它通过树形结构和多列支持，为展示和操作层级数据提供了直观的解决方案。其内置的排序、编辑、复选框和拖拽功能，极大地减少了开发者的工作量。尽管在面对超大规模数据时有其局限性，但在绝大多数桌面应用程序的界面设计中，QTreeWidget凭借其易用性和灵活性，依然是构建清晰、高效用户界面的不二之选。

感谢各位大佬支持！！！

互三啦！！！