QTableWidget的函数和信号介绍

前言

Qt版本:6.8.0
该类适用于表格模型/视图

QTableWidgetItem函数介绍

作用

QTableWidget 是 Qt 框架中用于显示和编辑表格数据的一个控件（类），属于 Qt Widgets 模块。它为开发者提供了一个基于单元格的二维表格视图，每个单元格都可以包含文本、图标、复选框、甚至自定义控件（如按钮、下拉框等）。

---

主要作用

1. 显示二维表格数据
   适合展示和编辑类似 Excel 的数据表格，每个单元格都可以独立设置内容和属性。

2. 支持单元格编辑
   用户可以直接在表格中编辑单元格内容，支持文本、数字、复选框等多种数据类型。

3. 支持单元格控件嵌入
   可以在单元格中嵌入自定义控件（如按钮、进度条、下拉框等），实现丰富的交互。

4. 支持行、列、单元格的选择和操作
   支持多选、区域选择、拖拽、排序、插入、删除等操作。

5. 信号与槽机制
   提供丰富的信号（如单元格点击、内容改变、选中变化等），方便与业务逻辑联动。

6. 可自定义表头和行头
   可以设置表头、行头的文本、图标、样式等。

7. 支持数据导入导出
   通过遍历单元格内容，可以方便地实现数据的导入导出。

---

典型应用场景

• 数据管理工具（如数据库表格、Excel 类应用）
• 配置参数编辑器
• 统计报表展示
• 需要二维数据交互的任何桌面应用

---

公共函数

构造与析构

1. QTableWidget(QWidget *parent = nullptr)

• 作用：创建一个空的表格控件。
• 参数：parent 父窗口指针（可选）
• 返回值：构造函数，无返回值
• 示例：

  QTableWidget *table = new QTableWidget();
  

2. QTableWidget(int rows, int columns, QWidget *parent = nullptr)

• 作用：创建指定行列数的表格控件。
• 参数：rows 行数，columns 列数，parent 父窗口指针（可选）
• 返回值：构造函数
• 示例：

  QTableWidget *table = new QTableWidget(3, 4);
  

3. virtual ~QTableWidget()

• 作用：析构函数，释放资源。
• 参数：无
• 返回值：无
• 示例：自动调用，无需手动使用。

---

常用方法

4. QWidget *cellWidget(int row, int column) const

• 作用：获取指定单元格的嵌入控件。
• 参数：row 行，column 列
• 返回值：QWidget*，单元格内的控件指针
• 示例：

  QWidget *w = table->cellWidget(0, 1);
  

5. void closePersistentEditor(QTableWidgetItem *item)

• 作用：关闭某项的持久编辑器（如一直显示的编辑框）。
• 参数：item 目标项
• 返回值：无
• 示例：

  table->closePersistentEditor(item);
  

6. int column(const QTableWidgetItem *item) const

• 作用：获取某项所在的列号。
• 参数：item 目标项
• 返回值：int，列号
• 示例：

  int col = table->column(item);
  

7. int columnCount() const

• 作用：获取表格的总列数。
• 参数：无
• 返回值：int
• 示例：

  int cols = table->columnCount();
  

8. int currentColumn() const

• 作用：获取当前选中的列号。
• 参数：无
• 返回值：int
• 示例：

  int col = table->currentColumn();
  

9. QTableWidgetItem *currentItem() const

• 作用：获取当前选中的项。
• 参数：无
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->currentItem();
  

10. int currentRow() const

• 作用：获取当前选中的行号。
• 参数：无
• 返回值：int
• 示例：

  int row = table->currentRow();
  

11. void editItem(QTableWidgetItem *item)

• 作用：使某项进入编辑状态。
• 参数：item 目标项
• 返回值：无
• 示例：

  table->editItem(item);
  

12. QList findItems(const QString &text, Qt::MatchFlags flags) const

