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)

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

注意：连接到此信号的组件会利用它来适应模型尺寸的变化。该信号只能由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()。

将left QVariant 与right QVariant 进行比较，并将排序结果作为weak ordering 返回。

如果将QVariant 作为字符串进行比较，则会使用可选的collator 对象进行locale-aware 和case-sensitive 比较。如果未提供排序器，则字符串仅根据字符的数值Unicode值进行比较。这种方式速度很快，但往往不符合用户对用户界面的预期。

该函数适用于QAbstractItemModel::sort()的实现，即使对于无法比较的变体值（即QVariant::compare 会返回unordered 的情况），也能提供弱排序。这使得该函数可在std::sort 和std::stable_sort 中安全使用，因为这些操作要求数据能够被排序。

void Model::sort(int column, Qt::SortOrder sortOrder)
{
    // Model operates on a QList<QVariant> data
    std::sort(data.begin(), data.end(), [=](const QVariant &lhs, const Variant &rhs){
        const auto ordering = compareData(lhs, rhs);
        return sortOrder == Qt::AscendingOrder ? sortOrder < 0 : sortOrder > 0;
    });
}

如果left QVariant 包含一个字符串，则会使用可选的collator 对变体进行比较as strings 。

否则，实现将使用QVariant::compare() 比较left 和right ，该方法只能提供部分排序。如果比较产生unordered 结果，且left 和right 的meta type 不相同，则该函数会尝试将变体convert 转换为共同类型，并重新进行比较。

如果这仍然产生unordered 的结果，则比较两个变体的字符串表示。这可能会比较两个空字符串，它们在{Qt::weak_ordering::}中被视为{equivalent}。

Invalid variants 始终比持有有效值的变体大。

这些函数在 Qt 6.12 中引入。

另请参阅 三元比较、sort()、QVariant::compare 以及QSortFilterProxyModel 。

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

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

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

该函数提供了一个统一的接口，模型子类必须通过此接口来创建模型索引。

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

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

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

另请参阅 QModelIndex::internalId()。

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

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

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

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

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

如果这些项属于同一个父项，则受影响的项范围为topLeft 到bottomRight （含这两个端点）。如果这些项不属于同一个父项，则行为未定义。

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

可选的roles 参数可用于指定哪些数据角色实际上已被修改。如果 roles 参数为空向量，则表示应将所有角色视为已修改。roles 参数中元素的顺序没有任何意义。

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

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

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

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

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

例如，对QTreeView 中的某个项执行拖放操作时，新项可能会作为row 、column 和parent 所指定的项的子项插入，也可能作为该项的同级项插入。

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

调用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

如果模型针对row 和column （同时满足parent ）返回有效的QModelIndex ，则返回true ；否则返回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())

在支持此功能的模型中，该操作会在模型中将count 个新列插入到指定的column 之前。每个新列中的项将成为由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() 之前更新任何持久化模型索引。换言之，当结构发生变化时：

• emitlayoutAboutToBeChanged
• 记住即将发生变化的QModelIndex
• 更新内部数据
• 调用changePersistentIndex()
• emit 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 移动到destinationChild ，位于destinationParent 之下。

如果列已成功移动，则返回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 移动到destinationChild ，路径为destinationParent 。

如果行已成功移动，则返回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 对象已分配的内存，而后者总是会分配新的变体并销毁旧的。

请注意，视图可能会使用在先前调用中已用过的跨度（spans）来调用 multiData()，因此这些跨度可能已经包含某些数据。因此，如果模型无法返回给定角色的数据，则必须清除相应QModelRoleData 对象中的数据，这一点至关重要。 这可以通过调用QModelRoleData::clearData()来实现，或者类似地，通过设置一个默认构造的QVariant 等方法来实现。如果未能清除数据，将导致视图误以为应使用“旧”数据来处理相应角色。

最后，为了避免代码重复，子类还可以选择通过向`multiData()`提供仅包含一个元素的span，来重写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) const 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)

该信号在模型内部移动行之前触发。将被移动的项是位于给定sourceParent 项之下、介于sourceStart 和sourceEnd （含两端）之间的项。这些项将被移动到destinationParent ，起始行号为destinationRow 。

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

另请参阅 beginMoveRows()。

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

该信号在行从模型中移除之前触发。将被移除的项目是位于给定parent 项之下、介于first 和last （含这两个值）之间的项目。

另请参阅 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)

将指定orientation 的标头中role 和section 字段的数据设置为提供的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

返回位于row 和column 处的、与位于index 的项对应的同级项；如果该位置没有同级项，则返回无效的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 以及《在项目视图中使用拖放功能》。