【Qt6】列表模型——几个便捷的列表类型

前面一些文章，老周简单介绍了在Qt 中使用列表模型的方法。很明显，使用 Item Model 在许多时候还是挺麻烦的------要先建模型，再放数据，最后才构建视图。为了简化这些骚操作，Qt 提供了几个便捷类。今天咱们逐个看看。

一、QListWidget

这厮对应的 List View，用来显示简单的列表。要添加列表项，此类有两个方法

void addItem(const QString &label) ;
void addItem(QListWidgetItem *item);

void addItems(const QStringList &labels);

前两个方法是调用一次就添加一个列表项，新加的列表项将追加到列表末尾；addItems 方法是一次性添加多个项，以字符串列表的方式添加。

对于简单的列表项，可以用第一个方法，直接传个字符串就完事了。第二个方法需要一个 QListWidgetItem 对象，它可以对列表项做一些其他设置，如放个图标，文本对齐方式等。当然，如果你不想用追加模式添加列表项，也可以用插入方法：

void insertItem(int row, const QString &label);
void insertItem(int row, QListWidgetItem *item);
void insertItems(int row, const QStringList &labels);

和 addItem 方法一样，但多了一个 row 参数。因为简单的列表模型只有一个列，所以 row 就是子项的索引。索引从 0 起计算，指定 row 参数表示在此处插入列表项，而列表中原有的元素会向后移一位。比如 5、6、7，在row=1 处插入9，即列表变成 5、9、6、7。

要删除列表项，调用 takeItem 方法。

QListWidgetItem* takeItem(int row)

调用后，指定索引处的项被移除，并返回该项的实例引用（指针类型）。不要调用 removeItemWidget 方法，那个只删除用于显示列表项的组件罢了，列表项并未真正删除。

下面咱们动动手，做个练习。

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    // 实例化组件
    QListWidget *view = nullptr;
    view = new QListWidget;
    // 窗口标题
    view->setWindowTitle("烧烤档常见食物");
    // 窗口大小
    view->resize(255, 200);
    // 添加点子项
    view->addItem("烤羊肺");
    view->addItem("烤年糕");
    // 选创建QListWidgetItem实例，再添加
    QListWidgetItem* item = new QListWidgetItem("烤狗腿");
    view->addItem(item);// 也可以用字符串列表
    QStringList strs;
    strs << "臭豆腐" << "烤鸭肉" << "烤鸡翅";
    view->addItems(strs);

    // 显示窗口
    view->show();
    // 进入事件循环
    return QApplication::exec();
}

第一、二项直接用字符串添加列表项；第三项是先创建 QListWidgetItem 实例，然后再添加；第四、五、六项是通过字符串列表一次性添加的。QStringList 其实就是 QList<QString> 类。

效果如下图所示：

前面我们提到过一个 removeItemWidget 方法。提到它就得提一下 setItemWidget 方法，因为这俩是青梅竹马的。这一对方法的作用是为某个列表项添加（或删除）一个自定义组件（QWidget 或其子类）。被添加的组件会显示在该列表项上面------其实是覆盖在原有内容上面的。这个方法虽然方便我们为列表项定制 UI，但它不支持动态行为，比如，你如果加一个文本框用来编辑数据，编辑好后数据是不会自动保存的，所有的逻辑都要你自己写代码实现。

咱们拿上面的示例开刀，为最后三项加入个按钮，看看会怎样。代码修改如下：

// 获取最后三项的引用
int len = view->count();  // 猜猜它返回什么
QListWidgetItem* tmpItem1 = view->item(len - 3);
QListWidgetItem* tmpItem2 = view->item(len - 2);
QListWidgetItem* tmpItem3 = view->item(len - 1);
// 弄三个按钮
QPushButton* b1 = new QPushButton;
b1->setText("A");
QPushButton* b2= new QPushButton;
b2->setText("B");
QPushButton* b3 = new QPushButton;
b3->setText("C");
// 调整一下列表项的高度，不然按钮可能显示不全
QSize size(0, 32);
tmpItem1->setSizeHint(size);
tmpItem2->setSizeHint(size);
tmpItem3->setSizeHint(size);
// 设置三个按钮与三个列表项关联
view->setItemWidget(tmpItem1, b1);
view->setItemWidget(tmpItem2, b2);
view->setItemWidget(tmpItem3, b3);
// 为了能发现其中的秘密，咱们让按钮的宽度缩小一点
b1->setFixedWidth(25);
b2->setFixedWidth(25);
b3->setFixedWidth(25);

