QStandardItemModel的函数和信号介绍

前言

Qt版本:6.8.0

QStandardItem函数介绍

函数

部分函数有不同的重载来适应不同的模型,例如appendrow

构造函数与析构函数

1. **QStandardItemModel(QObject *parent = nullptr)**

说明：创建一个空的模型（0行0列）。
参数：
- parent：父对象（通常用于内存管理）。

示例：

QStandardItemModel *model = new QStandardItemModel(this); // 创建空模型

2. **QStandardItemModel(int rows, int columns, QObject *parent = nullptr)**

说明：创建指定行数和列数的模型，所有项初始化为空。
参数：
- rows：初始行数。
- columns：初始列数。
- parent：父对象。

示例：

QStandardItemModel *model = new QStandardItemModel(3, 2, this); // 3行2列-表格模型

QStandardItemModel *model = new QStandardItemModel(3, 1, this); // 3行1列-列表模型

3. virtual ~QStandardItemModel()

说明：析构函数，销毁模型及其所有项。

核心数据操作

4. **void appendColumn(const QList<QStandardItem *> &items)**

说明：在模型末尾添加一列，用 items 填充。
参数：
- items：列项的列表（长度需等于当前行数）。

示例：

QList<QStandardItem*> columnItems;
columnItems << new QStandardItem("A1") << new QStandardItem("A2");
model->appendColumn(columnItems); // 添加一列（假设当前有2行）

5. **void appendRow(const QList<QStandardItem *> &items)–适用于表格模型**

说明：在末尾添加一行，用 items 填充列。
参数：
- items：行项的列表（长度需等于当前列数）。

示例：

QList<QStandardItem*> rowItems;
rowItems << new QStandardItem("Cell1") << new QStandardItem("Cell2");
model->appendRow(rowItems); // 添加一行（假设当前有2列）

6. **void appendRow(QStandardItem *item)–适用于列表模型**

说明：在末尾添加一行，仅填充第0列的项。
参数：
- item：单个项的指针。

示例：

model->appendRow(new QStandardItem("Row Header")); // 添加一行，第0列有数据

7. QBindable bindableSortRole()

说明：返回排序角色的可绑定对象（用于属性绑定）。
返回值：QBindable<int>，可监听排序角色变化。

示例：

QBindable<int> bindable = model->bindableSortRole();
bindable.setBinding([&](){ return Qt::DisplayRole; }); // 绑定排序角色到 DisplayRole

8. void clear()

说明：清空模型所有数据（包括行、列、表头）。
示例：
```
model->clear(); // 清空模型
```

9. **QList<QStandardItem *> findItems(const QString &text, Qt::MatchFlags flags = Qt::MatchExactly, int column = 0) const**

说明：查找匹配 text 的项。
参数：
- text：要匹配的文本。
- flags：匹配模式（如 Qt::MatchContains）。
- column：搜索的列（默认第0列）。
返回值：匹配项的列表。

示例：

QList<QStandardItem*> found = model->findItems("Alice", Qt::MatchExactly, 0);

10. **QStandardItem *horizontalHeaderItem(int column) const**

说明：获取水平表头指定列的项。
参数：
- column：列索引。
返回值：表头项的指针，若不存在返回 nullptr。

示例：

QStandardItem *header = model->horizontalHeaderItem(0); // 获取第0列表头

11. **QModelIndex indexFromItem(const QStandardItem *item) const**

说明：获取项对应的 QModelIndex。
参数：
- item：要查询的项。
返回值：项的索引，无效项返回 QModelIndex()。

示例：

QStandardItem *item = model->item(0, 0);
QModelIndex index = model->indexFromItem(item); // 获取索引

12. **void insertColumn(int column, const QList<QStandardItem *> &items)**

说明：在指定列插入数据。
参数：
- column：插入的列索引。
- items：列项的列表。

示例：

QList<QStandardItem*> newColumn;
newColumn << new QStandardItem("X") << new QStandardItem("Y");
model->insertColumn(1, newColumn); // 在第1列插入数据