• 作用：查找所有匹配文本的项。
• 参数：text 查找文本，flags 匹配方式（如Qt::MatchExactly, Qt::MatchContains等）
• 返回值：QList
• 示例：

  auto items = table->findItems("Alice", Qt::MatchExactly);
  

13. QTableWidgetItem *horizontalHeaderItem(int column) const

• 作用：获取指定列的表头项。
• 参数：column 列号
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *header = table->horizontalHeaderItem(0);
  

14. QModelIndex indexFromItem(const QTableWidgetItem *item) const

• 作用：获取某项的模型索引。
• 参数：item 目标项
• 返回值：QModelIndex
• 示例：

  QModelIndex idx = table->indexFromItem(item);
  

15. bool isPersistentEditorOpen(QTableWidgetItem *item) const

• 作用：判断某项的持久编辑器是否打开。
• 参数：item 目标项
• 返回值：bool
• 示例：

  bool open = table->isPersistentEditorOpen(item);
  

16. QTableWidgetItem *item(int row, int column) const

• 作用：获取指定单元格的项。
• 参数：row 行，column 列
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->item(1, 2);
  

17. QTableWidgetItem *itemAt(const QPoint &point) const

• 作用：获取指定坐标点的项。
• 参数：point 坐标点
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->itemAt(QPoint(50, 50));
  

18. QTableWidgetItem *itemAt(int ax, int ay) const

• 作用：获取指定像素坐标的项。
• 参数：ax x坐标，ay y坐标
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->itemAt(50, 50);
  

19. QTableWidgetItem *itemFromIndex(const QModelIndex &index) const

• 作用：通过模型索引获取项。
• 参数：index 模型索引
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->itemFromIndex(index);
  

20. const QTableWidgetItem *itemPrototype() const

• 作用：获取当前的项原型（用于批量创建项）。
• 参数：无
• 返回值：const QTableWidgetItem*
• 示例：

  const QTableWidgetItem *proto = table->itemPrototype();
  

21. QList items(const QMimeData *data) const

• 作用：从拖放数据中提取项。
• 参数：data QMimeData*
• 返回值：QList
• 示例：

  // 通常在拖放事件中使用
  

22. void openPersistentEditor(QTableWidgetItem *item)

• 作用：为某项打开持久编辑器（一直显示编辑框）。
• 参数：item 目标项
• 返回值：无
• 示例：

  table->openPersistentEditor(item);
  

23. void removeCellWidget(int row, int column)

• 作用：移除指定单元格的控件。
• 参数：row 行，column 列
• 返回值：无
• 示例：

  table->removeCellWidget(0, 1);
  

24. int row(const QTableWidgetItem *item) const

• 作用：获取某项所在的行号。
• 参数：item 目标项
• 返回值：int
• 示例：

  int row = table->row(item);
  

25. int rowCount() const

• 作用：获取表格的总行数。
• 参数：无
• 返回值：int
• 示例：

  int rows = table->rowCount();
  

26. QList selectedItems() const

• 作用：获取所有被选中的项。
• 参数：无
• 返回值：QList
• 示例：

  auto items = table->selectedItems();
  

27. QList selectedRanges() const

• 作用：获取所有被选中的区域。
• 参数：无
• 返回值：QList
• 示例：

  auto ranges = table->selectedRanges();
  

28. void setCellWidget(int row, int column, QWidget *widget)

• 作用：在指定单元格嵌入一个控件。
• 参数：row 行，column 列，widget 控件
• 返回值：无
• 示例：

  table->setCellWidget(0, 1, new QPushButton("按钮"));
  

29. void setColumnCount(int columns)

• 作用：设置表格的列数。
• 参数：columns 列数
• 返回值：无
• 示例：

  table->setColumnCount(5);
  

30. void setCurrentCell(int row, int column)

• 作用：设置当前选中的单元格。
• 参数：row 行，column 列
• 返回值：无
• 示例：

  table->setCurrentCell(1, 2);
  

31. void setCurrentCell(int row, int column, QItemSelectionModel::SelectionFlags command)

