Qt QAbstractItemModel类详解

一.概述

QAbstractItemModel 类定义了项目模型必须使用的标准接口，以便能够与模型/视图Model/View框架中的其他组件进行互操作。 正确用法是将其子类化以创建新模型。此类用作 QML 中的项目视图元素或 Qt Widgets 模块中的项目视图类的底层数据模型。如果需要一个模型与项目视图一起使用，例如 QML 的列表视图元素或 C++控件QListView 或 QTableView，则应该考虑子类化QAbstractListModel 或 QAbstractTableModel 而不是此类。底层数据模型作为表的层次结构向视图和委托公开。 如果不使用层次结构，那么模型就是一个简单的行和列表。每个项目都有一个由 QModelIndex 指定的唯一索引。

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

二.QAbstractItemModel类

1.类型

类型	原型	说明
enum class	CheckIndexOption { NoOption, IndexIsValid, DoNotUseParent, ParentIsInvalid }	此枚举可用于控制由 checkIndex() （此函数检查 index 是否是该模型的合法模型索引）执行的检查。
flags	CheckIndexOptions
enum	LayoutChangeHint { NoLayoutChangeHint, VerticalSortHint, HorizontalSortHint }	此枚举描述模型更改布局的方式

2.信号

返回值	信号	说明
void	columnsAboutToBeInserted(const QModelIndex &parent, int first, int last)	该信号在列插入模型之前发出。新项目将位于给定parent下的first和last之间。
void	columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)	该信号在列在模型内移动之前发出。将被移动的项目是在给定的 sourceParent 项目下的 sourceStart 和 sourceEnd 之间的项目。 它们将被移动到destinationParent，从destinationColumn 列开始。
void	columnsAboutToBeRemoved(const QModelIndex &parent, int first, int last)	该信号在列从模型中移除之前发出。要删除的项目是在给定 parent 下的 first 和 last 之间的项目。
void	columnsInserted(const QModelIndex &parent, int first, int last)	在将列插入模型之后发出此信号。新项目是在给定parent下的first和last之间的项目。
void	columnsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int column)	在模型内移动列之后发出此信号。给parent下的 start 和 end 之间的项目已移至 column 列开始的destination。
void	columnsRemoved(const QModelIndex &parent, int first, int last)	从模型中删除列后会发出此信号。 删除的项目是在给parent下的first和last之间的项目。
void	dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList &roles = QList())	只要现有项目中的数据发生变化，就会发出此信号。
void	headerDataChanged(Qt::Orientation orientation, int first, int last)	每当更改标题时都会发出此信号。
void	layoutAboutToBeChanged(const QList &parents = QList(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)	该信号在模型布局更改之前发出。
void	layoutChanged(const QList &parents = QList(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)	每当模型公开的项目布局发生变化时，就会发出此信号（例如，当模型已经排序）。
void	modelAboutToBeReset()	在调用 beginResetModel() 时，在模型的内部状态（例如，持久模型索引）失效之前，会发出此信号。
void	modelReset()	在模型的内部状态（例如，持久模型索引）失效后，调用 endResetModel() 时会发出此信号。
void	rowsAboutToBeInserted(const QModelIndex &parent, int start, int end)	该信号在行插入模型之前发出。新项目在给定的parent下将被定位在start和end之间。
void	rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)	该信号在行在模型内移动之前发出。将被移动的项目是在给定的 sourceParent 项目下的 sourceStart 和 sourceEnd 之间的项目。 它们将被移动到destinationParent 行，从destinationRow 开始。
void	rowsAboutToBeRemoved(const QModelIndex &parent, int first, int last)	该信号在行从模型中移除之前发出。 将被删除的项目是在给定parent下的first和last之间的项目。
void	rowsInserted(const QModelIndex &parent, int first, int last)	在将行插入模型后发出此信号。新项目是在给定parent下的first和last之间的项目。
void	rowsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int row)	在模型内移动行后发出此信号。 给定parent下的 start 和 end 之间的项已移动到从row行开始的destination。
void	rowsRemoved(const QModelIndex &parent, int first, int last)	从模型中删除行后会发出此信号。删除的项目是在给定parent下的first和last之间的项目。

3.函数

返回值	函数	说明
	QAbstractItemModel(QObject *parent = nullptr)
virtual	~QAbstractItemModel()
virtual QModelIndex	buddy(const QModelIndex &index) const	返回由index表示的项目的好友模型索引。
virtual bool	canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const	如果模型可以接受拖拽数据，则返回 true。
virtual bool	canFetchMore(const QModelIndex &parent) const	如果父级有更多可用数据，则返回 true。默认实现始终返回 false。
bool	checkIndex(const QModelIndex &index, QAbstractItemModel::CheckIndexOptions options = CheckIndexOption::NoOption) const	此函数检查 index 是否是该模型的合法模型索引。
virtual bool	clearItemData(const QModelIndex &index)	删除存储在给定索引的所有角色中的数据。成功则返回true。如果成功删除数据，则应发出 dataChanged() 信号。
virtual int	columnCount(const QModelIndex &parent = QModelIndex()) const = 0	返回给定父级的子级的列数。
virtual QVariant	data(const QModelIndex &index, int role = Qt::DisplayRole) const = 0	返回存储在给定角色下的数据，用于索引引用的项目。
virtual bool	dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)	处理拖放拖入的数据。
virtual void	fetchMore(const QModelIndex &parent)	获取具有由父索引指定的父项的项的任何可用数据。如果以增量方式填充模型，需要重新实现它。
virtual Qt::ItemFlags	flags(const QModelIndex &index) const	返回给定索引的项目标志。
virtual bool	hasChildren(const QModelIndex &parent = QModelIndex()) const	parent 是否有子项。
bool	hasIndex(int row, int column, const QModelIndex &parent = QModelIndex()) const	如果模型为具有父级的行和列返回有效的 QModelIndex，则返回 true。
virtual QVariant	headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const	返回具有指定方向的标题中给定角色和部分的数据。对于水平标题，节号对应于列号。 同样，对于垂直标题，节号对应于行号。
virtual QModelIndex	index(int row, int column, const QModelIndex &parent = QModelIndex()) const = 0	返回由给定的行、列和父索引指定的模型中项目的索引。
bool	insertColumn(int column, const QModelIndex &parent = QModelIndex())	在指定的父项的子项中的给定列之前插入单列。如果成功插入了列则返回 true。
virtual bool	insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())	上面函数的重载函数
bool	insertRow(int row, const QModelIndex &parent = QModelIndex())	在指定的父项的子项中的给定行之前插入单行。如果成功插入了列则返回 true。
virtual bool	insertRows(int row, int count, const QModelIndex &parent = QModelIndex())	上面函数的重载函数
virtual QMap<int, QVariant>	itemData(const QModelIndex &index) const	返回一个map，其中包含index处的项目的模型中所有预定义角色的值。
virtual QModelIndexList	match(const QModelIndex &start, int role, const QVariant &value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags(Qt::MatchStartsWith	Qt::MatchWrap)) const
virtual QMimeData *	mimeData(const QModelIndexList &indexes) const	返回一个对象，其中包含与指定索引列表相对应的序列化数据项。用于描述编码数据的格式是从 mimeTypes() 函数获得的。
virtual QStringList	mimeTypes() const	返回允许的 MIME 类型列表。
bool	moveColumn(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)	在支持此功能的模型上，将 sourceColumn 从 sourceParent 移动到 destinationParent 下的 destinationChild。
virtual bool	moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild)	在支持此功能的模型上，将从父 sourceParent 下的给定 sourceColumn 开始的列移动到父 destinationParent 下的列 destinationChild。
bool	moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)	在支持此功能的模型上，将从父 sourceParent 下的给定 sourceColumn 开始的行移动到父 destinationParent 下的行 destinationChild。
virtual bool	moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)	在支持此功能的模型上，将从父 sourceParent 下的给定 sourceColumn 开始的行移动到父 destinationParent 下的行 destinationChild。
virtual void	multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const	使用给定索引的请求数据填充 roleDataSpan。
virtual QModelIndex	parent(const QModelIndex &index) const = 0	返回具有给定索引的模型项的父项。
bool	removeColumn(int column, const QModelIndex &parent = QModelIndex())	从指定的父项的子项中删除给定列。如果列被删除返回 true。
virtual bool	removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())	在支持此功能的模型上，从模型中删除 parent 下的给定 column 开头的 count列。如果列被成功删除则返回 true。
bool	removeRow(int row, const QModelIndex &parent = QModelIndex())	从指定的父项的子项中删除给定行。如果行被删除返回 true。
virtual bool	removeRows(int row, int count, const QModelIndex &parent = QModelIndex())	在支持此功能的模型上，从模型中删除 parent 下的给定 row 开头的 count列。如果行被成功删除则返回 true。
virtual QHash<int, QByteArray>	roleNames() const	返回模型的角色名称。
virtual int	rowCount(const QModelIndex &parent = QModelIndex()) const = 0	返回给定父项下的行数。
virtual bool	setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)	设置索引处项目的角色数据。成功则返回true。如果成功设置了数据，则应发出 dataChanged() 信号。
virtual bool	setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)	设置标题的值。如果标题的数据已更新则返回 true。
virtual bool	setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)	对于每个 Qt::ItemDataRole，将 index 处项目的角色数据设置为角色中的关联值。不在角色中的角色将不会被修改。
virtual QModelIndex	sibling(int row, int column, const QModelIndex &index) const	返回索引处项目的行和列的兄弟，如果该位置没有兄弟，则返回无效的 QModelIndex。
virtual void	sort(int column, Qt::SortOrder order = Qt::AscendingOrder)	按给定顺序按列对模型进行排序。
virtual QSize	span(const QModelIndex &index) const	返回由索引表示的项目的行和列跨度。
virtual Qt::DropActions	supportedDragActions() const	返回此模型中数据支持的操作。
virtual Qt::DropActions	supportedDropActions() const	返回此模型支持的放置操作。

返回值	函数	说明
void	beginInsertColumns(const QModelIndex &parent, int first, int last)	开始列插入操作。
void	beginInsertRows(const QModelIndex &parent, int first, int last)	开始行插入操作。
bool	beginMoveColumns(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)	开始列移动操作。
bool	beginMoveRows(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)	开始行移动操作。
void	beginRemoveColumns(const QModelIndex &parent, int first, int last)	开始列移除操作。
void	beginRemoveRows(const QModelIndex &parent, int first, int last)	开始行移除操作。
void	beginResetModel()	开始模型重置操作。
void	changePersistentIndex(const QModelIndex &from, const QModelIndex &to)
void	changePersistentIndexList(const QModelIndexList &from, const QModelIndexList &to)
QModelIndex	createIndex(int row, int column, const void *ptr = nullptr) const	使用内部指针 ptr 为给定的行和列创建模型索引。
QModelIndex	createIndex(int row, int column, quintptr id) const	上面函数的重载函数
void	endInsertColumns()	结束列插入操作。
void	endInsertRows()	结束行插入操作。
void	endMoveColumns()	结束列移动操作。
void	endMoveRows()	结束行移动操作。
void	endRemoveColumns()	结束列移除操作。
void	endRemoveRows()	结束行删除操作。
void	endResetModel()	完成模型重置操作。
QModelIndexList	persistentIndexList() const	返回在模型中存储为持久索引的索引列表。