PySide6.QtCore.QAbstractItemModel

class QAbstractItemModel

QAbstractItemModel 类为项目模型类提供了抽象接口。更多…

PySide6.QtCore.QAbstractItemModel 的继承图

Inherited by: QFileSystemModel, QAbstractItemModelReplica, QPdfBookmarkModel, QHelpContentModel, QStandardItemModel, QConcatenateTablesProxyModel, QAbstractTableModel, QSqlQueryModel, QSqlTableModel, QSqlRelationalTableModel, QAbstractProxyModel, QTransposeProxyModel, QSortFilterProxyModel, QIdentityProxyModel, QAbstractListModel, QWebEngineHistoryModel, QPdfSearchModel, QPdfLinkModel, QStringListModel, QHelpIndexModel

概要

方法

虚拟方法

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

QAbstractItemModel 类定义了项目模型必须使用的标准接口，以便能够与模型/视图架构中的其他组件互操作。它不应该直接实例化。相反，您应该继承它以创建新模型。

QAbstractItemModel 类是模型/视图类之一，是 Qt 模型/视图框架的一部分。它可以用作 QML 中项目视图元素或 Qt Widgets 模块中项目视图类的基础数据模型。

如果您需要一个与项目视图（如QML的List View元素或C++小部件QListView或QTableView）一起使用的模型，您应该考虑子类化QAbstractListModel或QAbstractTableModel，而不是这个类。

底层数据模型以表格层次结构的形式暴露给视图和委托。如果不使用层次结构，那么模型就是一个简单的行和列的表。每个项目都有一个由QModelIndex指定的唯一索引。

../../_images/modelindex-no-parent.png

可以通过模型访问的每个数据项都有一个关联的模型索引。您可以使用index()函数获取此模型索引。每个索引可能有一个sibling()索引；子项有一个parent()索引。

每个项目都有多个与之相关的数据元素，可以通过向模型的data()函数指定一个角色（参见ItemDataRole）来检索它们。可以使用itemData()函数同时获取所有可用角色的数据。

每个角色的数据使用特定的ItemDataRole设置。单个角色的数据可以通过setData()单独设置，或者可以使用setItemData()为所有角色设置数据。

可以使用flags()（参见ItemFlag）查询项目，以查看它们是否可以被选择、拖动或以其他方式操作。

如果一个项目有子对象，hasChildren() 会为相应的索引返回 true。

该模型在层次结构的每个级别都有一个rowCount()和一个columnCount()。可以使用insertRows()、insertColumns()、removeRows()和removeColumns()来插入和删除行和列。

模型发出信号以指示变化。例如，每当模型提供的数据项发生变化时，就会发出dataChanged()。模型提供的标题发生变化时，会发出headerDataChanged()。如果底层数据的结构发生变化，模型可以发出layoutChanged()，以指示任何附加的视图应重新显示任何显示的项，并考虑新的结构。

可以通过模型中的项目使用match()函数搜索特定数据。

要对模型进行排序，你可以使用 sort() 。

子类化

注意

有关子类化模型的一些一般指南可在模型子类化参考中找到。

当子类化 QAbstractItemModel 时，至少必须实现 index()、parent()、rowCount()、columnCount() 和 data()。这些函数在所有只读模型中使用，并构成可编辑模型的基础。

你也可以重新实现 hasChildren() 来为那些 rowCount() 实现代价高昂的模型提供特殊行为。这使得模型能够限制视图请求的数据量，并且可以作为实现模型数据懒加载的一种方式。

要在您的模型中启用编辑功能，您还必须实现 setData()，并重新实现 flags() 以确保返回 ItemIsEditable。您还可以重新实现 headerData() 和 setHeaderData() 来控制模型标题的显示方式。

在重新实现setData()和setHeaderData()函数时，必须分别显式发出dataChanged()和headerDataChanged()信号。

自定义模型需要为其他组件创建模型索引以供使用。为此，请使用适当的行号和列号以及项目的标识符（作为指针或整数值）调用createIndex()。这些值的组合对于每个项目必须是唯一的。自定义模型通常在其他重新实现的函数中使用这些唯一标识符来检索项目数据并访问有关项目父项和子项的信息。有关唯一标识符的更多信息，请参见简单树模型示例。

