QAbstractItemModel 类

成员函数文档

[显式] QAbstractItemModel::QAbstractItemModel(QObject *parent = nullptr)

使用给定的 parent 构造一个抽象项模型。

[虚函数 noexcept] QAbstractItemModel::~QAbstractItemModel()

销毁抽象项模型。

[受保护] 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行之前插入3行，因此first为2，last为4 beginInsertRows(parent, 2, 4); 这将把3个新行作为第2、3、4行插入。
追加行	要追加行，请在最后一行之后插入它们。 例如，如图所示，我们在4行（结束于第3行）的集合后追加2行，因此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); 这将在源中将3行2、3和4移动到2、3和4行，其他受影响的兄弟项将相应位移。
将行移动到另一个父项后追加	要追加行到另一个父项，请将它们移动到最后一行之后。 例如，如图所示，我们将3行移动到现有行集合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列的3列，所以first是4，last是6。 beginRemoveColumns(parent, 4, 6);

另请参阅 endRemoveColumns().

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

开始执行行删除操作。

在子类中重写removeRows() 方法时，必须在从模型的基础数据存储中删除数据之前调用此函数。

父索引对应于要从中删除新行的父索引；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() 中。

如果要在自定义模型中重新实现此函数，以便测试数据是否可以丢弃在 行、列、父项 处，并以 操作 丢弃。如果不需要该测试，则不需要重新实现此函数。

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

[虚可调用] bool QAbstractItemModel::canFetchMore(const QModelIndex &parent) const

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

默认实现始终返回 false。

如果 canFetchMore() 返回 true，则应调用 fetchMore() 函数。例如，QAbstractItemView 就会执行此操作。

另请参阅 fetchMore。

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

将等于给定 from 模型索引的 QPersistentModelIndex 替换为给定 to 模型索引。

如果没有发现等于给定 from 模型索引的持久化模型索引，则不进行任何更改。

另请参阅 persistentIndexList() 和 changePersistentIndexList。

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

将等于给定 from 模型索引列表中的索引的 QPersistentModelIndex 替换为给定 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。

[虚拟，自6.0版以来] bool QAbstractItemModel::clearItemData(const QModelIndex &index)

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

此函数是在Qt 6.0中引入的。

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

[纯虚函数调用] int QAbstractItemModel::columnCount(const QModelIndex &parent = QModelIndex()) const

返回给定父的子项的列数。

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

例如

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

另请参阅 rowCount()。

[私有信号] void QAbstractItemModel::columnsAboutToBeInserted(const QModelIndex &parent, int first, int last)

此信号在列插入模型之前发出。新项目将位于给定 父 项目下的 第一 和 最后一 项之间，包含在内。

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

[私有信号] void QAbstractItemModel::columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

此信号在列在模型内移动之前发出。将要移动的项目是位于给定 源父 项目下的 源起始 和 源结束 之间，包含在内。它们将被移动到 目标父 项目，从列 目标列 开始。

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

另请参阅：beginMoveRows()。

[私有信号] void QAbstractItemModel::columnsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

此信号在从模型中删除列之前发出。要删除的项目是位于给定 父 项目下的 第一 和 最后一 项之间，包含在内。

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

[私有信号] void QAbstractItemModel::columnsInserted(const QModelIndex &parent, int first, int last)

此信号在列被插入模型之后发出。新项目是位于给定 父 项目下的 第一 和 最后一 项之间，包含在内。

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

[私有信号] void QAbstractItemModel::columnsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

此信号在列在模型内被移动之后发出。位于给定 源父 项目下的 源起始 和 源结束 之间，包含在内，的项目已经被移动到 目标父 项目，从列 目标列 开始。

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

另请参阅：beginMoveRows()。

[私有信号] void QAbstractItemModel::columnsRemoved(const QModelIndex &parent, int first, int last)

在从模型中删除列后，将发出此信号。被删除的项包括在给定 parent 项目下的 first 和 last 之间（包括两个端点）的项目。

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

[受保护的] QModelIndex QAbstractItemModel::createIndex(int row, int column, const void *ptr = nullptr) const

为指定的 row 和 column 创建一个具有内部指针 ptr 的模型索引。

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

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

[受保护的] QModelIndex QAbstractItemModel::createIndex(int row, int column, quintptr id) const

为指定的 row 和 column 创建一个带内部标识符 id 的模型索引。

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

另请参阅QModelIndex::internalId().

[纯虚调用] QVariant QAbstractItemModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

返回由 index 指向的项目在给定的 role 下存储的数据。

另请参阅Qt::ItemDataRole、setData 和 headerData。

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

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

如果项目属于同一父项，则受影响的项目是那些在 topLeft 和 bottomRight 之间（包括两个端点）。如果项目不属于同一父项，则行为未定义。

在重新实现 setData() 函数时，必须显式发出此信号。

