QAbstractItemModel Class

Posted 2020-09-03

The QAbstractItemModel class provides the abstract interface for item model classes. 

ps:QAbstractItemModel类为项目模型类提供了抽象接口。

Detailed Description 详细说明

The QAbstractItemModel class defines the standard interface that item models must use to be able to interoperate with other components in the model/view architecture. It is not supposed to be instantiated directly. Instead, you should subclass it to create new models.

ps:QAbstractItemModel类定义了项目模型必须使用的标准接口，以便能够与模型/视图体系结构中的其他组件进行交互操作。 它不应该直接实例化。 相反，您应该将其子类化以创建新模型。

The QAbstractItemModel class is one of the Model/View Classes and is part of Qt‘s model/view framework.

ps:QAbstractItemModel类是一种Model/View类，是Qt的模型/视图框架的一部分。

If you need a model to use with a QListView or a QTableView, you should consider subclassing QAbstractListModel or QAbstractTableModel instead of this class.

ps:如果你需要一个模型来使用QListView或QTableView，你应该考虑子类化QAbstractListModel或QAbstractTableModel而不是这个类(QAbstractItemModel)。

The underlying data model is exposed to views and delegates as a hierarchy of tables. If you do not make use of the hierarchy, then the model is a simple table of rows and columns. Each item has a unique index specified by a QModelIndex.

ps:底层数据模型暴露给视图和委托作为表的层次结构。 如果不使用层次结构，则模型是一个简单的行和列的表。 每个项目都有一个由QModelIndex指定的唯一索引。

Every item of data that can be accessed via a model has an associated model index. You can obtain this model index using the index() function. Each index may have a sibling() index; child items have a parent() index.

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

Each item has a number of data elements associated with it and they can be retrieved by specifying a role (see Qt::ItemDataRole) to the model‘s data() function. Data for all available roles can be obtained at the same time using the itemData() function.

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

Data for each role is set using a particular Qt::ItemDataRole. Data for individual roles are set individually with setData(), or they can be set for all roles with setItemData().

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

Items can be queried with flags() (see Qt::ItemFlag) to see if they can be selected, dragged, or manipulated in other ways.

ps:可以使用flags() 查看项目（请参阅Qt :: ItemFlag），以查看它们是否可以通过其他方式进行选择，拖动或操作。

If an item has child objects, hasChildren() returns true for the corresponding index.

ps:如果项目具有子对象，则hasChildren()对相应的索引返回true。

The model has a rowCount() and a columnCount() for each level of the hierarchy. Rows and columns can be inserted and removed with insertRows(), insertColumns(), removeRows(), andremoveColumns().

ps:模型对于层次结构的每个级别都有一个rowCount()和一个columnCount()。 可以使用insertRows()，insertColumns()，removeRows()和removeColumns()插入和删除行和列。

The model emits signals to indicate changes. For example, dataChanged() is emitted whenever items of data made available by the model are changed. Changes to the headers supplied by the model cause headerDataChanged() to be emitted. If the structure of the underlying data changes, the model can emit layoutChanged() to indicate to any attached views that they should redisplay any items shown, taking the new structure into account.

ps:模型发出信号以指示变化。 例如，只要改变模型可用的数据项，就会发出dataChanged()。 对模型提供的头的更改会导致headerDataChanged()被发出。 如果底层数据的结构发生变化，模型可以发出layoutChanged()来指示任何附加的视图，他们应该重新显示任何显示的项目，考虑新的结构。

The items available through the model can be searched for particular data using the match() function.

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

To sort the model, you can use sort().

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

Subclassing 子类化

Note: Some general guidelines for subclassing models are available in the Model Subclassing Reference.

ps:注意：有关子类化模型的一些一般准则，请参阅“模型子类化参考”。

When subclassing QAbstractItemModel, at the very least you must implement index(), parent(),rowCount(), columnCount(), and data(). These functions are used in all read-only models, and form the basis of editable models.

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

You can also reimplement hasChildren() to provide special behavior for models where the implementation of rowCount() is expensive. This makes it possible for models to restrict the amount of data requested by views, and can be used as a way to implement lazy population of model data.

ps:您还可以重新实现hasChildren()，为rowCount()的实现代价很高的模型提供特殊的行为。 这使得模型可以限制视图所请求的数据量，并且可以用作实现模型数据的惰性填充的方式。

