QAbstractItemModel Class

成员函数文档

[explicit] QAbstractItemModel::QAbstractItemModel(QObject *parent = nullptr)

用给定的parent 构建抽象项目模型。

[virtual noexcept] QAbstractItemModel::~QAbstractItemModel()

销毁抽象项目模型。

[protected] void QAbstractItemModel::beginInsertColumns(const QModelIndex &parent, int first, int last)

开始列插入操作。

在子类中重新实现insertColumns() 时，必须在将数据插入模型的底层数据存储之前调用此函数。

parent 索引与插入新列的父级对应；first 和last 是新列插入后的列号。

插入列	为要插入模型中项目的列跨度指定第一列和最后一列的列号。 例如，如图所示，我们在第 4 列之前插入三列，因此first 为 4，last 为 6： beginInsertColumns(parent, 4, 6); 这样就会插入三个新列，分别为第 4、5 和 6 列。
追加列	要追加列，请在最后一列之后插入。 例如，如图所示，我们将三列追加到现有的六列集合中（以第 5 列结束），因此first 为 6，last 为 8： beginInsertColumns(parent, 6, 8); 这样就将两列新列追加为第 6、7 和 8 列。

另请参阅 endInsertColumns()。

[protected] void QAbstractItemModel::beginInsertRows(const QModelIndex &parent, int first, int last)

开始行插入操作。

在子类中重新实现insertRows() 时，必须在将数据插入模型的底层数据存储之前调用该函数。

parent 索引对应于插入新行的父节点；first 和last 是新行插入后的行号。

插入行	为要插入模型中项目的行跨度指定第一行和最后一行的行号。 例如，如图所示，我们在第 2 行之前插入三行，因此first 为 2，last 为 4： beginInsertRows(parent, 2, 4); 这样插入的三条新行就是第 2、3 和 4 行。
追加行	要追加行，请在最后一行之后插入。 例如，如图所示，我们将两行追加到现有的 4 行集合中（以第 3 行结束），因此first 为 4，last 为 5： beginInsertRows(parent, 4, 5); 这样就将两行新记录追加为第 4 行和第 5 行。

另请参见 endInsertRows()。