setSizeHint 方法为项目的"期望"大小设置一个固定的高度，宽度为0表示由布局行为决定；而 32 是高度，告诉容器组件："我需要32的高度"，毕竟默认的高度可能显示不全按钮。最后，我用 setFixedWidth 方法把三个按钮的宽度给固死了，它的宽度只能是25像素。这么做是为了让大伙看清楚，我们自定义的组件其实就是显示在原有列表项上面的。如下图，你看看，原列表项的文本还在呢。

不过，上述代码只是方便理解，没什么实际用处。下面咱们做有用的，重新做一下这个示例。

view->connect(view, &QListWidget::currentItemChanged, [=]
(QListWidgetItem* current, QListWidgetItem* previous) -> void{
    // 删除前一个列表项所关联的QWidget
    if(previous)
    {
        view->removeItemWidget(previous);
        // 还原列表项高度
        previous->setSizeHint(QSize(-1, -1));
    }
    // 如当前项为NULL，那后面的代码就没必要运行了
    if(!current){
        return;
    }
    // 为当前项创建QWidget
    QWidget* wg = new QWidget;
    // 设置背景色
    wg->setAutoFillBackground(true);
    wg->setStyleSheet("background: lightgray");
    // 布局
    QHBoxLayout* layout=new QHBoxLayout;
    wg->setLayout(layout);
    // 标签
    QLabel* lb=new QLabel;
    // 标签的文本就是列表项的文本
    lb->setText(current->text());
    layout->addWidget(lb);
    // 加个空白，填补剩余空间
    layout->addStretch(1);
    // 按钮
    QPushButton* btn= new QPushButton("删除");
    layout->addWidget(btn);
    // 套娃，又一个信号连接
    QObject::connect(btn, &QPushButton::clicked, [=](){
        // 当前索引
        int row = view->row(current);
        // 把当前列表项分离出来
        QListWidgetItem* _oldItem = view->takeItem(row);
        // 清除它
        delete _oldItem;
    });
    // 要改一下列表项的高度，不然按钮可能显示不全
    current->setSizeHint(QSize(0, 40));
    // 关联列表项与组件
    view->setItemWidget(current, wg);
});

这里实现的逻辑是：当列表项被选中才显示按钮。现在咱们也知道，setItemWidget 是创建一个自定义组件覆盖在列表项上的，所以，在列表项选中后，显示的自定义组件的背景不能透明，不然就穿帮了。组件里面放一个QLabel 组件显示列表项的文本，然后再放一个"删除"按钮，这样就差不多了。

需要用到 QListWidget 的一个信号：

void currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous);

这个信号正符合咱们的需求，current 表示当前项（99.9% 的情况下就是被选中的项），previous 是前一个项------即被取消选择的项。有了这两个参数，咱们就可以用 removeItemWidget 方法删除 previous 关联的 Widget，并为 current 关联新的 Widget。

currentItemChanged 信号连接的 lambda 表达式内部又嵌套了一个 lambda 表达式------ 连接按钮的 clicked 信号。

QObject::connect(btn, &QPushButton::clicked, [=](){
    // 当前索引
    int row = view->row(current);
    // 把当前列表项分离出来
    QListWidgetItem* _oldItem = view->takeItem(row);
    // 清除它
    delete _oldItem;
});

删除列表项时，takeItem 方法返回指定索引处的列表项指针。正因为这货需要的参数是索引，所以不得不调用 row 方法选获取 current 的索引，再传给 takeItem 方法。列表项被移除后会返回其指针，因为这时候我们不需要它了，所以得 delete 掉其指向的对象。

运行程序后，选中"臭豆腐"。

然后单击右边的"删除"按钮，臭豆腐就没了。

二、QTableWidget

QTableWidget 类派生自 QTableView，也是一个便捷类，可以不创建模型对象而直接添加数据。对应的列表项类型是 QTableWidgetItem。注意，一个 QTableWidgetItem 仅表示一个单元格的数据，所以，如果数据表格有两行两列，那么，你得向里面四个 item。

在添加列表项之前，要先调用：

setRowCount------ 设置表格共有几行；

setColumnCount------ 设置表格共有多少列。

然后设置标题。包括列标题、行标题。一般设置列标题就可以了，行标题通常不用设置（默认显示行号）。

setHorizontalHeaderLabels------ 设置列标题；

setVerticalHeaderLabels------ 设置行标题。

不管是行还是列标题，都可以使用字符串列表（QStringList）来传递，有几行/列就设置几个值。