13. bool insertColumn(int column, const QModelIndex &parent = QModelIndex())

说明：插入空列（继承自 QAbstractItemModel）。
参数：
- column：插入的列索引。
- parent：父索引（对表格模型无效）。
返回值：成功返回 true。

示例：

model->insertColumn(1); // 在第1列插入空列

14. **void insertRow(int row, const QList<QStandardItem *> &items)**

说明：在指定行插入数据。
参数：
- row：插入的行索引。
- items：行项的列表。

示例：

QList<QStandardItem*> newRow;
newRow << new QStandardItem("New1") << new QStandardItem("New2");
model->insertRow(1, newRow); // 在第1行插入数据

15. bool insertRow(int row, const QModelIndex &parent = QModelIndex())

说明：插入空行（继承自 QAbstractItemModel）。
参数：
- row：插入的行索引。
- parent：父索引（对表格模型无效）。
返回值：成功返回 true。

示例：

model->insertRow(1); // 在第1行插入空行

16. **void insertRow(int row, QStandardItem *item)**

说明：插入单列行（仅填充第0列）。
参数：
- row：插入的行索引。
- item：第0列的项。

示例：

model->insertRow(1, new QStandardItem("Single Column")); // 插入一行，仅第0列有数据

17. **QStandardItem *invisibleRootItem() const**

说明：返回模型的根项（用于树形结构）。
返回值：根项的指针。

示例：

QStandardItem *root = model->invisibleRootItem();

18. **QStandardItem *item(int row, int column = 0) const**

说明：获取指定行和列的项。
参数：
- row：行索引。
- column：列索引（默认0）。
返回值：项的指针，若不存在返回 nullptr。

示例：

QStandardItem *cell = model->item(0, 1); // 获取第0行第1列的项

19. **QStandardItem *itemFromIndex(const QModelIndex &index) const**

说明：从视图索引获取项。
参数：
- index：视图提供的索引。
返回值：项的指针。

示例：

QModelIndex index = model->index(0, 0);
QStandardItem *item = model->itemFromIndex(index); // 获取对应项

20. **const QStandardItem *itemPrototype() const**

说明：返回创建新项时使用的原型。
返回值：原型项的指针。

示例：

const QStandardItem *prototype = model->itemPrototype();

表头与元数据

21. void setColumnCount(int columns)

说明：设置列数（自动扩展或收缩）。
参数：
- columns：目标列数。

示例：

model->setColumnCount(3); // 设置模型为3列

22. **void setHorizontalHeaderItem(int column, QStandardItem *item)**

说明：设置水平表头某一列的项。
参数：
- column：列索引。
- item：表头项。

示例：

QStandardItem *headerItem = new QStandardItem("ID");
model->setHorizontalHeaderItem(0, headerItem); // 设置第0列表头为"ID"

23. void setHorizontalHeaderLabels(const QStringList &labels)

说明：设置水平表头的标签。
参数：
- labels：标签列表。

示例：

model->setHorizontalHeaderLabels({"Name", "Age"}); // 设置两列的标题

24. **void setItem(int row, int column, QStandardItem *item)**

说明：设置指定行和列的项。
参数：
- row：行索引。
- column：列索引。
- item：项的指针。

示例：

model->setItem(0, 1, new QStandardItem("25")); // 第0行第1列设置为"25"

25. **void setItem(int row, QStandardItem *item)**

说明：设置指定行第0列的项。
参数：
- row：行索引。
- item：项的指针。

示例：

model->setItem(0, new QStandardItem("Alice")); // 第0行第0列设置为"Alice"

26. **void setItemPrototype(const QStandardItem *item)**

说明：设置创建新项时使用的原型（克隆属性）。
参数：
- item：原型项。

示例：

QStandardItem *prototype = new QStandardItem();
prototype->setForeground(Qt::red); // 默认文本颜色为红色
model->setItemPrototype(prototype); // 所有新项将继承此属性