[protected] bool QAbstractItemModel::beginMoveColumns(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

开始列移动操作。

在重新实现子类时，该方法可简化模型中实体的移动。该方法负责移动模型中的持久性索引，否则您就需要亲自动手。使用 beginMoveColumns 和endMoveColumns 可替代直接发送layoutAboutToBeChanged 和layoutChanged 以及changePersistentIndex 。

sourceParent 索引对应于要移动列的父代；sourceFirst 和sourceLast 是要移动列的首列号和尾列号。destinationParent 索引对应于这些列被移入的父级。destinationChild 是要移动的列的列号。也就是说，sourceParent 中sourceFirst 列的索引将变为destinationParent 中的destinationChild 列，然后是直到sourceLast 的所有其他列。

但是，如果将同一父级中的列向下移动（sourceParent 和destinationParent 相等），这些列将被放在destinationChild 索引之前。也就是说，如果要移动列 0 和 1，使其成为列 1 和 2，destinationChild 应为 3。在这种情况下，源列i 的新索引（位于sourceFirst 和sourceLast 之间）等于(destinationChild-sourceLast-1+i) 。

请注意，如果sourceParent 和destinationParent 相同，则必须确保destinationChild 不在sourceFirst 和sourceLast + 1 的范围内。您还必须确保不试图将列移动到它自己的子列或祖列。如果任一条件为真，本方法将返回false ，在这种情况下，您应该放弃移动操作。

另请参见 endMoveColumns()。

[protected] bool QAbstractItemModel::beginMoveRows(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)

开始行移动操作。

在重新实现子类时，该方法可简化模型中实体的移动。该方法负责移动模型中的持久性索引，否则您就需要自己进行移动。使用 beginMoveRows 和endMoveRows 可替代直接发射layoutAboutToBeChanged 和layoutChanged 以及changePersistentIndex 。

sourceParent 索引对应于要移动行的父代；sourceFirst 和sourceLast 是要移动行的首尾行号。destinationParent 索引对应的是要将这些行移入的父行。destinationChild 是要移动的行的行号。也就是说，sourceParent 中sourceFirst 行的索引将变为destinationParent 中destinationChild 行的索引，然后是直到sourceLast 的所有其他行。

但是，如果将同一父代中的行向下移动（sourceParent 和destinationParent 相等），这些行将被放在destinationChild 索引之前。也就是说，如果要移动 0 和 1 行，使其成为 1 和 2 行，destinationChild 应为 3。在这种情况下，源行i 的新索引（位于sourceFirst 和sourceLast 之间）等于(destinationChild-sourceLast-1+i) 。

请注意，如果sourceParent 和destinationParent 相同，则必须确保destinationChild 不在sourceFirst 和sourceLast + 1 的范围内。此外，还必须确保不试图将一行移动到其子行或祖先行。如果任一条件为真，此方法将返回false ，在这种情况下，你应该放弃移动操作。

将行移动到另一个父代	在模型中指定要移动的源父代中跨行的首尾行号。同时指定要将跨度移动到的目标父代中的行。 例如，如图所示，我们在源父代中将三行从第 2 行移动到第 4 行，因此sourceFirst 为 2，sourceLast 为 4。我们将这些项目移动到目标父代的第 2 行以上，因此destinationChild 为 2。 beginMoveRows(sourceParent, 2, 4, destinationParent, 2); 这样，源文件中的第 2、3 和 4 行就变成了目的文件中的第 2、3 和 4 行。其他受影响的同级项目也会相应移动。
移动行以追加到另一个父代	要将行附加到另一个父代，可将它们移到最后一行之后。 例如，如图所示，我们将三行移动到现有的 6 行集合中（以第 5 行结束），因此destinationChild 为 6： beginMoveRows(sourceParent, 2, 4, destinationParent, 6); 这将目标行移动到目标父代的末尾，分别为 6、7 和 8。
向上移动同一父代中的行	要移动同一父代中的行，请指定要移动的行。 例如，如图所示，我们将一个项目从第 2 行移动到第 0 行，因此sourceFirst 和sourceLast 为 2，destinationChild 为 0。 beginMoveRows(parent, 2, 2, parent, 0); 请注意，其他行也会相应移动。还要注意的是，在同一父级中移动项目时，不应尝试无效或无操作的移动。在上面的示例中，项目 2 在移动前位于第 2 行，因此不能移动到第 2 行（已在该行）或第 3 行（无操作，因为第 3 行意味着在第 3 行以上，已在该行）。
向下移动同一父代中的行	要移动同一父代中的行，请指定要移动的行。 例如，如图所示，我们将一个项目从第 2 行移到第 4 行，因此sourceFirst 和sourceLast 为 2，destinationChild 为 4。 beginMoveRows(parent, 2, 2, parent, 4); 请注意，其他行可能会相应移动。

另请参见 endMoveRows()。

[protected] void QAbstractItemModel::beginRemoveColumns(const QModelIndex &parent, int first, int last)

开始列删除操作。

在子类中重新实现removeColumns() 时，必须在从模型的底层数据存储中移除数据之前调用此函数。

parent 索引对应于从中移除新列的父级；first 和last 是要移除的第一列和最后一列的列号。

删除列	为要从模型中的项目移除的列跨度指定第一列和最后一列的列号。 例如，如图所示，我们移除从第 4 列到第 6 列的三列，因此first 为 4，last 为 6： beginRemoveColumns(parent, 4, 6);

另请参见 endRemoveColumns()。

[protected] void QAbstractItemModel::beginRemoveRows(const QModelIndex &parent, int first, int last)

开始删除行操作。

在子类中重新实现removeRows() 时，必须在从模型的底层数据存储中移除数据之前调用此函数。

parent 索引对应于从中移除新行的父类；first 和last 是要移除的行的行号。

删除行	为要从模型中的一个项目中移除的行跨度指定第一行和最后一行的行号。 例如，如图所示，我们要删除从第 2 行到第 3 行的两行，因此first 为 2，last 为 3： beginRemoveRows(parent, 2, 3);

另请参见 endRemoveRows()。

[protected] void QAbstractItemModel::beginResetModel()

开始模型重置操作。

重置操作会在任何附加视图中将模型重置为当前状态。

重置模型时，意味着以前从模型中报告的任何数据现在都无效，必须重新查询。这也意味着当前项目和任何选定项目都将失效。

当模型彻底改变其数据时，有时只需调用此函数，而不必在底层数据源或其结构发生变化时发出dataChanged() 通知其他组件。

在重置模型或代理模型中的任何内部数据结构之前，必须调用此函数。

此函数将发出信号modelAboutToBeReset()。

另请参阅 modelAboutToBeReset()、modelReset() 和endResetModel()。

[virtual] QModelIndex QAbstractItemModel::buddy(const QModelIndex &index) const

返回由index 表示的项目好友的模型索引。当用户要编辑一个项目时，视图将调用此函数来检查是否应该编辑模型中的另一个项目。然后，视图将使用好友项目返回的模型索引构建一个委托。

此函数的默认实现是将每个项目作为自己的好友。

[virtual] bool QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const

如果模型可以接受data 的下拉，则返回true 。此默认实现只检查data 是否在mimeTypes() 列表中至少有一种格式，以及action 是否在模型的supportedDropActions() 中。

如果您想测试data 是否可以在row,column,parent 和action 上丢弃，请在自定义模型中重新实现此函数。如果您不需要该测试，则无需重新实现此函数。

另请参阅 dropMimeData() 和使用项目视图拖放。

[virtual invokable] bool QAbstractItemModel::canFetchMore(const QModelIndex &parent) const

如果parent 有更多可用数据，则返回true ；否则返回false 。

默认实现总是返回false 。

如果 canFetchMore() 返回true ，则应调用fetchMore() 函数。例如，这就是QAbstractItemView 的行为。

另请参阅 fetchMore()。

[protected] void QAbstractItemModel::changePersistentIndex(const QModelIndex &from, const QModelIndex &to)

将等于给定from 模型索引的QPersistentModelIndex 更改为给定的to 模型索引。

如果没有找到与给定from 模型索引相等的持久模型索引，则不会更改任何内容。

另请参阅 persistentIndexList() 和changePersistentIndexList()。

[protected] void QAbstractItemModel::changePersistentIndexList(const QModelIndexList &from, const QModelIndexList &to)

将与给定的from 模型索引列表中的索引相等的 {QPersistentModelIndex}es 更改为给定的to 模型索引列表。

如果没有找到与给定的from 模型索引列表中的索引相等的持久模型索引，则不会更改任何内容。

另请参阅 persistentIndexList() 和changePersistentIndex()。

bool QAbstractItemModel::checkIndex(const QModelIndex &index, QAbstractItemModel::CheckIndexOptions options = CheckIndexOption::NoOption) const

此函数检查index 是否是此模型的合法模型索引。合法的模型索引要么是无效的模型索引，要么是符合以下所有条件的有效模型索引：

• 该索引的模型是this ；
• 索引行大于或等于零；
• 索引行小于索引父代的行数；
• 索引列大于或等于零；
• 索引 "列小于索引父代的列数。

options 参数可能会改变其中一些检查。如果options 包含IndexIsValid ，则index 必须是有效索引；这在重新实现data() 或setData() 等函数时非常有用，因为这些函数希望使用有效索引。

如果options 包含DoNotUseParent ，则会省略调用parent() 的检查；这样就可以在重新实现parent() 时调用该函数（否则会导致无休止的递归和崩溃）。

如果options 不包含DoNotUseParent ，而包含ParentIsInvalid ，则会执行额外的检查：检查父索引是否无效。这在实现列表或表格等扁平模型时非常有用，因为在这些模型中，任何模型索引都不应具有有效的父索引。

如果所有检查都成功，则该函数返回 true，否则返回 false。这样就可以在Q_ASSERT 和类似的其他调试机制中使用该函数。如果某些检查失败，将在qt.core.qabstractitemmodel.checkindex 日志类别中打印一条警告信息，其中包含一些可能对调试失败有用的信息。

另请参阅 QModelIndex 。

[virtual, since 6.0] bool QAbstractItemModel::clearItemData(const QModelIndex &index)

删除存储在给定index 的所有角色中的数据。如果成功，则返回true ；否则返回false 。如果数据已成功删除，则应发出dataChanged() 信号。基类实现返回false

此函数在 Qt 6.0 中引入。

另请参阅 data()、itemData()、setData() 和setItemData()。

[pure virtual invokable] int QAbstractItemModel::columnCount(const QModelIndex &parent = QModelIndex()) const

返回给定parent 子类的列数。

在大多数子类中，列数与parent 无关。

例如

int MyModel::columnCount(const QModelIndex &parent) const
{
    Q_UNUSED(parent);
    return 3;
}

另请参阅 rowCount() 。

[private signal] void QAbstractItemModel::columnsAboutToBeInserted(const QModelIndex &parent, int first, int last)

该信号在列插入模型之前发出。新项目将被放置在first 和last 之间（含 ），位于给定的parent 项目之下。

另请参阅 insertColumns() 和beginInsertColumns()。

[private signal] void QAbstractItemModel::columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

该信号在模型内移动列之前发出。将被移动的项目是sourceStart 和sourceEnd 之间（含 ）的项目，位于给定的sourceParent 项目之下。它们将从destinationColumn 列开始被移动到destinationParent 。

注：连接到此信号的组件使用它来适应模型尺寸的变化。该信号只能由QAbstractItemModel 实现发出，不能在子类代码中明确发出。

另请参阅 beginMoveRows().

[private signal] void QAbstractItemModel::columnsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

该信号在从模型中移除列之前发出。要移除的项目是在给定的parent 项目下，介于first 和last 之间（含 ）的项目。

另请参阅 removeColumns() 和beginRemoveColumns()。

[private signal] void QAbstractItemModel::columnsInserted(const QModelIndex &parent, int first, int last)

该信号在列插入模型后发出。新项目是在给定的parent 项目下，介于first 和last 之间的项目。

另请参阅 insertColumns() 和beginInsertColumns()。

[private signal] void QAbstractItemModel::columnsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

该信号在模型中的列被移动后发出。在给定的sourceParent 项下，介于sourceStart 和sourceEnd 之间（包括 ）的项已被移动到destinationParent ，从destinationColumn 列开始。

注：连接到此信号的组件使用它来适应模型尺寸的变化。该信号只能由QAbstractItemModel 实现发出，不能在子类代码中明确发出。

另请参阅 beginMoveRows().

[private signal] void QAbstractItemModel::columnsRemoved(const QModelIndex &parent, int first, int last)

从模型中移除列后发出此信号。移除的项目是在给定的parent 项目下，介于first 和last 之间（含 ）的项目。

另请参阅 removeColumns() 和beginRemoveColumns()。

[protected] QModelIndex QAbstractItemModel::createIndex(int row, int column, const void *ptr = nullptr) const

使用内部指针ptr 为给定的row 和column 创建模型索引。

使用QSortFilterProxyModel 时，其索引有自己的内部指针。建议不要在模型之外访问该内部指针。请使用data() 函数。

该函数提供了一个一致的接口，模型子类必须使用该接口来创建模型索引。

[protected] QModelIndex QAbstractItemModel::createIndex(int row, int column, quintptr id) const

使用内部标识符id 为给定的row 和column 创建模型索引。

该函数提供了一个一致的接口，模型子类必须使用该接口来创建模型索引。

另请参阅 QModelIndex::internalId() 。

[pure virtual invokable] QVariant QAbstractItemModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

返回role 下存储的index 所指项目的数据。

另请参阅 Qt::ItemDataRole,setData() 和headerData() 。

[signal] void QAbstractItemModel::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

每当现有项目中的数据发生变化时，就会发出该信号。

如果项目属于同一父级，则受影响的项目是topLeft 和bottomRight （含）之间的项目。如果项目的父项不相同，则行为未定义。

在重新实现setData() 函数时，必须明确发出该信号。

可选的roles 参数可用于指定哪些数据角色实际上已被修改。角色参数中的空向量表示所有角色都被视为已修改。角色参数中元素的顺序与此无关。

另请参阅 headerDataChanged()、setData() 和layoutChanged()。

[virtual] bool QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

处理以给定的action 结束的拖放操作所提供的data 。

如果模型处理了数据和操作，则返回true ；否则返回false 。

指定的row 、column 和parent 表示操作结束时项目在模型中的位置。模型有责任在正确的位置完成操作。

例如，对QTreeView 中的项目执行下拉操作后，会插入新项目作为row,column, 和parent 所指定项目的子项，或作为项目的同级项。

当row 和column 为-1 时，意味着被删除的数据应被视为直接在parent 上被删除。通常，这意味着将数据作为parent 的子项目追加。如果row 和column 大于或等于零，则表示丢弃发生在指定的row 和column 之前，在指定的parent 中。

调用mimeTypes() 成员可获取可接受的 MIME 类型列表。该默认实现假定mimeTypes() 的默认实现是返回单一默认 MIME 类型。如果您在自定义模型中重新实现mimeTypes() 以返回多个 MIME 类型，则必须重新实现此函数才能使用它们。

另请参阅 supportedDropActions()、canDropMimeData() 和使用项目视图拖放。

[protected] void QAbstractItemModel::endInsertColumns()

结束列插入操作。

在子类中重新实现insertColumns() 时，必须在将数据插入模型的底层数据存储后调用该函数。

另请参阅 beginInsertColumns()。

[protected] void QAbstractItemModel::endInsertRows()

结束行插入操作。

在子类中重新实现insertRows() 时，必须在将数据插入模型的底层数据存储后调用该函数。

另请参阅 beginInsertRows()。

[protected] void QAbstractItemModel::endMoveColumns()

结束列移动操作。

在实现子类时，必须在模型的底层数据存储中移动数据后调用此函数。

另请参阅 beginMoveColumns()。

[protected] void QAbstractItemModel::endMoveRows()

结束行移动操作。

在实现子类时，必须在模型的底层数据存储中移动数据后调用此函数。

另请参见 beginMoveRows()。

[protected] void QAbstractItemModel::endRemoveColumns()

结束列删除操作。

在子类中重新实现removeColumns() 时，必须在从模型的底层数据存储中删除数据后调用此函数。

另请参阅 beginRemoveColumns()。

[protected] void QAbstractItemModel::endRemoveRows()

结束行删除操作。

在子类中重新实现removeRows() 时，必须在从模型的底层数据存储中删除数据后调用此函数。

另请参阅 beginRemoveRows()。

[protected] void QAbstractItemModel::endResetModel()

完成模型重置操作。

您必须在重置模型或代理模型中的任何内部数据结构后调用此函数。

此函数会发出modelReset() 信号。

另请参阅 beginResetModel().

[virtual invokable] void QAbstractItemModel::fetchMore(const QModelIndex &parent)

获取parent 索引指定的父项的任何可用数据。

如果要逐步填充模型，请重新执行此操作。

默认实现不做任何操作。

另请参阅 canFetchMore() 。

[virtual invokable] Qt::ItemFlags QAbstractItemModel::flags(const QModelIndex &index) const

返回给定index 的项目标志。

基类实现返回启用项目 (ItemIsEnabled) 和允许选择项目 (ItemIsSelectable) 的标志组合。

另请参见 Qt::ItemFlags 。

[virtual invokable] bool QAbstractItemModel::hasChildren(const QModelIndex &parent = QModelIndex()) const

如果parent 有子代，则返回true ；否则返回false 。

在父索引上使用rowCount() 查找子索引的数量。

请注意，如果同一索引设置了标志Qt::ItemNeverHasChildren ，则使用此方法报告特定索引 hasChildren 是未定义的行为。

另请参阅 parent() 和index()。

[invokable] bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent = QModelIndex()) const