• 作用：设置当前单元格并指定选择行为。
• 参数：row 行，column 列，command 选择标志
• 返回值：无
• 示例：

  table->setCurrentCell(1, 2, QItemSelectionModel::Select);
  

32. void setCurrentItem(QTableWidgetItem *item)

• 作用：设置当前项。
• 参数：item 目标项
• 返回值：无
• 示例：

  table->setCurrentItem(item);
  

33. void setCurrentItem(QTableWidgetItem *item, QItemSelectionModel::SelectionFlags command)

• 作用：设置当前项并指定选择行为。
• 参数：item 目标项，command 选择标志
• 返回值：无
• 示例：

  table->setCurrentItem(item, QItemSelectionModel::Select);
  

34. void setHorizontalHeaderItem(int column, QTableWidgetItem *item)

• 作用：设置指定列的表头项。
• 参数：column 列号，item 表头项
• 返回值：无
• 示例：

  table->setHorizontalHeaderItem(0, new QTableWidgetItem("姓名"));
  

35. void setHorizontalHeaderLabels(const QStringList &labels)

• 作用：批量设置表头标签。
• 参数：labels 标签列表
• 返回值：无
• 示例：

  table->setHorizontalHeaderLabels(QStringList() << "姓名" << "年龄");
  

36. void setItem(int row, int column, QTableWidgetItem *item)

• 作用：设置指定单元格的项。
• 参数：row 行，column 列，item 项
• 返回值：无
• 示例：

  table->setItem(0, 0, new QTableWidgetItem("Alice"));
  

37. void setItemPrototype(const QTableWidgetItem *item)

• 作用：设置项原型（用于批量创建项）。
• 参数：item 原型项
• 返回值：无
• 示例：

  table->setItemPrototype(new QTableWidgetItem("原型"));
  

38. void setRangeSelected(const QTableWidgetSelectionRange &range, bool select)

• 作用：选择或取消选择指定区域。
• 参数：range 区域，select 是否选择
• 返回值：无
• 示例：

  QTableWidgetSelectionRange range(0, 0, 1, 1);
  table->setRangeSelected(range, true);
  

39. void setRowCount(int rows)

• 作用：设置表格的行数。
• 参数：rows 行数
• 返回值：无
• 示例：

  table->setRowCount(10);
  

40. void setVerticalHeaderItem(int row, QTableWidgetItem *item)

• 作用：设置指定行的表头项。
• 参数：row 行号，item 表头项
• 返回值：无
• 示例：

  table->setVerticalHeaderItem(0, new QTableWidgetItem("第一行"));
  

41. void setVerticalHeaderLabels(const QStringList &labels)

• 作用：批量设置行头标签。
• 参数：labels 标签列表
• 返回值：无
• 示例：

  table->setVerticalHeaderLabels(QStringList() << "A" << "B" << "C");
  

42. void sortItems(int column, Qt::SortOrder order = Qt::AscendingOrder)

• 作用：按指定列排序。
• 参数：column 列号，order 排序顺序
• 返回值：无
• 示例：

  table->sortItems(1, Qt::DescendingOrder);
  

43. QTableWidgetItem *takeHorizontalHeaderItem(int column)

• 作用：移除并返回指定列的表头项。
• 参数：column 列号
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *header = table->takeHorizontalHeaderItem(0);
  

44. QTableWidgetItem *takeItem(int row, int column)

• 作用：移除并返回指定单元格的项。
• 参数：row 行，column 列
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *item = table->takeItem(0, 0);
  

45. QTableWidgetItem *takeVerticalHeaderItem(int row)

• 作用：移除并返回指定行的表头项。
• 参数：row 行号
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *header = table->takeVerticalHeaderItem(0);
  

46. QTableWidgetItem *verticalHeaderItem(int row) const

• 作用：获取指定行的表头项。
• 参数：row 行号
• 返回值：QTableWidgetItem*
• 示例：

  QTableWidgetItem *header = table->verticalHeaderItem(0);
  