可选的 roles 参数可以用来指定哪些数据角色已被修改。在 roles 参数中为空向量表示应考虑所有角色已修改。roles 参数中元素的顺序没有意义。

参见 headerDataChanged()、setData() 以及 layoutChanged()。

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

处理由给定的 action 结束的拖放操作提供的数据。

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

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

例如，在 QTreeView 中的一个项上的拖放操作可能会导致新项作为 row、column 和 parent 指定的项的子项被插入，或者作为该项的兄弟项。

当 row 和 column 是 -1 时，意味着应将 dropped 数据视为直接放在 parent 上。通常这表示将数据追加为 parent 的子项。如果 row 和 column 大于或等于零，这意味着在指定的 parent 中指定的 row 和 column 之前发生拖放。

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

参见 supportedDropActions()、canDropMimeData() 以及 使用项视图进行拖放。

[保护函数] void QAbstractItemModel::endInsertColumns()

结束列插入操作。

在子类中重新实现 insertColumns() 时，您必须在向模型的基本数据存储插入数据之后调用此函数。

参见 beginInsertColumns()。

[保护函数] void QAbstractItemModel::endInsertRows()

结束行插入操作。

在子类中重新实现 insertRows() 时，您必须在向模型的基本数据存储插入数据之后调用此函数。

参见 beginInsertRows()。

[保护函数] 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

如果父项有任何子项，返回true，否则返回false。

使用rowCount() 在父项上以找出子项的数量。

注意，如果同样的索引设置了标志Qt::ItemNeverHasChildren，使用此方法报告特定索引是否有子项是不确定的。

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

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

如果模型返回对 row 和 column 以及 parent 的有效 QModelIndex，则返回 true，否则返回 false。

[虚拟可调用] QVariant QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

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

对于水平标题，部分号对应于列号。类似地，对于垂直标题，部分号对应于行号。

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

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

每次更改标题时都会发出此信号。 orientation 表示是否更改了横向或纵向标题。从 first 到 last 的标题部分需要更新。

在重写 setHeaderData() 函数时，必须显式发出此信号。

如果您正在更改列数或行数，则不需要发出此信号，而是使用 begin/end 函数（有关详细信息，请参阅 QAbstractItemModel 类描述中的子类部分）。

另请参阅headerData、setHeaderData 和 dataChanged。

[纯虚拟可调用] QModelIndex QAbstractItemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

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

在子类中重写此函数时，调用 createIndex() 以生成模型索引，其他组件可以用来引用您的模型中的项。

另请参阅createIndex。

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

在指定 parent 指定的子项中在给定 column 前插入单个列。

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

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

[虚拟可调用] bool QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

在支持此功能的模型中，在指定的列之前向模型中插入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())

在指定的row之前向parent指定的子项插入单个行。

如果成功插入行，则返回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()。

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

返回一个包含给定 index 处模型项所有预设角色的值的映射。

若要扩展该函数，使其在映射中包含自定义角色，请重新实现此函数。

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

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

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

在发出 layoutAboutToBeChanged() 之后，子类应该更新任何持久的模型索引。

可选的 parents 参数用于提供有关模型布局的哪些部分正在改变的更具体的通知。空列表表示整个模型布局的改变。列表中元素的出现顺序是不重要的。可选的 hint 参数用于在模型重新布局时提供发生操作的提示。

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

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

每当模型公开的项的布局发生变化时（例如模型被排序时），都会发出此信号。当视图接收到此信号时，应更新项的布局以反映此变化。

当子类化 QAbstractItemModel 或 QAbstractProxyModel 时，确保在更改项的顺序或更改您对视图公开的数据结构之前调用 layoutAboutToBeChanged()，并在更改布局后发出 layoutChanged()。

可选的 parents 参数用于提供有关模型布局的哪些部分正在改变的更具体的通知。空列表表示整个模型布局的改变。列表中元素的出现顺序是不重要的。可选的 hint 参数用于在模型重新布局时提供发生操作的提示。

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

• 发出 layoutAboutToBeChanged
• 记住将要改变的 QModelIndex
• 更新你的内部数据
• 调用 changePersistentIndex()
• 发出布局已改变

另请参阅layoutAboutToBeChanged()，dataChanged()，headerDataChanged()，modelReset() 和 changePersistentIndex()。

[可虚拟调用] 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指定的搜索词开头的项。

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

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

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

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

[虚拟] QStringList QAbstractItemModel::mimeTypes() const

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

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

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

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

[私有信号] void QAbstractItemModel::modelAboutToBeReset()

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

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

[私有信号] void QAbstractItemModel::modelReset()

当调用endResetModel()函数时，发出此信号，在模型内部状态（例如持久模型索引）无效化之后。

请注意，如果重置模型，应考虑从模型检索的所有以前信息都是无效的。这包括但不限于rowCount() 和 columnCount()、flags()、通过 data() 检索的数据以及 roleNames()。

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

