24. [Python GUI] PyQt5中的模型与视图框架-表格部件QTableWidget

PyQt5的表格部件QTableWidget

QTableWidget 类继承自 QTableView，该类是一个由 Qt 实现的标准的表格部件，该类的数据项由 QTableWidgetItem 类管理。

当前单元格(或当前项目)与当前索引或当前选择是相同的，即可以同时选择多个单元格，但只能有一个当前单元格，当编辑单元格时，只会编辑当前单元格。当前单元格通常具有焦点边框。

单元格和项目的区别(重要概念)：
项目是指 QTableWidgetItem 类的对象，因此空单元格是不含有项目的。当在空单元格上单击鼠标时，会发送 cellClicked()信号，但不会发送 itemClicked()信号。 因此当前单元格和当前项目也是有区别的。

一、QTableWidget 类中的属性和函数

1.1 属性和构造函数

• columnCount： int
  访问函数： int columnCount() const; void setColumnCount(int);

• rowCount： int
  访问函数： int rowCount() const; void setRowCount(int);
  以上属性描述表格的行数和列数

• QTableWidget(QWidget *parent = Q_NULLPTR) //构造函数
  QTableWidget(int rows, int columns, QWidget *parent = Q_NULLPTR)

1.2 设置、移除、获取项目基本信息

• void setItem(int row, int column, QTableWidgetItem *item)
  把(row, column)处的项目设置为 item，该表格取得 item 的所有权。注意：若启用了排序(按列)，则会将行移至由排序确定的位置。

• QTableWidgetItem * takeItem(int row, int column);
  从表中移除而不删除(row, column)处的项目。

• QTableWidgetItem *item(int row, int column) const
  返回(row, column)处的项目，否则返回 0。

• QTableWidgetItem *itemAt(const QPoint &point) const;
  返回位置 point 处的项目。使用内容坐标。

• QTableWidgetItem *itemAt(int ax, int ay) const
  返回位置(ax, ay)处的项目。使用内容坐标。

• QRect visualItemRect(const QTableWidgetItem *item) const
  返回项目 item 在视口上所占用的矩形(即位置和大小)。

• int column(const QTableWidgetItem *item) const
  返回项目 item 所在的列

• int row(const QTableWidgetItem *item) const
  返回项目 item 所在的行。

• QList items(const QMimeData *data) const;
  返回包含在 data 中的项目列表。

1.3 当前项目

• void setCurrentCell(int row, int column)

• void setCurrentCell(int row, int column, QItemSelectionModel::SelectionFlags * command)

• void setCurrentItem(QTableWidgetItem *item)

• void setCurrentItem(QTableWidgetItem *item, QItemSelectionModel::SelectionFlags command)
  以上函数用于设置当前单元格或当前项目，除非选择模式为 NoSelection，否则当前项目会同时被选中。

• QTableWidgetItem *currentItem() const
  返回当前项目

• int currentColumn() const
  返回当前项目所在的列。

• int currentRow() const
  返回当前项目所在的行。

1.4 选择项目

• QList selectedItems() const
  返回所有被选择项目的列表(不含空单元格)。函数 QTableView::selectedIndexes()包含空单元格。

• QList selectedRanges() const
  返回所有被选择项目的范围列表(含空单元格)。

• void setRangeSelected(const QTableWidgetSelectionRange &range, bool select)
  选择或取消选择范围 range 指定的项目。 QTableWidgetSelectionRange 类类似于QItemSelection 用于指示选择的范围。使用方法如下：
  QTableWidgetSelectionRange r(1,1,4,4); //从左上角(1,1)到右下角(4,4)的范围
  setRangeSelected(r, true); //选择 r 指定的范围

1.5 排序、查找、编辑、 模型索引

• void sortItems(int column, Qt::SortOrder order = Qt::AscendingOrder)
  使表格按照列 column 进行排序，排序规则(升序或降序)由 order 指定)。

• void editItem(QTableWidgetItem *item)
  开始编辑项目 item

• QList findItems(const QString &text, Qt::MatchFlags flags) const
  使用文本 text 查找项目

• QModelIndex indexFromItem(QTableWidgetItem *item) const;
  返回与 item 关联的模型索引。

• QTableWidgetItem *itemFromIndex(const QModelIndex &index) const;
  返回与 index 关联的项目

1.6 表头

• int visualColumn(int logicalColumn) const
  返回逻辑列 logicalColumn 处的可视列(与 QHeaderView 类中的逻辑索引原理相同)。

• int visualRow(int logicalRow) const;
  返回逻辑行 logicalColumn 处的可视行。

• QTableWidgetItem *horizontalHeaderItem(int column) const
  void setHorizontalHeaderItem(int column, QTableWidgetItem *item)
  void setHorizontalHeaderLabels(const QStringList &labels)
  QTableWidgetItem *verticalHeaderItem(int row) const
  以上函数用于设置标头，其原理与 QStandardItemView 类中的相应函数相同。

1.7 持久编辑器、 部件、项目原型

• QWidget *cellWidget(int row, int column) const
  返回单元格(row, column)处的部件

• void setCellWidget(int row,int column,QWidget *widget);
  把部件设置到位置(row, column)处

• void removeCellWidget(int row, int column)
  删除单元格(row,column)处的部件。