不需要支持ItemDataRole中定义的每个角色。根据模型中包含的数据类型，可能只需要实现data()函数来返回一些更常见角色的有效信息。大多数模型至少为DisplayRole提供项目数据的文本表示，行为良好的模型还应为ToolTipRole和WhatsThisRole提供有效信息。支持这些角色使模型能够与标准的Qt视图一起使用。然而，对于一些处理高度专业化数据的模型，可能只适合为用户定义的角色提供数据。

提供可调整大小数据结构接口的模型可以实现insertRows()、removeRows()、insertColumns()和removeColumns()。在实现这些函数时，重要的是在模型维度发生变化之前和之后通知所有连接的视图：

private 信号表示这些函数发出的信号，使附加的组件有机会在任何数据变得不可用之前采取行动。使用这些开始和结束函数封装插入和删除操作，也使模型能够正确管理persistent model indexes。如果您希望正确处理选择，必须确保调用这些函数。 如果您插入或删除一个有子项的项，您不需要为子项调用这些函数。换句话说，父项将负责其子项。

要创建逐步填充的模型，你可以重新实现 fetchMore() 和 canFetchMore()。如果重新实现的 fetchMore() 向模型添加了行，则必须调用 beginInsertRows() 和 endInsertRows()。

线程安全

作为QObject的子类，QAbstractItemModel不是线程安全的。任何与QAbstractItemModel模型相关的API只能从模型对象所在的线程中调用。如果QAbstractItemModel与视图连接，这意味着GUI线程，因为视图位于该线程中，并且它将从GUI线程调用模型。使用后台线程填充或修改模型的内容是可能的，但需要小心，因为后台线程不能直接调用任何与模型相关的API。相反，您应该将更新排队并在主线程中应用它们。这可以通过排队连接来完成。

另请参阅

QModelIndex QAbstractItemViewUsing drag and drop with item viewsSimple Tree Model ExampleEditable Tree Model ExampleFetch More Example

class LayoutChangeHint

此枚举描述了模型更改布局的方式。

常量

描述

QAbstractItemModel.NoLayoutChangeHint

没有可用的提示。

QAbstractItemModel.VerticalSortHint

行正在被排序。

QAbstractItemModel.HorizontalSortHint

列正在排序。

请注意，VerticalSortHint 和 HorizontalSortHint 的含义是项目在同一父级内移动，而不是在模型中移动到不同的父级，也不是被过滤掉或过滤进来。

class CheckIndexOption

(继承自 enum.Flag) 此枚举可用于控制由 checkIndex() 执行的检查。

常量

描述

QAbstractItemModel.CheckIndexOption.NoOption

未指定检查选项。

QAbstractItemModel.CheckIndexOption.IndexIsValid

传递给checkIndex()的模型索引被检查为有效的模型索引。

QAbstractItemModel.CheckIndexOption.DoNotUseParent

不执行任何涉及传递给checkIndex()的索引的父级使用的检查。

QAbstractItemModel.CheckIndexOption.ParentIsInvalid

传递给checkIndex()的模型索引的父级被检查为无效的模型索引。如果同时指定了此选项和DoNotUseParent，则忽略此选项。
__init__([parent=None])
Parameters:

父对象 – QObject

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

beginInsertColumns(parent, first, last)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始列插入操作。

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

parent 索引对应于插入新列的父列；first 和 last 是新列插入后将具有的列号。

modelview-begin-insert-columns1 插入列

指定要插入到模型中的项目的列范围的第一个和最后一个列号。

例如，如图所示，我们在第4列之前插入了三列，因此first为4，last为6：

beginInsertColumns(parent, 4, 6)

这将插入三列新列，分别为第4、5和6列。

modelview-begin-append-columns2 添加列

要添加列，请在最后一列之后插入它们。

例如，如图所示，我们在六个现有列（以第5列结尾）的集合中添加了三列，因此 first 是6，last 是8：