To enable editing in your model, you must also implement setData(), and reimplement flags() to ensure that ItemIsEditable is returned. You can also reimplement headerData() andsetHeaderData() to control the way the headers for your model are presented.

ps:要在模型中启用编辑，还必须实现setData()和重新实现flags()，以确保返回ItemIsEditable。 您还可以重新实现headerData()和setHeaderData()来控制模型头的呈现方式。

The dataChanged() and headerDataChanged() signals must be emitted explicitly when reimplementing the setData() and setHeaderData() functions, respectively.

ps:当分别实现setData()和setHeaderData()函数时，必须显式地发出dataChanged()和头DataChanged()信号。

Custom models need to create model indexes for other components to use. To do this, callcreateIndex() with suitable row and column numbers for the item, and an identifier for it, either as a pointer or as an integer value. The combination of these values must be unique for each item. Custom models typically use these unique identifiers in other reimplemented functions to retrieve item data and access information about the item‘s parents and children. See the Simple Tree Model Example for more information about unique identifiers.

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

It is not necessary to support every role defined in Qt::ItemDataRole. Depending on the type of data contained within a model, it may only be useful to implement the data() function to return valid information for some of the more common roles. Most models provide at least a textual representation of item data for the Qt::DisplayRole, and well-behaved models should also provide valid information for the Qt::ToolTipRole and Qt::WhatsThisRole. Supporting these roles enables models to be used with standard Qt views. However, for some models that handle highly-specialized data, it may be appropriate to provide data only for user-defined roles.

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

Models that provide interfaces to resizable data structures can provide implementations ofinsertRows(), removeRows(), insertColumns(),and removeColumns(). When implementing these functions, it is important to notify any connected views about changes to the model‘s dimensions both before and after they occur:

ps:为可调整大小的数据结构提供接口的模型可以提供insertRows()，removeRows()，insertColumns()和removeColumns()的实现。 当实现这些功能时，重要的是在发生之前和之后通知任何连接的视图关于模型尺寸的改变：

1. An insertRows() implementation must call beginInsertRows() before inserting new rows into the data structure, and endInsertRows() immediately afterwards.ps:insertRows()实现必须在将新行插入数据结构之前调用beginInsertRows()，然后立即调用endInsertRows()。
2. An insertColumns() implementation must call beginInsertColumns() before inserting new columns into the data structure, and endInsertColumns() immediately afterwards.ps:insertColumns()实现必须在将新列插入数据结构之前调用beginInsertColumns()，然后立即调用endInsertColumns()。
3. A removeRows() implementation must call beginRemoveRows() before the rows are removed from the data structure, and endRemoveRows() immediately afterwards.ps:removeRows()实现必须在从数据结构中删除行之前调用beginRemoveRows()，然后立即调用endRemoveRows()。
4. A removeColumns() implementation must call beginRemoveColumns() before the columns are removed from the data structure, and endRemoveColumns() immediately afterwards.ps:removeColumns()实现必须在从数据结构中删除列之前调用beginRemoveColumns()，然后立即调用endRemoveColumns()。

The private signals that these functions emit give attached components the chance to take action before any data becomes unavailable. The encapsulation of the insert and remove operations with these begin and end functions also enables the model to manage persistent model indexes correctly.If you want selections to be handled properly, you must ensure that you call these functions. If you insert or remove an item with children, you do not need to call these functions for the child items. In other words, the parent item will take care of its child items.

ps:这些函数发出的私有信号给附加的组件在任何数据变得不可用之前采取行动的机会。 使用这些开始和结束函数封装插入和删除操作也使得模型能够正确地管理持久性模型索引。 如果要正确处理选择，您必须确保调用这些函数。 如果插入或删除具有子项的项，则不需要为子项调用这些函数。 换句话说，父项将处理它的子项。

To create models that populate incrementally, you can reimplement fetchMore() andcanFetchMore(). If the reimplementation of fetchMore() adds rows to the model, beginInsertRows()and endInsertRows() must be called.

ps:要创建以递增方式填充的模型，您可以重新实现fetchMore()和canFetchMore()。 如果fetchMore()的重新实现向模型添加行，则必须调用beginInsertRows()和endInsertRows()。