如果模型返回一个有效的QModelIndex ，row ，column ，则返回true ，否则返回parent ，否则返回false 。

[virtual invokable] QVariant QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

返回标题中给定的role 和section 的数据以及指定的orientation 。

对于水平标题，节号与列号相对应。同样，对于垂直标题，节号与行号相对应。

另请参阅 Qt::ItemDataRole,setHeaderData() 和QHeaderView 。

[signal] void QAbstractItemModel::headerDataChanged(Qt::Orientation orientation, int first, int last)

每当页眉发生变化时，就会发出该信号。orientation 表示水平或垂直页眉是否发生了变化。从first 到last 的页眉部分需要更新。

在重新实现setHeaderData() 函数时，必须明确发出该信号。

如果要更改列数或行数，则无需发出此信号，而应使用 begin/end 函数（详情请参阅QAbstractItemModel 类说明中的子类化部分）。

另请参见 headerData()、setHeaderData() 和dataChanged()。

[pure virtual invokable] QModelIndex QAbstractItemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

返回由给定的row 、column 和parent 索引指定的模型中项的索引。

在子类中重新实现此函数时，请调用createIndex() 来生成模型索引，其他组件可以用它来引用模型中的项目。

另请参阅 createIndex() 。

[invokable] bool QAbstractItemModel::insertColumn(int column, const QModelIndex &parent = QModelIndex())