beginInsertColumns(parent, 6, 8)

这将两个新列添加为第6、7和8列。

注意

此函数发出columnsAboutToBeInserted()信号，连接的视图（或代理）必须在数据插入之前处理此信号。否则，视图可能会处于无效状态。

另请参阅

endInsertColumns()

beginInsertRows(parent, first, last)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始行插入操作。

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

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

modelview-begin-insert-rows1 插入行

指定要插入到模型项中的行范围的第一行和最后一行编号。

例如，如图所示，我们在第2行之前插入了三行，因此first为2，last为4：

beginInsertRows(parent, 2, 4)

这将插入三行新行，分别为第2、3和4行。

modelview-begin-append-rows2 添加行

要添加行，请在最后一行之后插入它们。

例如，如图所示，我们向4个现有行（以第3行结尾）的集合中添加了两行，因此first为4，last为5：

beginInsertRows(parent, 4, 5)

这将两新行添加为第4行和第5行。

注意

此函数发出rowsAboutToBeInserted()信号，连接的视图（或代理）必须在数据插入之前处理此信号。否则，视图可能会处于无效状态。

另请参阅

endInsertRows()

beginMoveColumns(sourceParent, sourceFirst, sourceLast, destinationParent, destinationColumn)
Parameters:

  • sourceParent – QModelIndex

  • sourceFirst – int

  • sourceLast – int

  • destinationParent – QModelIndex

  • destinationColumn – int

Return type:

布尔

开始列移动操作。

在重新实现子类时，此方法简化了模型中实体的移动。此方法负责移动模型中的持久索引，否则您需要自己完成此操作。使用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()

beginMoveRows(sourceParent, sourceFirst, sourceLast, destinationParent, destinationRow)
Parameters:

  • sourceParent – QModelIndex

  • sourceFirst – int

  • sourceLast – int

  • destinationParent – QModelIndex

  • destinationRow – int

Return type:

布尔

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始行移动操作。

在重新实现子类时，此方法简化了模型中实体的移动。此方法负责移动模型中的持久索引，否则您需要自己完成此操作。使用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，在这种情况下，您应中止移动操作。

modelview-move-rows-11 将行移动到另一个父节点

指定要移动的行在源父节点中的起始和结束行号。同时指定目标父节点中的行号，将行移动到该位置。

例如，如图所示，我们将源中的第2到第4行的三行移动，因此sourceFirst为2，sourceLast为4。我们将这些项目移动到目标中的第2行上方，因此destinationChild为2。

beginMoveRows(sourceParent, 2, 4, destinationParent, 2)

这将源中的第2、3和4行移动到目标中的第2、3和4行。其他受影响的兄弟节点将相应地被移动。

modelview-move-rows-22 将行移动到附加到另一个父级

要将行附加到另一个父级，请将它们移动到最后一行的后面。

例如，如图所示，我们将三行移动到6个现有行的集合中（以第5行结尾），因此destinationChild为6：

beginMoveRows(sourceParent, 2, 4, destinationParent, 6)

这将目标行移动到目标父级的末尾，作为6、7和8。

modelview-move-rows-33 在同一父级中向上移动行

要在同一父级中移动行，请指定要将它们移动到的行。

例如，如图所示，我们将一个项目从第2行移动到第0行，因此 sourceFirst 和 sourceLast 为2，destinationChild 为0。

beginMoveRows(parent, 2, 2, parent, 0)

请注意，其他行可能会相应地移动。还要注意，当在同一父级中移动项目时，不应尝试无效或无操作移动。在上面的示例中，项目2在移动前位于第2行，因此不能将其移动到第2行（它已经在第2行）或第3行（无操作，因为第3行意味着在第3行上方，它已经在第3行上方）

modelview-move-rows-44 在同一父级中向下移动行

要在同一父级内移动行，请指定要将它们移动到的行。

例如，如图所示，我们将一个项目从第2行移动到第4行，因此 sourceFirst 和 sourceLast 为2，destinationChild 为4。

beginMoveRows(parent, 2, 2, parent, 4)

请注意，其他行可能会相应地移动。

另请参阅