27. void setItemRoleNames(const QHash<int, QByteArray> &roleNames)

说明：设置自定义角色名称（用于数据绑定）。
参数：
- roleNames：角色ID与名称的映射。

示例：

QHash<int, QByteArray> roles;
roles[Qt::UserRole + 1] = "customRole";
model->setItemRoleNames(roles);

28. void setRowCount(int rows)

说明：设置行数（自动扩展或收缩）。
参数：
- rows：目标行数。

示例：

model->setRowCount(5); // 设置模型为5行

29. void setSortRole(int role)

说明：设置排序时使用的角色（如 Qt::DisplayRole）。
参数：
- role：角色ID。

示例：

model->setSortRole(Qt::UserRole); // 排序时使用自定义角色数据

30. **void setVerticalHeaderItem(int row, QStandardItem *item)**

说明：设置垂直表头某一行的项。
参数：
- row：行索引。
- item：表头项。

示例：

QStandardItem *rowHeader = new QStandardItem("Row1");
model->setVerticalHeaderItem(0, rowHeader); // 设置第0行表头

31. void setVerticalHeaderLabels(const QStringList &labels)

说明：设置垂直表头的标签。
参数：
- labels：标签列表。

示例：

model->setVerticalHeaderLabels({"Row1", "Row2"}); // 设置两行的行标题

32. int sortRole() const

说明：返回当前排序使用的角色。
返回值：角色ID。

示例：

int role = model->sortRole(); // 获取当前排序角色

移除数据

33. **QList<QStandardItem *> takeColumn(int column)**

说明：移除并返回指定列的所有项。
参数：
- column：列索引。
返回值：被移除项的列表。

示例：

QList<QStandardItem*> removed = model->takeColumn(0); // 移除第0列

34. **QStandardItem *takeHorizontalHeaderItem(int column)**

说明：移除并返回水平表头的某一项。
参数：
- column：列索引。
返回值：被移除的表头项。

示例：

QStandardItem *header = model->takeHorizontalHeaderItem(0); // 移除第0列表头

35. **QStandardItem *takeItem(int row, int column = 0)**

说明：移除并返回指定位置的项。
参数：
- row：行索引。
- column：列索引（默认0）。
返回值：被移除的项。

示例：

QStandardItem *item = model->takeItem(0, 1); // 移除第0行第1列的项

36. **QList<QStandardItem *> takeRow(int row)**

说明：移除并返回指定行的所有项。
参数：
- row：行索引。
返回值：被移除的行项列表。

示例：

QList<QStandardItem*> rowItems = model->takeRow(0); // 移除第0行

37. **QStandardItem *takeVerticalHeaderItem(int row)**

说明：移除并返回垂直表头的某一项。
参数：
- row：行索引。
返回值：被移除的表头项。

示例：

QStandardItem *header = model->takeVerticalHeaderItem(0); // 移除第0行表头

38. **QStandardItem *verticalHeaderItem(int row) const**

说明：获取垂直表头某一行的项。
参数：
- row：行索引。
返回值：表头项的指针。

示例：

QStandardItem *header = model->verticalHeaderItem(0); // 获取第0行表头

已重写的虚函数

在这里插入图片描述

信号

39. **void itemChanged(QStandardItem *item)**

说明：当项的数据（如文本、颜色）被修改时触发。

连接示例：

connect(model, &QStandardItemModel::itemChanged, [](QStandardItem *item) {
    qDebug() << "Item changed:" << item->text();
});

使用QStandardItemModel自定义模型

一、列表模型（QListView + QStandardItemModel）