设置完上述基本参数后，就可以用 setItem 方法来设置每个单元格的数据了。方法原型如下：

void setItem(int row, int column, QTableWidgetItem *item);

row 表示行索引，column 表示列索引，索引从 0 算起。

接下来咱们做个演示：

int main(int argc, char* argv[])
{
    QApplication app(argc, argv);
    // 创建组件实例
    QTableWidget* viewWindow = new QTableWidget;
    // 设置标题和大小
    viewWindow->setWindowTitle("经典语录");
    viewWindow->resize(350, 270);
    // 设定行数和列数
    viewWindow->setColumnCount(3);  // 三列
    viewWindow->setRowCount(4);     // 四行
    // 先弄好列标题
    viewWindow->setHorizontalHeaderLabels({"编号", "句子", "伤害指数"});
    // 创建列表项
    // 注意，每个QTableWidgetItem代表一个单元格
    // 第一行
    viewWindow->setItem(0, 0, new QTableWidgetItem("001"));
    viewWindow->setItem(0, 1, new QTableWidgetItem("你就长这个样子啊？"));
    viewWindow->setItem(0, 2, new QTableWidgetItem("2"));
    // 第二行
    viewWindow->setItem(1, 0, new QTableWidgetItem("002"));
    viewWindow->setItem(1, 1, new QTableWidgetItem("你进化到灵长目动物了吗？"));
    viewWindow->setItem(1, 2, new QTableWidgetItem("3"));
    // 第三行
    viewWindow->setItem(2, 0, new QTableWidgetItem("003"));
    viewWindow->setItem(2, 1, new QTableWidgetItem("你脑细胞够不够用？"));
    viewWindow->setItem(2, 2, new QTableWidgetItem("5"));
    // 第四行
    viewWindow->setItem(3, 0, new QTableWidgetItem("004"));
    viewWindow->setItem(3, 1, new QTableWidgetItem("学姐，你有头吗？"));
    viewWindow->setItem(3, 2, new QTableWidgetItem("10"));
    // 显示视图窗口
    viewWindow->show();
    return QApplication::exec();
}

运行结果如下：

三、QTreeWidget

QTreeWidget 类针对的就是树形结构的列表，是 QTreeView 的子类。它对应的列表项是 QTreeWidgetItem 类。

不过这里要注意的是，QTreeWidgetItem 虽然表示树形数据中的一个节点，但它在形式上就像一行数据。因为它可以包含多个列。Qt 的 Tree 视图是可以展示多列的。

下面咱们先做个单列的 Tree 视图。

int main(int argc, char** argv)
{
    QApplication app(argc, argv);

    // 创建视图窗口
    QTreeWidget* view = nullptr;
    view = new QTreeWidget;
    // 先来几个顶层节点
    QTreeWidgetItem* item1 = new QTreeWidgetItem({"秦"});
    QTreeWidgetItem* item2 = new QTreeWidgetItem({"汉"});
    QTreeWidgetItem* item3 = new QTreeWidgetItem({"晋"});
    QTreeWidgetItem* item4 = new QTreeWidgetItem({"隋"});
    QTreeWidgetItem* item5 = new QTreeWidgetItem({"唐"});
    QTreeWidgetItem* item6 = new QTreeWidgetItem({"宋"});
    // 给顶层节点添加子节点
    // 秦朝
    item1->addChild(new QTreeWidgetItem({"胡亥"}));
    item1->addChild(new QTreeWidgetItem({"扶苏"}));
    item1->addChild(new QTreeWidgetItem({"辛追"}));
    item1->addChild(new QTreeWidgetItem({"项籍"}));
    // 汉朝
    item2->addChildren({
        new QTreeWidgetItem({"霍光"}),
        new QTreeWidgetItem({"刘向"}),
        new QTreeWidgetItem({"司马迁"})
    });
    // 晋朝
    item3->addChildren({
        new QTreeWidgetItem({"卫铄"}),
        new QTreeWidgetItem({"司马承"}),
        new QTreeWidgetItem({"谢安"}),
        new QTreeWidgetItem({"王导"})
    });
    // 隋朝
    item4->addChild(new QTreeWidgetItem({"杨坚"}));
    item4->addChild(new QTreeWidgetItem({"史万岁"}));
    item4->addChild(new QTreeWidgetItem({"王通"}));
    // 唐朝
    item5->addChildren({
        new QTreeWidgetItem({"上官婉儿"}),
        new QTreeWidgetItem({"李龟年"}),
        new QTreeWidgetItem({"张旭"}),
        new QTreeWidgetItem({"杜牧"}),
        new QTreeWidgetItem({"武三思"}),
        new QTreeWidgetItem({"李靖"})
    });
    // 宋朝
    item6->addChildren({
        new QTreeWidgetItem({"王坚"}),
        new QTreeWidgetItem({"贾似道"}),
        new QTreeWidgetItem({"司马光"}),
        new QTreeWidgetItem({"宋慈"}),
        new QTreeWidgetItem({"张士逊"})
    });
    // 将顶层节点添加到QTreeWidget中
    view->addTopLevelItems({
        item1,
        item2,
        item3,
        item4,
        item5,
        item6
    });
    // 隐藏标题栏
    view->setHeaderHidden(true);
    // 设置窗口标题
    view->setWindowTitle("中华名人表");
    // 显示窗口
    view->show();

    return QApplication::exec();
}

QTreeWidgetItem 类的构造函数可以使用字符串列表来初始化显示的文本。原型如下：

explicit QTreeWidgetItem(const QStringList &strings, int type = Type);

在赋值的时候，可以直接用 { }，例如

QTreeWidgetItem({"天时", "地利", "人和"});

在上面例子中，因为咱们这次用的只是一列，所以传一个字符串元素就可以了。

QTreeWidgetItem 要添加子节点，可以用这些方法：

// 一次只加一个节点，新节点追加到末尾
void addChild(QTreeWidgetItem *child);

// 一次只添加一个节点，但可以指定新节点插入到哪个位置
void insertChild(int index, QTreeWidgetItem *child);

// 一次可以添加多个节点，参数是个列表对象
void addChildren(const QList<QTreeWidgetItem*> &children);

// 一次可以添加多个节点，能指定插入位置
void insertChildren(int index, const QList<QTreeWidgetItem*> &children);

QTreeWidget 组件用以下方法添加顶层节点：

// 添加一个节点，追加到末尾
void addTopLevelItem(QTreeWidgetItem *item);

// 添加一个节点，可以指定插入位置
void insertTopLevelItem(int index, QTreeWidgetItem *item);

// 添加多个节点，追加到末尾
void addTopLevelItems(const QList<QTreeWidgetItem*> &items);

// 添加多个节点，可指定插入位置
void insertTopLevelItems(int index, const QList<QTreeWidgetItem*> &items);

运行效果如下：

QTreeWidget 类也有 setItemWidget、removeItemWidget 方法。这个就不必多介绍了，和上面 QListWidget 类的一个意思，就是用一个自定义 Widget 显示在数据项上面。

下面咱们做个多列的 Tree 视图。

#include <qapplication.h>
#include <qtreewidget.h>

int main(int argc, char* argv[])
{
    QApplication app(argc, argv);

    QTreeWidget * view = new QTreeWidget;
    // 设置列数
    view->setColumnCount(4);
    // 顶层节点
    auto itemA = new QTreeWidgetItem({"潜水部"});
    auto itemB = new QTreeWidgetItem({"洗脑部"});
    auto itemC = new QTreeWidgetItem({"韭菜部"});
    // 子节点
    itemA->addChildren({
        new QTreeWidgetItem({"01", "梁酷裆", "经理", "6"}),
        new QTreeWidgetItem({"02", "王晓意", "秘书", "3"})
    });
    itemB->addChildren({
        new QTreeWidgetItem({"03", "于三明", "经理", "4"}),
        new QTreeWidgetItem({"04", "周日清", "经理助理", "3"}),
        new QTreeWidgetItem({"05", "费洁合", "跟办", "5"})
    });
    itemC->addChildren({
        new QTreeWidgetItem({"06", "安德诗", "经理", "3"}),
        new QTreeWidgetItem({"07", "李殿驰", "助理", "2"}),
        new QTreeWidgetItem({"08", "易更菁", "文员", "3"})
    });
    // 添加顶层节点到视图
    view->addTopLevelItems({itemA, itemB, itemC});
    // 设置列标题
    view->setHeaderLabels({"编号", "姓名", "职务", "工龄"});
    // 设置窗口标题
    view->setWindowTitle("啃瓜装饰服务有限公司员工表");
    // 显示窗口
    view->show();

    return QApplication::exec();
}

效果如下：

代码就不用多解释了吧，单列和多列的节点用法是一样的，只是传递给 QTreeWidgetItem 类构造函数的列表元素个数不同罢了。