[可调用的] bool QAbstractItemModel::moveColumn(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)

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

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

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

[虚可调用的] 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()。

[可调用的] bool QAbstractItemModel::moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)

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

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

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

[可虚拟调用] 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。

[虚拟，自6.0以来] void QAbstractItemModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const

使用 index 给定的数据填充 roleDataSpan。

默认实现将简单地调用每个角色的 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 等。未能清除数据将导致视图相信“旧”数据应为相应角色使用。

最后，为了避免代码冗余，子类还可以决定用 data 的方式重新实现，通过供应一个仅包含一个元素的跨度。

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

此函数是在Qt 6.0中引入的。

另请参阅 QModelRoleDataSpan 和 data。

[纯虚拟可调用] QModelIndex QAbstractItemModel::parent(const QModelIndex &index) const

返回具有给定索引的模型项的父项。如果该项没有父项，则返回一个无效的 QModelIndex。

在公开树数据结构的模型中，通常有一个常见的约定，即只有第一列的项有子项。对于这种情况，在子类中重新实现此函数时，返回的 QModelIndex 的列应该是 0。

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

另请参阅createIndex。

[受保护] QModelIndexList QAbstractItemModel::persistentIndexList() const

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

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

从指定的父项指定的子项中移除给定的 列。

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

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

[虚可调用] bool QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex()):

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

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

基类实现不执行任何操作，并返回false。

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

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

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

从指定的父项指定的子项中移除给定的 行。

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

这是一个便利函数，它调用 removeRows()。 QAbstractItemModel 的 removeRows() 实现不执行任何操作。

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

[虚拟可调用的] bool QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

在支持此特性的模型上，从给定 row 开始的父项 parent 下的 count 行将从模型中删除。

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

基类实现不执行任何操作，并返回false。

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

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

[虚拟保护槽] 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。

[虚拟槽] void QAbstractItemModel::revert()

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

另请参阅submit。

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

返回模型的角色名称。

Qt 默认设置的角色名称是这样的

[纯虚拟可调用的] int QAbstractItemModel::rowCount(const QModelIndex &parent = QModelIndex()) const

返回指定 parent 的行数。当父项有效时，意味着 rowCount 返回父项的子项数量。

另请参阅columnCount。

[私有信号] void QAbstractItemModel::rowsAboutToBeInserted(const QModelIndex &parent, int start, int end)

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

另请参阅insertRows() 和 beginInsertRows。

[私有信号] void QAbstractItemModel::rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

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

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

另请参阅：beginMoveRows()。

[私有信号] void QAbstractItemModel::rowsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

在从模型中移除行之前发出此信号。将要移除的项目是位于 first 到 last 之间（包括这些端点），在给定的 parent 项目下。

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

[私有信号] void QAbstractItemModel::rowsInserted(const QModelIndex &parent, int first, int last)

向模型插入行后发出此信号。新项目是位于 first 到 last 之间（包括这些端点），在给定的 parent 项目下。

另请参阅insertRows() 和 beginInsertRows。

[私有信号] void QAbstractItemModel::rowsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

在模型内移动行之后发出此信号。位于 sourceStart 到 sourceEnd 之间（包括这两个端点）且在给定的 sourceParent 项目下的项目已经被移动到从 destinationRow 行开始的 destinationParent。

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

另请参阅：beginMoveRows()。

[私有信号] void QAbstractItemModel::rowsRemoved(const QModelIndex &parent, int first, int last)

从模型中移除行之后发出此信号。被移除的项目是位于 first 到 last 之间（包括这些端点）且在给定的 parent 项目下。

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

[虚拟可调用] 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)

设置指定 orientation 的头部中相应 section 的 role 数据为提供的 value。

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

在重新实现此函数时，必须显式发出 headerDataChanged() 信号。

另请参阅Qt::ItemDataRole 和 headerData。

[virtual invokable] QModelIndex 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] void QAbstractItemModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

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

基类实现不做任何事情。

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

返回索引为 index 的项的行和列跨度。

[虚拟槽] bool QAbstractItemModel::submit()

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

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

另请参阅revert()。

[虚拟] Qt::DropActions QAbstractItemModel::supportedDragActions() const

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

默认实现返回 supportedDropActions()。如果希望支持更多操作，则重写此函数。

supportedDragActions() 用在 QAbstractItemView::startDrag() 中，作为拖动发生时的默认值。

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

[虚拟] Qt::DropActions QAbstractItemModel::supportedDropActions() const

返回此模型支持的拖放操作。

默认实现返回 Qt::CopyAction。如果希望支持更多操作，则重写此函数。同时，您还必须重写 dropMimeData() 函数以处理额外的操作。

另请参阅dropMimeData()、Qt::DropActions 和 使用项目视图中的拖放。