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）
• 为子节点添加图标
• 自动展开所有节点
• 监听节点选择事件

---

四、关键特性总结

1. 通用功能：

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

2. 自定义扩展：

   // 设置自定义角色数据
   item->setData("custom data", Qt::UserRole + 1);// 自定义显示
   item->setFont(QFont("Arial", 12, QFont::Bold));
   item->setToolTip("This is a tooltip");
   

3. 数据持久化：

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

---