47. int visualColumn(int logicalColumn) const

• 作用：获取逻辑列号对应的可视列号（列重排时有用）。
• 参数：logicalColumn 逻辑列号
• 返回值：int
• 示例：

  int vcol = table->visualColumn(1);
  

48. QRect visualItemRect(const QTableWidgetItem *item) const

• 作用：获取某项的可视区域矩形。
• 参数：item 目标项
• 返回值：QRect
• 示例：

  QRect rect = table->visualItemRect(item);
  

49. int visualRow(int logicalRow) const

• 作用：获取逻辑行号对应的可视行号。
• 参数：logicalRow 逻辑行号
• 返回值：int
• 示例：

  int vrow = table->visualRow(2);
  

---

公共槽函数

50. void clear()

• 作用：清空所有内容和结构。
• 参数：无
• 返回值：无
• 示例：

  table->clear();
  

51. void clearContents()

• 作用：清空所有单元格内容，保留结构。
• 参数：无
• 返回值：无
• 示例：

  table->clearContents();
  

52. void insertColumn(int column)

• 作用：插入一列。
• 参数：column 插入位置
• 返回值：无
• 示例：

  table->insertColumn(1);
  

53. void insertRow(int row)

• 作用：插入一行。
• 参数：row 插入位置
• 返回值：无
• 示例：

  table->insertRow(2);
  

54. void removeColumn(int column)

• 作用：移除一列。
• 参数：column 列号
• 返回值：无
• 示例：

  table->removeColumn(0);
  

55. void removeRow(int row)

• 作用：移除一行。
• 参数：row 行号
• 返回值：无
• 示例：

  table->removeRow(1);
  

56. void scrollToItem(const QTableWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)

• 作用：滚动视图以显示指定项。
• 参数：item 目标项，hint 滚动方式
• 返回值：无
• 示例：

  table->scrollToItem(item, QAbstractItemView::PositionAtCenter);
  

---

信号

57. void cellActivated(int row, int column)

• 作用：单元格被激活时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellActivated, [](int row, int col){
      qDebug() << "Cell activated:" << row << col;
  });
  

58. void cellChanged(int row, int column)

• 作用：单元格内容改变时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellChanged, [](int row, int col){
      qDebug() << "Cell changed:" << row << col;
  });
  

59. void cellClicked(int row, int column)

• 作用：单元格被点击时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellClicked, [](int row, int col){
      qDebug() << "Cell clicked:" << row << col;
  });
  

60. void cellDoubleClicked(int row, int column)

• 作用：单元格被双击时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellDoubleClicked, [](int row, int col){
      qDebug() << "Cell double clicked:" << row << col;
  });
  

61. void cellEntered(int row, int column)

• 作用：鼠标进入单元格时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellEntered, [](int row, int col){
      qDebug() << "Cell entered:" << row << col;
  });
  

62. void cellPressed(int row, int column)

• 作用：单元格被按下时发出。
• 参数：row 行，column 列
• 示例：

  connect(table, &QTableWidget::cellPressed, [](int row, int col){
      qDebug() << "Cell pressed:" << row << col;
  });
  

63. void currentCellChanged(int currentRow, int currentColumn, int previousRow, int previousColumn)

• 作用：当前单元格变化时发出。
• 参数：currentRow，currentColumn，previousRow，previousColumn
• 示例：

  connect(table, &QTableWidget::currentCellChanged, [](int curRow, int curCol, int preRow, int preCol){
      qDebug() << "Current cell changed:" << curRow << curCol << preRow << preCol;
  });
  

64. void currentItemChanged(QTableWidgetItem *current, QTableWidgetItem *previous)

• 作用：当前项变化时发出。
• 参数：current 当前项，previous 前一项
• 示例：

  connect(table, &QTableWidget::currentItemChanged, [](QTableWidgetItem *cur, QTableWidgetItem *pre){
      qDebug() << "Current item changed:" << cur << pre;
  });
  