在parent 的子项目中，在给定的column 之前插入单列。

如果列已插入，则返回true ；否则返回false 。

另请参阅 insertColumns()、insertRow() 和removeColumn()。

[virtual invokable] bool QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型中，会在给定的column 之前向模型中插入count 新列。每个新列中的项都将是parent 模型索引所代表项的子项。

如果column 为 0，这些列将被预先添加到任何现有列中。

如果column 为columnCount() ，则会将列添加到任何现有列中。

如果parent 没有子代，则插入包含count 列的单行。

如果成功插入列，则返回true ；否则返回false 。

基类实现什么也不做，返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持插入。或者，您也可以提供自己的 API 来更改数据。

另请参阅 insertRows()、removeColumns()、beginInsertColumns() 和endInsertColumns() 。

[invokable] bool QAbstractItemModel::insertRow(int row, const QModelIndex &parent = QModelIndex())

在parent 的子项目中，在给定的row 之前插入一行。

如果行已插入，则返回true ；否则返回false 。

另请参阅 insertRows()、insertColumn() 和removeRow()。

[virtual invokable] bool QAbstractItemModel::insertRows(int row, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型上，会在给定的row 之前向模型中插入count 行。新行中的项将是parent 模型索引所代表项的子项。

如果row 为 0，这些行将被预先添加到父代中的任何现有行中。

如果row 为rowCount() ，则会将行添加到父代中的任何现有行中。

如果parent 没有子代，则会插入一列count 行。

如果行已成功插入，则返回true ；否则返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持插入。或者，您也可以提供自己的 API 来更改数据。无论哪种情况，您都需要调用beginInsertRows() 和endInsertRows() 来通知其他组件模型已更改。

另请参阅 insertColumns()、removeRows()、beginInsertRows() 和endInsertRows()。

[virtual] QMap<int, QVariant> QAbstractItemModel::itemData(const QModelIndex &index) const

返回一个包含模型中所有预定义角色值的映射，该模型适用于给定index 的项目。

如果您想扩展此函数的默认行为以在映射中包含自定义角色，请重新实现此函数。

另请参阅 setItemData(),Qt::ItemDataRole 和data()。

[signal] void QAbstractItemModel::layoutAboutToBeChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

该信号在模型布局改变之前发出。连接到此信号的组件使用它来适应模型布局的变化。

子类应在发出 layoutAboutToBeChanged() 信号后更新任何持久化模型索引。

可选的parents 参数用于提供更具体的通知，说明模型布局的哪些部分正在发生变化。空列表表示整个模型的布局发生了变化。parents 列表中元素的顺序并不重要。可选的hint 参数用于提示模型在中继布局时发生了什么变化。

另请参阅 layoutChanged() 和changePersistentIndex()。

[signal] void QAbstractItemModel::layoutChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

当模型暴露的项的布局发生变化时（例如，模型已排序），就会发出该信号。当视图接收到此信号时，它应更新项的布局以反映这一变化。

在子类化QAbstractItemModel 或QAbstractProxyModel 时，请确保在改变项目顺序或改变向视图公开的数据结构之前发出layoutAboutToBeChanged() 信号，并在改变布局后发出 layoutChanged() 信号。

可选的parents 参数用于发出更具体的通知，说明模型布局的哪些部分发生了变化。空列表表示整个模型的布局发生了变化。parents 列表中元素的顺序并不重要。可选的hint 参数用于在模型中继时提示正在发生的事情。

子类应在发出 layoutChanged() 之前更新任何持久化模型索引。换句话说，当结构发生变化时

• 发出layoutAboutToBeChanged
• 记住将发生变化的QModelIndex
• 更新内部数据
• 调用changePersistentIndex()
• 发出 layoutChanged

另请参阅 layoutAboutToBeChanged(),dataChanged(),headerDataChanged(),modelReset() 和changePersistentIndex().

[virtual invokable] QModelIndexList QAbstractItemModel::match(const QModelIndex &start, int role, const QVariant &value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags(Qt::MatchStartsWith|Qt::MatchWrap)) const

返回start 索引列中的项的索引列表，其中给定的role 下存储的数据与指定的value 匹配。搜索方式由给定的flags 定义。返回的列表可能为空。还需注意的是，如果使用的是代理模型等，列表中结果的顺序可能与模型中的顺序不一致。搜索结果的顺序不可依赖。

搜索从start 索引开始，直到匹配数据项的数量等于hits ，搜索到达最后一行，或者搜索再次到达start - 这取决于flags 中是否指定了MatchWrap 。如果要搜索所有匹配项，请使用hits =-1。

默认情况下，该函数将对所有项目执行基于字符串的包装比较，搜索以value 指定的搜索词开头的项目。

[virtual] QMimeData *QAbstractItemModel::mimeData(const QModelIndexList &indexes) const

返回一个对象，该对象包含与指定的indexes 列表相对应的序列化数据项。用于描述编码数据的格式可从mimeTypes() 函数中获取。本默认实现使用mimeTypes() 的默认实现返回的默认 MIME 类型。如果您在自定义模型中重新实现mimeTypes() 以返回更多 MIME 类型，请重新实现此函数以使用它们。

如果indexes 的列表为空，或没有支持的 MIME 类型，则返回nullptr 而不是序列化的空列表。

另请参阅 mimeTypes() 和dropMimeData()。

[virtual] QStringList QAbstractItemModel::mimeTypes() const

返回允许的 MIME 类型列表。默认情况下，内置模型和视图使用内部 MIME 类型：application/x-qabstractitemmodeldatalist 。

在自定义模型中实现拖放支持时，如果要以默认内部 MIME 类型以外的格式返回数据，则应重新实现此函数以返回 MIME 类型列表。

如果在自定义模型中重新实现该函数，还必须重新实现调用该函数的成员函数：mimeData() 和dropMimeData()。

另请参阅 mimeData() 和dropMimeData()。

[private signal] void QAbstractItemModel::modelAboutToBeReset()

当调用beginResetModel() 时，在模型的内部状态（如持久化模型索引）失效之前，会发出此信号。

另请参阅 beginResetModel() 和modelReset()。

[private signal] void QAbstractItemModel::modelReset()

当调用endResetModel() 时，在模型的内部状态（如持久化模型索引）失效后，会发出该信号。

需要注意的是，如果模型被重置，则应认为先前从中获取的所有信息都已失效。这包括但不限于rowCount() 和columnCount(),flags(), 通过data() 和roleNames() 提取的数据。

另请参阅 endResetModel() 和modelAboutToBeReset()。

[invokable] bool QAbstractItemModel::moveColumn(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，将sourceColumn 从sourceParent 移动到destinationParent 下的destinationChild 。

如果列移动成功，则返回true ；否则返回false 。

另请参阅 moveColumns() 和moveRow()。

[virtual invokable] bool QAbstractItemModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，将父sourceParent 下从给定的sourceColumn 开始的count 列移动到父destinationParent 下的destinationChild 列。

如果列成功移动，则返回true ；否则返回false 。

基类实现什么也不做，返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持移动。或者，您也可以提供自己的 API 来更改数据。

另请参阅 beginMoveColumns() 和endMoveColumns()。

[invokable] bool QAbstractItemModel::moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，将sourceRow 从sourceParent 移至destinationParent 下的destinationChild 。

如果行已成功移动，则返回true ；否则返回false 。

另请参阅 moveRows() 和moveColumn()。

[virtual invokable] bool QAbstractItemModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)

在支持此功能的模型上，会将父sourceParent 下从给定的sourceRow 开始的count 行移动到父destinationParent 下的destinationChild 行。

如果行已成功移动，则返回true ；否则返回false 。

基类实现什么也不做，返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持移动。或者，您也可以提供自己的 API 来更改数据。

另请参阅 beginMoveRows() 和endMoveRows()。

[virtual, since 6.0] void QAbstractItemModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const

用给定index 的请求数据填充roleDataSpan 。

默认实现会为 span 中的每个角色简单调用data() 函数。子类可以重新实现该函数，以便更有效地向视图提供数据：

void MyModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const
{
    for (QModelRoleData &roleData : roleDataSpan) {
        int role = roleData.role();

        // ... obtain the data for index and role ...

        roleData.setData(result);
    }
}

在上面的代码段中，index 在整个调用过程中都是一样的。这意味着只需访问一次必要的数据结构，就能为index 获取信息（将相关代码吊出循环）。

我们鼓励使用QModelRoleData::setData() 或类似的QVariant::setValue() 而不是单独构建QVariant 和使用普通赋值操作符；这是因为前者允许重新使用已为存储在QModelRoleData 中的QVariant 对象分配的内存，而后者总是分配新的变量，然后销毁旧的变量。

需要注意的是，视图在调用 multiData() 时可能会使用之前调用过的跨度，因此可能已经包含了一些数据。因此，如果模型无法返回给定角色的数据，就必须清除相应QModelRoleData 对象中的数据。这可以通过调用QModelRoleData::clearData() 来实现，或者类似地通过设置默认构造QVariant 等来实现。如果不清除数据，视图就会认为 "旧 "数据应该用于相应的角色。

最后，为了避免代码重复，子类也可以决定用 multiData() 来重新实现data()，方法是只提供一个元素的跨度：

QVariant MyModel::data(const QModelIndex &index, int role) const
{
    QModelRoleData roleData(role);
    multiData(index, roleData);
    return roleData.data();
}

此函数在 Qt 6.0 中引入。

另请参阅 QModelRoleDataSpan 和data()。

[pure virtual invokable] QModelIndex QAbstractItemModel::parent(const QModelIndex &index) const

返回给定index 的模型项的父节点。如果项没有父项，则返回无效的QModelIndex 。

在暴露树形数据结构的模型中，一个常用的惯例是只有第一列中的项才有子项。在这种情况下，当在子类中重新实现此函数时，返回的QModelIndex 的列将是 0。

在子类中重新实现此函数时，请注意避免调用QModelIndex 成员函数，如QModelIndex::parent() ，因为属于您的模型的索引会简单地调用您的实现，从而导致无限递归。

另请参见 createIndex() 。

[protected] QModelIndexList QAbstractItemModel::persistentIndexList() const

返回模型中作为持久性索引存储的索引列表。

[invokable] bool QAbstractItemModel::removeColumn(int column, const QModelIndex &parent = QModelIndex())

从parent 的子项目中删除给定的column 。

如果列被移除，则返回true ；否则返回false 。

另请参阅 removeColumns()、removeRow() 和insertColumn()。

[virtual invokable] bool QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型上，从模型中移除父parent 下以给定column 开始的count 列。

如果列已成功移除，则返回true ；否则返回false 。

基类实现什么也不做，返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持移除功能。或者，您也可以提供自己的 API 来更改数据。

另请参阅 removeColumn()、removeRows()、insertColumns()、beginRemoveColumns() 和endRemoveColumns() 。

[invokable] bool QAbstractItemModel::removeRow(int row, const QModelIndex &parent = QModelIndex())

从parent 的子项目中删除给定的row 。

如果行已删除，则返回true ；否则返回false 。

这是一个调用removeRows() 的方便函数。QAbstractItemModel 实现的removeRows() 不做任何操作。

另请参阅 removeRows()、removeColumn() 和insertRow()。

[virtual invokable] bool QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型上，从模型中删除从父级parent 下的给定row 开始的count 行。

如果行已成功移除，则返回true ；否则返回false 。

基类实现什么也不做，返回false 。

如果要实现自己的模型，可以重新实现此函数，以支持移除操作。或者，您也可以提供自己的 API 来更改数据。

另请参阅 removeRow()、removeColumns()、insertColumns()、beginRemoveRows() 和endRemoveRows() 。

[virtual protected slot] void QAbstractItemModel::resetInternalData()

在重置模型时，模型的内部数据刚被清除，这个槽就会被调用。

提供此槽是为了方便具体代理模型的子类，如维护额外数据的QSortFilterProxyModel 的子类。

class CustomDataProxy : public QSortFilterProxyModel
{
    Q_OBJECT
public:
    CustomDataProxy(QObject *parent)
      : QSortFilterProxyModel(parent)
    {
    }

    ...

    QVariant data(const QModelIndex &index, int role) override
    {
        if (role != Qt::BackgroundRole)
            return QSortFilterProxyModel::data(index, role);

        if (m_customData.contains(index.row()))
            return m_customData.value(index.row());
        return QSortFilterProxyModel::data(index, role);
    }

private slots:
    void resetInternalData()
    {
        m_customData.clear();
    }

private:
  QHash<int, QVariant> m_customData;
};

另请参阅 modelAboutToBeReset() 和modelReset()。

[virtual slot] void QAbstractItemModel::revert()

让模型知道它应该丢弃缓存信息。此函数通常用于行编辑。

另请参阅 submit()。

[virtual] QHash<int, QByteArray> QAbstractItemModel::roleNames() const

返回模型的角色名称。

Qt 设置的默认角色名称是

[pure virtual invokable] int QAbstractItemModel::rowCount(const QModelIndex &parent = QModelIndex()) const

返回给定parent 下的行数。当父节点有效时，rowCount 将返回父节点的子节点数。

另请参阅 columnCount() 。

[private signal] void QAbstractItemModel::rowsAboutToBeInserted(const QModelIndex &parent, int start, int end)

该信号在行被插入模型之前发出。新项目将被放置在start 和end 之间（含 ），位于给定的parent 项目之下。

另请参阅 insertRows() 和beginInsertRows()。

[private signal] void QAbstractItemModel::rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

此信号在模型内移动行之前发出。将被移动的项目是sourceStart 和sourceEnd 之间（含 ）的项目，位于给定的sourceParent 项目之下。它们将从destinationRow 行开始被移动到destinationParent 。

注：连接到此信号的组件使用它来适应模型尺寸的变化。该信号只能由QAbstractItemModel 实现发出，不能在子类代码中明确发出。

另请参阅 beginMoveRows().

[private signal] void QAbstractItemModel::rowsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

该信号在从模型中移除行之前发出。将被移除的条目是first 和last 之间（含 ）的条目，位于给定的parent 条目之下。

另请参阅 removeRows() 和beginRemoveRows()。

[private signal] void QAbstractItemModel::rowsInserted(const QModelIndex &parent, int first, int last)

此信号在行被插入模型后发出。新项目是在给定的parent 项目下，介于first 和last 之间的项目。

另请参阅 insertRows() 和beginInsertRows()。

[private signal] void QAbstractItemModel::rowsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

此信号在模型中的行被移动后发出。从给定的sourceParent 项开始，介于sourceStart 和sourceEnd 之间（包括 ）的项已被移动到destinationParent destinationRow 行。

注：连接到此信号的组件使用它来适应模型尺寸的变化。它只能由QAbstractItemModel 实现发出，不能在子类代码中明确发出。

另请参阅 beginMoveRows().

[private signal] void QAbstractItemModel::rowsRemoved(const QModelIndex &parent, int first, int last)

此信号在从模型中移除记录后发出。移除的项目是在给定的parent 项目下，介于first 和last 之间（含 ）的项目。

另请参阅 removeRows() 和beginRemoveRows()。

[virtual invokable] bool QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

将index 项目的role 数据设置为value 。

如果成功，则返回true ；否则返回false 。

如果数据设置成功，则应发出dataChanged() 信号。

基类实现返回false 。对于可编辑模型，必须重新实现此函数和data() 。

另请参阅 Qt::ItemDataRole,data() 和itemData() 。

[virtual] bool QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)