• void closePersistentEditor(QTableWidgetItem*item)
  关闭持久编辑器(见 QAbstractItemView)

• void openPersistentEditor(QTableWidgetItem *item)
  打开持久编辑器

• bool isPersistentEditorOpen(QTableWidgetItem *item) const
  持久编辑器是否打开。 qt5.10

• const QTableWidgetItem *itemPrototype() const
  返回该表格的项目原型

• void setItemPrototype(const QTableWidgetItem *item)
  设置 item 为该表格的项目原型。该表格取得项目原型的所有权。

1.8 槽

• void clear() //删除视图中的所有项目(包含标头)
• void clearContents() //删除视图中的数据项(不含标头)
• void insertColumn(int column) //在 column 处插入一个空列
• void insertRow(int row) //在 row 处插入一个空行
• void removeColumn(int column) //移除列 column 及在其上的项目
• void removeRow(int row) ///移除行 row 及在其上的项目
• void scrollToItem(const QTableWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)
  滚动视图以使项目 item 可见。 QAbstractItemView::ScrollHint 枚举见相关类

1.9 信号

• void cellActivated(int row, int column) 激活单元格时发送。
  void itemActivated(QTableWidgetItem *item) //项目被激活时发送。
  windows 下激活是指在单元格上按下回车键， 具体取决于系统。

• void cellClicked(int row, int column) //单击单元格时发送
  void itemClicked(QTableWidgetItem *item) //单击表格中的项目就发送此信号

• void cellPressed(int row, int column) //单击单元格时发送
  void itemPressed(QTableWidgetItem *item) //当按下表格中的项目时，发送此信号

• void cellDoubleClicked(int row, int column) //双击单元格时发送
  void itemDoubleClicked(QTableWidgetItem *item) //双击表格中的项目就发送此信号

• void cellEntered(int row, int column) //鼠标进入(需开启鼠标跟踪)单元格时发送
  void itemEntered(QTableWidgetItem *item) //当鼠标光标进入项目时(需开启鼠标跟踪)发送

• void cellChanged(int row, int column) //单元格中的数据发生更改时发送。
  void itemChanged(QTableWidgetItem *item) //当项目的数据项变化时，发送此信号。

• void currentCellChanged(int currentRow, int currentColumn, int previousRow, int previousColumn)
  当当前单元格发生变化时，发送此信号。

• void currentItemChanged(QTableWidgetItem *current, QTableWidgetItem *previous)
  当当前项目发生变化时，发送此信号。

• void itemSelectionChanged() //当选择改变时，发送此信号

1.10 其他函数（主要用于处理拖放，与 QAbstractItemModel 类中的相应函数类似）

• virtual bool dropMimeData(int row, int column, const QMimeData *data, Qt::DropAction action)
• virtual QMimeData * mimeData(const QList items) const
• virtual QStringList mimeTypes() const
• virtual Qt::DropActions supportedDropActions() const

二、QTableWidgetItem类

QTableWidgetItem 是一个独立的类， 该类用于向 QTableWidget 类提供数据项。

以下函数主要用于设置项目数据，在前面章节已见过，下面以表格的形式列出：

其他的一些函数如下：

• QTableWidget * tableWidget() const //返回该项目的表格部件
• int column() const//返回表格中项目所在的列，若项目不在表格中，则返回-1。
• int row() const //返回表格中项目所在的行，若项目不在表格中，则返回-1。
• virtual QVariant data(int role) const
  virtual void setData(int role, const QVariant &value)
  把角色 role 的数据设置为 value，该函数可用于添加整型、浮点型等类型的数据。
• virtual void read(QDataStream &in); //从流中读取项目
• virtual void write(QDataStream &out) const; //把项目写入流中
• virtual QTableWidgetItem *clone() const; //创建该项目的副本。
• int type() const
  返回该数据项的类型，返回的类型主要用于区分是否是自定义类型，返回的值应是枚举
  ItemType 的成员所对应的整数值，见下表：
  

三、QTableWidget部件的示例代码

示例代码如下:

from PyQt5.QtWidgets import QApplication, QTableWidget, QTableWidgetItem
from PyQt5.QtCore import Qt
from PyQt5.QtGui import QIcon
import sys

if __name__ == "__main__":
    app = QApplication(sys.argv)
    app.setStyle('Fusion')
    
    my_table_widget = QTableWidget(3, 3)    # 构造一个3*3的table
    
    # 创建一些item
    item1 = QTableWidgetItem('AAA')
    
    # 整数值需要使用setData函数添加
    item2 = QTableWidgetItem()
    item2.setData(Qt.ItemDataRole.DisplayRole, 222)
    
    item3 = QTableWidgetItem()
    item3.setIcon(QIcon('C:\\Users\\hubing\\Pictures\\QQ图片20200112144947.jpg'))
    item3.setText('BBB')
    
    item4 = QTableWidgetItem('CCC')
    item5 = QTableWidgetItem('DDD')

    # 将数据项添加到表格里
    my_table_widget.setItem(0, 0, item1)
    my_table_widget.setItem(0, 1, item2)
    my_table_widget.setItem(1, 0, item3)
    my_table_widget.setItem(2, 1, item4)
    my_table_widget.setItem(2, 2, item5)
    
    my_table_widget.show()
    
    sys.exit(app.exec_())

运行效果如图: