【Qt之QStandardItemModel类】介绍

描述

QStandardItemModel类提供了一个通用的模型，用于存储自定义数据。QStandardItemModel可以用作Qt标准数据类型的存储库。它是 Model/View类 之一，是 Qt的model/view框架 的一部分。 QStandardItemModel提供了一种基于项目的传统方法来处理模型。 QStandardItemModel中的项目是由QStandardItem提供的。QStandardItemModel实现了QAbstractItemModel接口，这意味着该模型可用于在支持该接口的任何视图中提供数据（例如QListView、QTableView和QTreeView，以及自定义视图）。为了提高性能和灵活性，可能希望从QAbstractItemModel中派生子类，以提供对不同种类数据存储库的支持。例如，QDirModel提供了对底层文件系统的模型接口。

当想要一个列表或树时，通常会创建一个空的QStandardItemModel，并使用appendRow()将项目添加到模型中，并使用item()访问项目。如果模型表示一个表格，则通常会将表格的尺寸传递给QStandardItemModel构造函数，并使用setItem()将项目定位到表格中。还可以使用setRowCount()和setColumnCount()来更改模型的尺寸。要插入项目，请使用insertRow()或insertColumn()，要删除项目，请使用removeRow()或removeColumn()。

此外，可以使用setHorizontalHeaderLabels()和setVerticalHeaderLabels()设置模型的标题标签。可以使用findItems()搜索模型中的项目，并通过调用sort()对模型进行排序。调用clear()可以从模型中删除所有项目。

示例1：创建表格

  QStandardItemModel model(4, 4);
  for (int row = 0; row < 4; ++row) {
      for (int column = 0; column < 4; ++column) {
          QStandardItem *item = new QStandardItem(QString("row %0, column %1").arg(row).arg(column));
          model.setItem(row, column, item);
      }
  }

示例2：创建树

  QStandardItemModel model;
  QStandardItem *parentItem = model.invisibleRootItem();
  for (int i = 0; i < 4; ++i) {
      QStandardItem *item = new QStandardItem(QString("item %0").arg(i));
      parentItem->appendRow(item);
      parentItem = item;
  }

在将模型设置到视图上之后，通常希望对用户操作做出反应，例如单击一个项目。由于QAbstractItemView提供了基于QModelIndex的信号和函数，因此需要一种方法来获取与给定QModelIndex对应的QStandardItem，反之亦然。itemFromIndex()和indexFromItem()提供了这种映射。itemFromIndex()的典型用法包括在视图中获取当前索引处的项目，并获取与由QAbstractItemView信号传递的索引相对应的项目，例如QAbstractItemView::clicked()。
首先，将视图的信号连接到类中的一个槽中：

  QTreeView *treeView = new QTreeView(this);
  treeView->setModel(myStandardItemModel);
  connect(treeView, SIGNAL(clicked(QModelIndex)),
          this, SLOT(clicked(QModelIndex)));

当接收到信号时，调用给定模型索引上的itemFromIndex()以获取指向该项目的指针：

  void MyWidget::clicked(const QModelIndex &index)
  {
      QStandardItem *item = myStandardItemModel->itemFromIndex(index);
      // Do stuff with the item ...
  }

反之，在希望调用以索引为参数的model/view函数时，必须获取项目的QModelIndex。可以使用模型的indexFromItem()函数或等效地调用QStandardItem::index()来获取索引：

  treeView->scrollTo(item->index());

当然，并不需要使用基于项目的方法；在处理模型时，也可以完全依赖于QAbstractItemModel接口，或者根据需要使用两者的组合。

方法