65. void itemActivated(QTableWidgetItem *item)

• 作用：项被激活时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemActivated, [](QTableWidgetItem *item){
      qDebug() << "Item activated:" << item->text();
  });
  

66. void itemChanged(QTableWidgetItem *item)

• 作用：项内容改变时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemChanged, [](QTableWidgetItem *item){
      qDebug() << "Item changed:" << item->text();
  });
  

67. void itemClicked(QTableWidgetItem *item)

• 作用：项被点击时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemClicked, [](QTableWidgetItem *item){
      qDebug() << "Item clicked:" << item->text();
  });
  

68. void itemDoubleClicked(QTableWidgetItem *item)

• 作用：项被双击时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemDoubleClicked, [](QTableWidgetItem *item){
      qDebug() << "Item double clicked:" << item->text();
  });
  

69. void itemEntered(QTableWidgetItem *item)

• 作用：鼠标进入项时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemEntered, [](QTableWidgetItem *item){
      qDebug() << "Item entered:" << item->text();
  });
  

70. void itemPressed(QTableWidgetItem *item)

• 作用：项被按下时发出。
• 参数：item 目标项
• 示例：

  connect(table, &QTableWidget::itemPressed, [](QTableWidgetItem *item){
      qDebug() << "Item pressed:" << item->text();
  });
  

71. void itemSelectionChanged()

• 作用：选中项发生变化时发出。
• 参数：无
• 示例：

  connect(table, &QTableWidget::itemSelectionChanged, [](){
      qDebug() << "Selection changed";
  });
  

其他函数

示例

完整示例（C++，适用于 Qt Widgets）

#include 
#include 
#include 
#include 
#include 
#include 

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // 创建 QTableWidget，3行3列
    QTableWidget table(3, 3);
    table.setWindowTitle("QTableWidget 示例");
    table.resize(500, 300);

    // 设置表头
    table.setHorizontalHeaderLabels(QStringList() << "姓名" << "年龄" << "操作");
    table.setVerticalHeaderLabels(QStringList() << "A" << "B" << "C");

    // 添加数据
    table.setItem(0, 0, new QTableWidgetItem("Alice"));
    table.setItem(0, 1, new QTableWidgetItem("23"));
    table.setItem(1, 0, new QTableWidgetItem("Bob"));
    table.setItem(1, 1, new QTableWidgetItem("30"));
    table.setItem(2, 0, new QTableWidgetItem("Carol"));
    table.setItem(2, 1, new QTableWidgetItem("28"));

    // 设置单元格属性
    QTableWidgetItem *item = new QTableWidgetItem("只读项");
    item->setFlags(item->flags() & ~Qt::ItemIsEditable); // 只读
    item->setBackground(Qt::yellow);
    item->setTextAlignment(Qt::AlignCenter);
    table.setItem(0, 2, item);

    // 在单元格中嵌入控件（如按钮）
    QPushButton *btn = new QPushButton("点击我");
    table.setCellWidget(1, 2, btn);

    // 设置复选框
    QTableWidgetItem *checkItem = new QTableWidgetItem("已完成");
    checkItem->setFlags(checkItem->flags() | Qt::ItemIsUserCheckable);
    checkItem->setCheckState(Qt::Unchecked);
    table.setItem(2, 2, checkItem);

    // 响应单元格点击信号
    QObject::connect(&table, &QTableWidget::cellClicked, [&](int row, int col){
        QTableWidgetItem *clickedItem = table.item(row, col);
        QString msg = QString("点击了第%1行第%2列").arg(row).arg(col);
        if (clickedItem)
            msg += "\n内容: " + clickedItem->text();
        QMessageBox::information(&table, "单元格点击", msg);
    });

    // 响应按钮点击
    QObject::connect(btn, &QPushButton::clicked, [&](){
        QMessageBox::information(&table, "按钮", "你点击了表格中的按钮！");
    });

    // 自动调整列宽
    table.horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch);

    table.show();
    return app.exec();
}