#include <QApplication>
#include <QListView>
#include <QStandardItemModel>

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

    // 创建模型和视图
    QStandardItemModel model;
    QListView listView;

    // 添加列表项
    QList<QStandardItem*> items;
    for (int i = 0; i < 5; ++i) {
        QStandardItem *item = new QStandardItem(QString("Item %1").arg(i));
        item->setCheckable(true); // 可选中的复选框
        items.append(item);
    }
    model.appendColumn(items);

    // 设置模型并显示
    listView.setModel(&model);
    listView.setEditTriggers(QAbstractItemView::DoubleClicked); // 允许双击编辑
    listView.show();

    // 处理项修改信号
    QObject::connect(&model, &QStandardItemModel::itemChanged, [](QStandardItem *item) {
        qDebug() << "Item changed:" << item->text();
    });

    return app.exec();
}

说明：

创建包含复选框的可编辑列表
双击项目可修改文本内容
通过 itemChanged 信号监听修改事件

二、表格模型（QTableView + QStandardItemModel）

#include <QApplication>
#include <QTableView>
#include <QStandardItemModel>

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

    // 创建模型（3行3列）
    QStandardItemModel model(3, 3);
    QTableView tableView;

    // 设置表头
    model.setHorizontalHeaderLabels({"Name", "Age", "Occupation"});

    // 填充数据
    for (int row = 0; row < 3; ++row) {
        for (int col = 0; col < 3; ++col) {
            QStandardItem *item = new QStandardItem(QString("R%1C%2").arg(row).arg(col));
            if (col == 1) item->setData(QVariant(20 + row), Qt::EditRole); // 数字类型数据
            model.setItem(row, col, item);
        }
    }

    // 自定义显示特性
    model.item(0, 0)->setForeground(Qt::blue);  // 设置文字颜色
    model.item(1, 1)->setBackground(Qt::yellow); // 设置背景色

    // 设置视图
    tableView.setModel(&model);
    tableView.resize(400, 200);
    tableView.show();

    return app.exec();
}

说明：

创建 3x3 表格并设置表头
第二列存储数值类型数据
演示单元格颜色设置
默认支持直接编辑单元格内容

三、树模型（QTreeView + QStandardItemModel）

#include <QApplication>
#include <QTreeView>
#include <QStandardItemModel>

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

    QStandardItemModel model;
    QTreeView treeView;

    // 创建根节点
    QStandardItem *root = new QStandardItem("Root");
    model.appendRow(root);

    // 添加子节点
    for (int i = 0; i < 3; ++i) {
        QStandardItem *parentItem = new QStandardItem(QString("Parent %1").arg(i));
        root->appendRow(parentItem);

        // 添加子节点的子节点
        for (int j = 0; j < 2; ++j) {
            QStandardItem *childItem = new QStandardItem(QString("Child %1").arg(j));
            childItem->setIcon(QIcon(":/icons/child.png")); // 设置图标
            parentItem->appendRow(childItem);
        }
    }

    // 设置模型并显示
    treeView.setModel(&model);
    treeView.expandAll(); // 展开所有节点
    treeView.show();

    // 处理节点选择
    QObject::connect(treeView.selectionModel(), &QItemSelectionModel::selectionChanged,
        [](const QItemSelection &selected) {
            if (!selected.isEmpty()) {
                QModelIndex index = selected.indexes().first();
                qDebug() << "Selected:" << index.data().toString();
            }
        });

    return app.exec();
}

说明：

创建三级树形结构（Root → Parent → Child）
为子节点添加图标
自动展开所有节点
监听节点选择事件

四、关键特性总结

通用功能：
- 内置数据存储
- 自动视图同步
- 支持拖放操作（需启用相关属性）
- 提供丰富的信号（itemChanged、rowsInserted 等）

自定义扩展：

// 设置自定义角色数据
item->setData("custom data", Qt::UserRole + 1);

// 自定义显示
item->setFont(QFont("Arial", 12, QFont::Bold));
item->setToolTip("This is a tooltip");

数据持久化：

// 保存模型数据到文件
QFile file("data.xml");
file.open(QIODevice::WriteOnly);
model.save(&file, QStandardItemModel::XmlRole);

// 从文件加载
model.load(&file, QStandardItemModel::XmlRole);