void QStandardItemModel::appendColumn(const QList<QStandardItem *> &items): 添加一个包含项目的列。如果必要，行数将增加到items的大小。
void QStandardItemModel::appendRow(const QList<QStandardItem *> &items): 添加一个包含项目的行。如果必要，列数将增加到items的大小。
void QStandardItemModel::appendRow(QStandardItem *item): 这是一个重载函数。当构建仅有一列的列表或树时，此函数提供了一种方便的方法来追加新项目。
void QStandardItemModel::clear():从模型中删除所有项目（包括标题项目），并将行数和列数设置为零。
[virtual] int QStandardItemModel::columnCount(const QModelIndex &parent = QModelIndex()) const:从QAbstractItemModel::columnCount()函数中重新实现。
[virtual] QVariant QStandardItemModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const:从QAbstractItemModel::data()函数中重新实现。
[virtual] bool QStandardItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent):从QAbstractItemModel::dropMimeData()函数中重新实现。
QList<QStandardItem *> QStandardItemModel::findItems(const QString &text, Qt::MatchFlags flags = Qt::MatchExactly, int column = 0) const:返回与给定文本匹配的项目列表，使用给定标志，在给定列中。
[virtual] Qt::ItemFlags QStandardItemModel::flags(const QModelIndex &index) const:从QAbstractItemModel::flags()函数中重新实现。
[virtual] bool QStandardItemModel::hasChildren(const QModelIndex &parent = QModelIndex()) const:从QAbstractItemModel::hasChildren()函数中重新实现。
[virtual] QVariant QStandardItemModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const:从QAbstractItemModel::headerData()函数中重新实现。
QStandardItem *QStandardItemModel::horizontalHeaderItem(int column) const:如果已设置，则返回列的水平标题项；否则返回0。
[virtual] QModelIndex QStandardItemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const:从QAbstractItemModel::index()函数中重新实现。
QModelIndex QStandardItemModel::indexFromItem(const QStandardItem *item) const:返回与给定项关联的QModelIndex。在执行需要项的QModelIndex的操作（例如QAbstractItemView :: scrollTo()）时，请使用此函数。QStandardItem :: index（）提供了方便性; 它相当于调用此函数。
void QStandardItemModel::insertColumn(int column, const QList<QStandardItem *> &items):在包含项的column处插入一个列。如果必要，行数将增加到items的大小。
bool QStandardItemModel::insertColumn(int column, const QModelIndex &parent = QModelIndex()):在父项的子项中在给定列之前插入单个列。如果插入列，则返回true; 否则返回false。
[virtual] bool QStandardItemModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex()):从QAbstractItemModel :: insertColumns()函数中重新实现。
void QStandardItemModel::insertRow(int row, const QList<QStandardItem *> &items):在包含项的row处插入一个行。如果必要，列数将增加到items的大小。
void QStandardItemModel::insertRow(int row, QStandardItem *item):这是一个重载函数。在包含项的row处插入一个包含单个项的行。当构建仅有一列的列表或树时，此函数提供了一种方便的方法来追加一个新项。
bool QStandardItemModel::insertRow(int row, const QModelIndex &parent = QModelIndex()):在父项的子项中在给定行之前插入单个行。如果插入行，则返回true; 否则返回false。
[virtual] bool QStandardItemModel::insertRows(int row, int count, const QModelIndex &parent = QModelIndex()):从QAbstractItemModel :: insertRows()函数中重新实现。
QStandardItem *QStandardItemModel::invisibleRootItem() const:返回模型的不可见根项。不可见的根项通过QStandardItem API提供对模型的顶级项的访问，使得可以编写可以以统一的方式处理顶级项和它们的子项的函数；例如，涉及树模型的递归函数。注意：对从此函数检索的QStandardItem对象调用index（）无效。
QStandardItem *QStandardItemModel::item(int row, int column = 0) const:如果已设置，则返回给定行和列的项; 否则返回0。
[signal] void QStandardItemModel :: itemChanged(QStandardItem *item):每当item的数据更改时，就会发射此信号。
[virtual] QMap<int，QVariant> QStandardItemModel :: itemData(const QModelIndex &index) const:从QAbstractItemModel :: itemData()函数中重新实现。
QStandardItem *QStandardItemModel::itemFromIndex(const QModelIndex &index) const:
返回与给定索引关联的QStandardItem的指针。
在处理基于QModelIndex的视图信号（例如QAbstractItemView :: activated()）时，通常调用此函数是初始步骤。在您的槽中，使用由信号携带的QModelIndex调用itemFromIndex（）以获取指向相应QStandardItem的指针。
注意，如果在该索引处不存在项，则此函数将延迟创建该项（使用itemPrototype（）），并将其设置在父项的子项表格中。
如果index是无效索引，则此函数返回0。
const QStandardItem *QStandardItemModel::itemPrototype() const:
返回模型使用的项原型。当需要按需构建新项（例如，当视图或项代理调用setData（））时，模型使用项原型作为项工厂。
[virtual] QMimeData *QStandardItemModel :: mimeData(const QModelIndexList &indexes) const:
从QAbstractItemModel :: mimeData()函数中重新实现。
[virtual] QStringList QStandardItemModel :: mimeTypes() const:
从QAbstractItemModel :: mimeTypes()函数中重新实现。
[virtual] QModelIndex QStandardItemModel::parent(const QModelIndex &child) const:
从QAbstractItemModel :: parent()函数中重新实现。
[virtual] bool QStandardItemModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex()):
从QAbstractItemModel :: removeColumns()函数中重新实现。
[virtual] bool QStandardItemModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()):
从QAbstractItemModel :: removeRows()函数中重新实现。
[virtual] int QStandardItemModel::rowCount(const QModelIndex &parent = QModelIndex()) const:
从QAbstractItemModel :: rowCount()函数中重新实现。
void QStandardItemModel::setColumnCount(int columns):
将模型中的列数设置为columns。如果这小于columnCount（），则舍弃不需要的列中的数据。
[virtual] bool QStandardItemModel::setData(const QModelIndex &index，const QVariant &value，int role = Qt :: EditRole):
从QAbstractItemModel :: setData()函数中重新实现。
[virtual] bool QStandardItemModel::setHeaderData(int section，Qt :: Orientation orientation，const QVariant &value，int role = Qt :: EditRole):
从QAbstractItemModel :: setHeaderData()函数中重新实现。
void QStandardItemModel::setHorizontalHeaderItem(int column，QStandardItem *item):
将列column的水平标头项设置为item。模型接管该项。必要时，列计数将增加以适应该项。删除先前的标头项（如果有任何）。
void QStandardItemModel::setHorizontalHeaderLabels(const QStringList &labels):
使用labels设置水平标头标签。如果必要，列计数将增加到labels的大小。
void QStandardItemModel::setItem(int row，int column，QStandardItem *item):
将给定行和列的项设置为item。模型接管该项。必要时，行计数和列计数将增加以适应该项。删除给定位置的先前项（如果有任何）。
void QStandardItemModel::setItem(int row，QStandardItem *item):
这是一个重载函数。
[virtual] bool QStandardItemModel::setItemData(const QModelIndex &index，const QMap <int，QVariant> &roles):
从QAbstractItemModel :: setItemData()函数中重新实现。
void QStandardItemModel::setItemPrototype(const QStandardItem *item):
将该模型的项原型设置为指定的项。模型接管原型。
项原型通过依赖于QStandardItem :: clone（）函数来作为QStandardItem工厂。要提供自己的原型，请子类化QStandardItem，重新实现QStandardItem :: clone（）并将原型设置为您自定义类的实例。每当QStandardItemModel需要按需创建项（例如，当视图或项代理调用setData（））时，新项将是您自定义类的实例。
void QStandardItemModel::setItemRoleNames(const QHash<int，QByteArray> &roleNames):
将项角色名称设置为roleNames。
void QStandardItemModel::setRowCount(int rows):
将模型中的行数设置为rows。如果这小于rowCount（），则舍弃不需要的行中的数据。
void QStandardItemModel::setVerticalHeaderItem(int row，QStandardItem *item):
将行row的垂直标头项设置为item。模型接管该项。必要时，行计数将增加以适应该项。删除先前的标头项（如果有任何）。
void QStandardItemModel::setVerticalHeaderLabels(const QStringList &labels):
使用labels设置垂直标头标签。如果必要，行计数将增加到labels的大小。
[virtual] QModelIndex QStandardItemModel::sibling(int row，int column，const QModelIndex &idx) const:
从QAbstractItemModel :: sibling()函数中重新实现。
[virtual] void QStandardItemModel::sort(int column，Qt :: SortOrder order = Qt :: AscendingOrder):
从QAbstractItemModel :: sort()函数中重新实现。
[virtual] Qt :: DropActions QStandardItemModel :: supportedDropActions() const:
从QAbstractItemModel :: supportedDropActions()函数中重新实现。
QStandardItemModel支持复制和移动。
QList<QStandardItem *> QStandardItemModel::takeColumn(int column):
删除给定的列而不删除列项，并返回指向已删除项的指针列表。模型释放项的所有权。对于未设置的列中的项，列表中相应的指针将为0。
QStandardItem *QStandardItemModel::takeHorizontalHeaderItem(int column):
从标头中删除列column的水平标头项而不删除它，并返回指向该项的指针。模型释放项的所有权。
QStandardItem *QStandardItemModel::takeItem(int row，int column = 0):
删除（行，列）处的项而不删除它。模型释放项的所有权。
QList<QStandardItem *> QStandardItemModel::takeRow(int row):
删除给定的行而不删除行项，并返回指向已删除项的指针列表。模型释放项的所有权。对于未设置的行中的项，列表中相应的指针将为0。
QStandardItem *QStandardItemModel::takeVerticalHeaderItem(int row):
从标头中删除行row的垂直标头项而不删除它，并返回指向该项的指针。模型释放项的所有权。
QStandardItem *QStandardItemModel :: verticalHeaderItem(int row) const:
如果已设置，则返回行row的垂直标头项；否则返回0。

示例

下面是一个简单的使用示例：

#include <QStandardItemModel>
#include <QTableView>

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

    // 创建模型
    QStandardItemModel model(3, 3); // 3行3列

    // 设置水平表头
    model.setHorizontalHeaderItem(0, new QStandardItem("Column1"));
    model.setHorizontalHeaderItem(1, new QStandardItem("Column2"));
    model.setHorizontalHeaderItem(2, new QStandardItem("Column3"));

    // 设置垂直表头
    model.setVerticalHeaderItem(0, new QStandardItem("Row1"));
    model.setVerticalHeaderItem(1, new QStandardItem("Row2"));
    model.setVerticalHeaderItem(2, new QStandardItem("Row3"));

    // 设置列宽
    tableView->setColumnWidth(0, 100);
    tableView->setColumnWidth(1, 150);
    tableView->setColumnWidth(2, 200);

    // 设置行高
    tableView->setRowHeight(0, 30);
    tableView->setRowHeight(1, 40);
    tableView->setRowHeight(2, 50);

    // 插入数据
    model.setData(model.index(0, 0), QVariant("data1"));
    model.setData(model.index(0, 1), QVariant("data2"));
    model.setData(model.index(0, 2), QVariant("data3"));

    // 移除数据
    model.removeRow(1);

    // 创建视图
    QTableView tableView;
    tableView.setModel(&model);
    tableView.show();

    return app.exec();
}

此外，还支持信号和槽机制，比如在数据改变时会发出itemChanged()信号。可以为该信号连接一个槽函数，以便在发生更改时执行特定的操作。

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

注意，在使用QStandardItemModel时，需要自行为每个单元格创建QStandardItem对象，并设置其文本、图标等属性。以上示例中，使用了setData()函数，设置单元格的数据。另外，还可以使用setItem()函数设置单元格的QStandardItem对象，从而获得更多的控制权。

QStandardItem *item = new QStandardItem("data1");
model.setItem(0, 0, item); // 在(0, 0)位置设置该QStandardItem对象