endMoveRows()

beginRemoveColumns(parent, first, last)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始列移除操作。

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

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

modelview-begin-remove-columns1 移除列

指定要从模型中某个项目移除的列范围的第一个和最后一个列号。

例如，如图所示，我们从第4列到第6列移除了三列，因此first为4，last为6：

beginRemoveColumns(parent, 4, 6)

注意

此函数发出columnsAboutToBeRemoved()信号，连接的视图（或代理）必须在数据被移除之前处理此信号。否则，视图可能会处于无效状态。

另请参阅

endRemoveColumns()

beginRemoveRows(parent, first, last)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

开始行删除操作。

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

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

modelview-begin-remove-rows1 删除行

指定要从模型中某个项目删除的行范围的第一行和最后一行编号。

例如，如图所示，我们从第2行到第3行删除两行，因此first为2，last为3：

beginRemoveRows(parent, 2, 3)

注意

此函数发出rowsAboutToBeRemoved()信号，连接的视图（或代理）必须在数据被移除之前处理此信号。否则，视图可能会处于无效状态。

另请参阅

endRemoveRows()

beginResetModel()

开始模型重置操作。

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

注意

附加到此模型的任何视图也将被重置。

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

当模型的数据发生根本性变化时，有时直接调用此函数比发出dataChanged()来通知其他组件底层数据源或其结构已更改更为方便。

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

此函数发出信号 modelAboutToBeReset() 。

buddy(index)
Parameters:

索引 – QModelIndex

Return type:

QModelIndex

返回由index表示的项目的伙伴的模型索引。当用户想要编辑一个项目时，视图将调用此函数以检查是否应改为编辑模型中的另一个项目。然后，视图将使用伙伴项目返回的模型索引构造一个委托。

此函数的默认实现将每个项目作为其自己的伙伴。

canDropMimeData(data, action, row, column, parent)
Parameters:
Return type:

布尔

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

如果你想测试data是否可以在row、column、parent处通过action被删除，请在自定义模型中重新实现此函数。如果你不需要这个测试，则无需重新实现此函数。

另请参阅

dropMimeData() 使用 拖放 与 项目 视图

canFetchMore(parent)
Parameters:

父级 – QModelIndex

Return type:

布尔

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

默认实现总是返回false。

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

另请参阅

fetchMore()

changePersistentIndex(from, to)
Parameters:

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

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

changePersistentIndexList(from, to)
Parameters:

  • from – QModelIndex 列表

  • to – QModelIndex 的列表

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

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

checkIndex(index[, options=QAbstractItemModel.CheckIndexOption.NoOption])
Parameters:
Return type:

布尔

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

  • 索引的模型是 this;

  • 索引的行大于或等于零；

  • 索引的行数小于其父索引的行数；

  • 索引列大于或等于零；

  • 索引列小于索引父级的列数。

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

如果 options 包含 DoNotUseParent，那么将省略调用 parent() 的检查；这允许从 parent() 的重新实现中调用此函数（否则，这将导致无限递归和崩溃）。

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

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

注意

此函数是一个调试助手，用于实现您自己的项目模型。在开发复杂模型时，以及在构建复杂的模型层次结构（例如使用代理模型）时，调用此函数以捕获与非法模型索引（如上定义）相关的错误非常有用，这些错误可能会意外传递给某些QAbstractItemModel API。

警告

请注意，向项目模型传递非法索引是未定义的行为，因此应用程序必须避免这样做，并且不能依赖项目模型可能采用的任何“防御性”编程来优雅地处理非法索引。

另请参阅

QModelIndex

clearItemData(index)
Parameters:

索引 – QModelIndex

Return type:

布尔

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

abstract columnCount([parent=QModelIndex()])
Parameters:

父级 – QModelIndex

Return type:

整数

返回给定parent的子元素的列数。

在大多数子类中，列数独立于parent。

例如：

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

注意

在实现基于表的模型时，当父级有效时，columnCount() 应返回 0。

另请参阅

rowCount()

columnsAboutToBeInserted(parent, first, last)
Parameters:

此信号在将列插入模型之前发出。新项目将位于给定的parent项目下，介于first和last之间（包括两者）。

注意

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

另请参阅

insertColumns() beginInsertColumns()

columnsAboutToBeMoved(sourceParent, sourceStart, sourceEnd, destinationParent, destinationColumn)
Parameters:

  • sourceParent – QModelIndex

  • sourceStart – int

  • sourceEnd – int

  • destinationParent – QModelIndex

  • destinationColumn – int

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

注意

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

另请参阅

beginMoveRows()

columnsAboutToBeRemoved(parent, first, last)
Parameters:

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

注意

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

另请参阅

removeColumns() beginRemoveColumns()

columnsInserted(parent, first, last)
Parameters:

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

注意

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

另请参阅

insertColumns() beginInsertColumns()

columnsMoved(sourceParent, sourceStart, sourceEnd, destinationParent, destinationColumn)
Parameters:

  • sourceParent – QModelIndex

  • sourceStart – int

  • sourceEnd – int

  • destinationParent – QModelIndex

  • destinationColumn – int

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

注意

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

另请参阅

beginMoveRows()

columnsRemoved(parent, first, last)
Parameters:

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

注意

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

另请参阅

removeColumns() beginRemoveColumns()

createIndex(row, column, ptr)
Parameters:

  • row – int

  • column – 整数

  • ptr – 对象

Return type:

QModelIndex

为给定的行和列创建一个模型索引，使用内部指针ptr。当使用QSortFilterProxyModel时，其索引有自己的内部指针。不建议在模型外部访问此内部指针。请改用data()函数。

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

警告

由于一些Qt/Python集成规则，ptr参数在QModelIndex生命周期内不会增加引用计数。因此，在整个过程中保持ptr参数使用的对象存活是必要的。如果不确定，请不要销毁该对象。

createIndex(row, column[, id=0])
Parameters:

  • row – int

  • column – 整数

  • id – quintptr

Return type:

QModelIndex

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

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

另请参阅

internalId()

abstract data(index[, role=Qt.DisplayRole])
Parameters:
Return type:

对象

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

注意

如果没有值要返回，请返回一个无效的（默认构造的）QVariant。

另请参阅

ItemDataRole setData() headerData()

dataChanged(topLeft, bottomRight[, roles=list()])
Parameters:

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

如果项目具有相同的父级，则受影响的项目是位于topLeft和bottomRight之间的项目（包括这两个项目）。如果项目没有相同的父级，则行为未定义。

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

可选的roles参数可用于指定哪些数据角色实际上已被修改。roles参数中的空向量意味着应认为所有角色都已修改。roles参数中元素的顺序没有任何相关性。

decodeData(row, column, parent, stream)
Parameters:
Return type:

布尔

dropMimeData(data, action, row, column, parent)
Parameters:
Return type:

布尔

处理由拖放操作提供的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() 使用 拖放 与 项目 视图

encodeData(indexes, stream)
Parameters:

  • indexes – QModelIndex 的列表

  • stream – QDataStream

endInsertColumns()

结束列插入操作。

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

另请参阅

beginInsertColumns()

endInsertRows()

结束行插入操作。

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

另请参阅

beginInsertRows()

endMoveColumns()

结束列移动操作。

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

另请参阅

beginMoveColumns()

endMoveRows()

结束行移动操作。

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

另请参阅

beginMoveRows()

endRemoveColumns()

结束列移除操作。

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

另请参阅

beginRemoveColumns()

endRemoveRows()

结束行删除操作。

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

另请参阅

beginRemoveRows()

endResetModel()

完成模型重置操作。

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

此函数发出信号 modelReset() 。

另请参阅

beginResetModel()

fetchMore(parent)
Parameters:

父级 – QModelIndex

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

如果您正在逐步填充模型，请重新实现此功能。

默认实现不执行任何操作。

另请参阅

canFetchMore()

flags(index)
Parameters:

索引 – QModelIndex

Return type:

ItemFlag的组合

返回给定index的项目标志。

基类实现返回一组标志的组合，这些标志使项目启用（ItemIsEnabled）并允许其被选择（ItemIsSelectable）。

另请参阅

ItemFlags

hasChildren([parent=QModelIndex()])
Parameters:

父级 – QModelIndex

Return type:

布尔

如果 parent 有任何子节点，则返回 true；否则返回 false。

在父级上使用rowCount()来查找子项的数量。

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

另请参阅

parent() index()

hasIndex(row, column[, parent=QModelIndex()])
Parameters:
Return type:

布尔

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

headerData(section, orientation[, role=Qt.DisplayRole])
Parameters:

  • section – int

  • orientation – Orientation

  • role – int

Return type:

对象

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

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

headerDataChanged(orientation, first, last)
Parameters:

  • orientation – Orientation

  • first – int

  • last – int

每当标题发生变化时，都会发出此信号。orientation 表示水平或垂直标题是否已更改。标题中从 first 到 last 的部分需要更新。

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

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

abstract index(row, column[, parent=QModelIndex()])
Parameters:
Return type:

QModelIndex

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

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

另请参阅

createIndex()

insertColumn(column[, parent=QModelIndex()])
Parameters:
Return type:

布尔

在指定的parent的子项中的给定column之前插入一列。

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

insertColumns(column, count[, parent=QModelIndex()])
Parameters:

  • column – 整数

  • count – int

  • parent – QModelIndex

Return type:

布尔

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

如果 column 为 0，则列将前置到任何现有列之前。

如果 column 是 columnCount()，则列将附加到任何现有列。

如果 parent 没有子节点，则插入一行包含 count 列的数据。

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

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

如果您实现自己的模型，并且希望支持插入操作，可以重新实现此函数。或者，您可以提供自己的API来修改数据。

insertRow(row[, parent=QModelIndex()])
Parameters:
Return type:

布尔

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

注意

此函数调用虚拟方法 insertRows 。

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

insertRows(row, count[, parent=QModelIndex()])
Parameters:
Return type:

布尔

注意

此函数的基本类实现不执行任何操作并返回false。

在支持此功能的模型上，在给定的row之前插入count行。新行中的项目将成为由parent模型索引表示的项目的子项。

如果 row 为 0，则这些行将被添加到父级中任何现有行的前面。

如果 row 是 rowCount()，则这些行将附加到父级中的任何现有行。

如果 parent 没有子节点，则会插入一个包含 count 行的单列。

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

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

itemData(index)
Parameters:

索引 – QModelIndex

Return type:

字典的键类型为 .int，值类型为 QVariant。

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

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

layoutAboutToBeChanged([parents=list()[, hint=QAbstractItemModel.NoLayoutChangeHint]])
Parameters:

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

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

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

layoutChanged([parents=list()[, hint=QAbstractItemModel.NoLayoutChangeHint]])
Parameters:

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

当子类化 QAbstractItemModel 或 QAbstractProxyModel 时，确保在更改项目顺序或更改你向视图暴露的数据结构之前发出 layoutAboutToBeChanged()，并在更改布局后发出 layoutChanged()。

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

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

另请参阅

layoutAboutToBeChanged() dataChanged() headerDataChanged() modelReset() changePersistentIndex()

match(start, role, value[, hits=1[, flags=Qt.MatchFlags(Qt.MatchStartsWith|Qt.MatchWrap)]])
Parameters:
Return type:

QModelIndex 的列表

返回列中从start索引开始的项中，存储在给定role下的数据与指定value匹配的索引列表。搜索的方式由给定的flags定义。返回的列表可能为空。还要注意，列表中的结果顺序可能与模型中的顺序不对应，例如如果使用了代理模型。结果的顺序不可依赖。

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

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

注意

此函数的默认实现仅搜索列。重新实现此函数以包含不同的搜索行为。

mimeData(indexes)
Parameters:

索引 – .QModelIndex 列表

Return type:

QMimeData

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

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

mimeTypes()
Return type:

字符串列表

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

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

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

另请参阅

mimeData() dropMimeData()

modelAboutToBeReset()

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

modelReset()

当调用endResetModel()时，此信号被发出，此时模型的内部状态（例如持久模型索引）已被置为无效。

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

moveColumn(sourceParent, sourceColumn, destinationParent, destinationChild)
Parameters:

  • sourceParent – QModelIndex

  • sourceColumn – int

  • destinationParent – QModelIndex

  • destinationChild – int

Return type:

布尔

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

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

另请参阅

moveColumns() moveRow()

moveColumns(sourceParent, sourceColumn, count, destinationParent, destinationChild)
Parameters:

  • sourceParent – QModelIndex

  • sourceColumn – int

  • count – int

  • destinationParent – QModelIndex

  • destinationChild – int

Return type:

布尔

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

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

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

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

moveRow(sourceParent, sourceRow, destinationParent, destinationChild)
Parameters:
Return type:

布尔

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

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

另请参阅

moveRows() moveColumn()

moveRows(sourceParent, sourceRow, count, destinationParent, destinationChild)
Parameters:

  • sourceParent – QModelIndex

  • sourceRow – int

  • count – int

  • destinationParent – QModelIndex

  • destinationChild – int

Return type:

布尔

在支持此功能的模型上，将起始于给定sourceRow的count行移动到父级destinationParent下的行destinationChild，这些行原本位于父级sourceParent下。

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

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

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

multiData(index, roleDataSpan)
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

用请求的数据填充roleDataSpan，数据对应于给定的index。

默认实现将简单地调用data()来获取每个角色的数据。子类可以重新实现此函数，以更高效地向视图提供数据：

def multiData(self, index, roleDataSpan):

    for roleData in roleDataSpan:
        role = roleData.role()
        # ... obtain the data for index and role ...
        roleData.setData(result)

在上面的代码片段中，index 在整个调用过程中是相同的。这意味着为了检索 index 的信息，访问必要的数据结构只需进行一次（将相关代码提升到循环外）。

鼓励使用setData()，或者类似的setValue()，而不是单独构造一个QVariant并使用普通的赋值运算符；这是因为前者允许重用已经为存储在QModelRoleData中的QVariant对象分配的内存，而后者总是分配新的变体然后销毁旧的。

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

最后，为了避免代码重复，子类也可以决定通过提供一个仅包含一个元素的跨度来重新实现data()，基于multiData()：

def data(self, QModelIndex index, int role):

    roleData = QModelRoleData(role)
    multiData(index, roleData)
    return roleData.data()

注意

模型不允许修改span中的角色，或重新排列span元素。这样做会导致未定义的行为。

注意

向此函数传递无效的模型索引是非法的。

另请参阅

QModelRoleDataSpan data()

abstract parent(child)
Parameters:

子节点 – QModelIndex

Return type:

QModelIndex

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

在展示树形数据结构的模型中，一个常见的约定是只有第一列的项目有子项。对于这种情况，当在子类中重新实现此函数时，返回的QModelIndex的列将是0。

在子类中重新实现此函数时，请小心避免调用QModelIndex成员函数，例如parent()，因为属于你的模型的索引将直接调用你的实现，导致无限递归。

另请参阅

createIndex()

persistentIndexList()
Return type:

QModelIndex 的列表

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

removeColumn(column[, parent=QModelIndex()])
Parameters:
Return type:

布尔

从指定的parent的子项中移除给定的column。

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

removeColumns(column, count[, parent=QModelIndex()])
Parameters:

  • column – 整数

  • count – int

  • parent – QModelIndex

Return type:

布尔

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

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

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

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

removeRow(row[, parent=QModelIndex()])
Parameters:
Return type:

布尔

从指定的parent的子项中移除给定的row。

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

这是一个方便的函数，它调用了removeRows()。QAbstractItemModel的removeRows()实现什么也不做。

removeRows(row, count[, parent=QModelIndex()])
Parameters:
Return type:

布尔

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

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

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

如果你实现自己的模型，如果你想支持删除功能，可以重新实现这个函数。或者，你可以提供自己的API来修改数据。

resetInternalData()

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这个槽在模型重置时，其内部数据被清除后立即调用。

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

class CustomDataProxy(QSortFilterProxyModel):

    Q_OBJECT
# public
    CustomDataProxy(QObject parent)
    super().__init__(parent)


    ...
    QVariant data(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
    def resetInternalData():

        m_customData.clear()

# private
QVariant> = QHash<int,()

注意

由于一个错误，这个插槽在Qt 5.0中缺失了。

另请参阅

modelAboutToBeReset() modelReset()

revert()

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

另请参阅

submit()

roleNames()
Return type:

字典的键类型为 .int，值类型为 QByteArray。

返回模型的角色名称。

Qt设置的默认角色名称为：

Qt 角色

QML 角色名称

DisplayRole

显示

DecorationRole

装饰

EditRole

编辑

ToolTipRole

工具提示

StatusTipRole

状态提示

WhatsThisRole

这是什么
abstract rowCount([parent=QModelIndex()])
Parameters:

父级 – QModelIndex

Return type:

整数

返回给定parent下的行数。当父级有效时，意味着rowCount返回的是父级的子级数量。

注意

在实现基于表的模型时，当父级有效时，rowCount() 应返回 0。

另请参阅

columnCount()

rowsAboutToBeInserted(parent, first, last)
Parameters:

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

注意

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

另请参阅

insertRows() beginInsertRows()

rowsAboutToBeMoved(sourceParent, sourceStart, sourceEnd, destinationParent, destinationRow)
Parameters:

  • sourceParent – QModelIndex

  • sourceStart – int

  • sourceEnd – int

  • destinationParent – QModelIndex

  • destinationRow – int

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

注意

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

另请参阅

beginMoveRows()

rowsAboutToBeRemoved(parent, first, last)
Parameters:

此信号在从模型中移除行之前发出。将要移除的项目是在给定parent项目下，介于first和last之间的项目。

注意

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

另请参阅

removeRows() beginRemoveRows()

rowsInserted(parent, first, last)
Parameters:

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

注意

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

另请参阅

insertRows() beginInsertRows()

rowsMoved(sourceParent, sourceStart, sourceEnd, destinationParent, destinationRow)
Parameters:

  • sourceParent – QModelIndex

  • sourceStart – int

  • sourceEnd – int

  • destinationParent – QModelIndex

  • destinationRow – int

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

注意

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

另请参阅

beginMoveRows()

rowsRemoved(parent, first, last)
Parameters:

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

注意

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

另请参阅

removeRows() beginRemoveRows()

setData(index, value[, role=Qt.EditRole])
Parameters:
Return type:

布尔

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

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

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

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

setHeaderData(section, orientation, value[, role=Qt.EditRole])
Parameters:

  • section – int

  • orientation – Orientation

  • value – 对象

  • role – int

Return type:

布尔

为给定的role和section在头部设置指定orientation的数据为提供的value。

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

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

另请参阅

ItemDataRole headerData()

setItemData(index, roles)
Parameters:

  • index – QModelIndex

  • roles – 字典，键类型为 .int，值类型为 QVariant。

Return type:

布尔

为每个ItemDataRole，将index处的项目的角色数据设置为roles中的关联值。

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

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

另请参阅

setData() data() itemData()

sibling(row, column, idx)
Parameters:
Return type:

QModelIndex

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

sibling() 只是一个方便的函数，它找到项目的父级，并使用它来检索指定行和列中的子项目的索引。

此方法可以选择性地被重写以实现特定于实现的优化。

另请参阅

index() row() column()

sort(column[, order=Qt.AscendingOrder])
Parameters:

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

基类实现不执行任何操作。

span(index)
Parameters:

索引 – QModelIndex

Return type:

QSize

返回由index表示的项目的行和列跨度。

注意

目前，span 未被使用。

submit()
Return type:

布尔

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

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

另请参阅

revert()

supportedDragActions()
Return type:

DropAction的组合

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

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

supportedDragActions() 被 QAbstractItemView::startDrag() 用作拖拽发生时的默认值。

另请参阅

DropActions 使用 拖放 与 项目 视图

supportedDropActions()
Return type:

DropAction的组合

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

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

另请参阅

dropMimeData() DropActions 使用 拖放 与 项目 视图