将页眉中给定的role 和section 的数据与指定的orientation 设置为所提供的value 。

如果页眉数据已更新，则返回true ；否则返回false 。

重新实现此函数时，必须明确发出headerDataChanged() 信号。

另请参阅 Qt::ItemDataRole 和headerData()。

[virtual] bool QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)

将index 中项目的角色数据设置为roles 中的相关值，每Qt::ItemDataRole 。

如果成功，则返回true ；否则返回false 。

不在roles 中的角色不会被修改。

另请参阅 setData()、data() 和itemData()。

[virtual invokable] QModelIndex QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const

返回位于index 的项目在row 和column 的同级项目，如果该位置没有同级项目，则返回无效的QModelIndex 。

sibling()只是一个方便的函数，它可以找到项目的父节点，并用它来检索子项目在指定的row 和column 中的索引。

可以选择重载此方法，以实现特定的优化。

另请参阅 index()、QModelIndex::row() 和QModelIndex::column()。

[virtual invokable] void QAbstractItemModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

在给定的order 中按column 对模型排序。

基类实现不做任何操作。

[virtual] QSize QAbstractItemModel::span(const QModelIndex &index) const

返回index 所代表项目的行跨度和列跨度。

[virtual slot] bool QAbstractItemModel::submit()

让模型知道它应该将缓存信息提交到永久存储区。此函数通常用于行编辑。

如果没有错误，则返回true ；否则返回false 。

另请参阅 revert() 。

[virtual] Qt::DropActions QAbstractItemModel::supportedDragActions() const

返回此模型中的数据所支持的操作。

默认实现返回supportedDropActions() 。如果希望支持其他操作，请重新实现此函数。

当发生拖动时，QAbstractItemView::startDrag() 会将 supportedDragActions() 用作默认值。

另请参阅 Qt::DropActions 和在项目视图中使用拖放。

[virtual] Qt::DropActions QAbstractItemModel::supportedDropActions() const

返回此模型支持的下拉操作。

默认实现返回Qt::CopyAction 。如果您希望支持其他操作，请重新实现此函数。您还必须重新实现dropMimeData() 函数以处理附加操作。

另请参阅 dropMimeData()、Qt::DropActions 以及与项目视图一起使用拖放功能。