当前位置：首页 > news >正文

qt c++ QTableWidget

news 2025/8/28 8:01:38

# 📋 QTableWidget 完整接口详解

QTableWidget 是 Qt 中用于显示和编辑表格数据的强大控件。以下是其所有接口的详细讲解：

## 1. 构造函数和基本设置

### 构造函数
```cpp
// 创建空表格
QTableWidget(QWidget *parent = nullptr);

// 创建指定行列数的表格
QTableWidget(int rows, int columns, QWidget *parent = nullptr);
```

### 基本设置方法
```cpp
// 设置行列数
void setRowCount(int rows);
void setColumnCount(int columns);
int rowCount() const;
int columnCount() const;

// 设置表格维度
void setDimensions(int rows, int columns);
```

## 2. 行列管理接口

### 行列操作
```cpp
// 插入行列
void insertRow(int row);
void insertColumn(int column);

// 删除行列
void removeRow(int row);
void removeColumn(int column);

// 获取行列索引
int row(const QTableWidgetItem *item) const;
int column(const QTableWidgetItem *item) const;
```

### 行列属性设置
```cpp
// 显示/隐藏行列
void setRowHidden(int row, bool hide);
void setColumnHidden(int column, bool hide);
bool isRowHidden(int row) const;
bool isColumnHidden(int column) const;

// 设置行列高度/宽度
void setRowHeight(int row, int height);
int rowHeight(int row) const;
void setColumnWidth(int column, int width);
int columnWidth(int column) const;

// 调整行列尺寸以适应内容
void resizeRowToContents(int row);
void resizeColumnToContents(int column);
void resizeRowsToContents();
void resizeColumnsToContents();
```

## 3. 单元格内容管理

### 单元格操作
```cpp
// 获取/设置单元格项目
QTableWidgetItem *item(int row, int column) const;
void setItem(int row, int column, QTableWidgetItem *item);

// 获取/设置当前单元格
QTableWidgetItem *currentItem() const;
void setCurrentItem(QTableWidgetItem *item);
void setCurrentCell(int row, int column);

// 获取当前单元格位置
int currentRow() const;
int currentColumn() const;

// 清除内容
void clear();
void clearContents();
```

### 特殊单元格操作
```cpp
// 获取指定位置的单元格项目
QTableWidgetItem *itemAt(int x, int y) const;
QTableWidgetItem *itemAt(const QPoint &point) const;

// 获取单元格的视觉矩形
QRect visualItemRect(const QTableWidgetItem *item) const;

// 获取指定坐标处的行列
int rowAt(int y) const;
int columnAt(int x) const;
```

## 4. 选择和编辑控制

### 选择模式设置
```cpp
// 设置选择行为
void setSelectionBehavior(QAbstractItemView::SelectionBehavior behavior);
QAbstractItemView::SelectionBehavior selectionBehavior() const;

// 设置选择模式
void setSelectionMode(QAbstractItemView::SelectionMode mode);
QAbstractItemView::SelectionMode selectionMode() const;
```

### 编辑控制
```cpp
// 设置编辑触发器
void setEditTriggers(QAbstractItemView::EditTriggers triggers);
QAbstractItemView::EditTriggers editTriggers() const;

// 打开单元格编辑器
void editItem(QTableWidgetItem *item);
void openPersistentEditor(QTableWidgetItem *item);
void closePersistentEditor(QTableWidgetItem *item);
```

## 5. 表头管理

### 水平表头操作
```cpp
// 获取水平表头
QHeaderView *horizontalHeader() const;

// 设置水平表头标签
void setHorizontalHeaderLabels(const QStringList &labels);
void setHorizontalHeaderItem(int column, QTableWidgetItem *item);

// 获取水平表头项目
QTableWidgetItem *horizontalHeaderItem(int column) const;
```

### 垂直表头操作
```cpp
// 获取垂直表头
QHeaderView *verticalHeader() const;

// 设置垂直表头标签
void setVerticalHeaderLabels(const QStringList &labels);
void setVerticalHeaderItem(int row, QTableWidgetItem *item);

// 获取垂直表头项目
QTableWidgetItem *verticalHeaderItem(int row) const;
```

## 6. 排序和搜索

### 排序功能
```cpp
// 启用/禁用排序
void setSortingEnabled(bool enable);
bool isSortingEnabled() const;

// 按列排序
void sortByColumn(int column, Qt::SortOrder order = Qt::AscendingOrder);

// 排序项目
virtual void sortItems(int column, Qt::SortOrder order = Qt::AscendingOrder);
```

### 搜索功能
```cpp
// 查找项目
QList<QTableWidgetItem*> findItems(const QString &text,
Qt::MatchFlags flags) const;

// 滚动到指定项目
void scrollToItem(const QTableWidgetItem *item,
QAbstractItemView::ScrollHint hint = EnsureVisible);
```

## 7. 视觉和外观控制

### 网格和边框
```cpp
// 显示/隐藏网格
void setShowGrid(bool show);
bool showGrid() const;

// 设置网格样式
void setGridStyle(Qt::PenStyle style);
Qt::PenStyle gridStyle() const;
```

### 交替行颜色
```cpp
// 设置交替行颜色
void setAlternatingRowColors(bool enable);
bool alternatingRowColors() const;
```

### 视觉选项
```cpp
// 设置文字换行
void setWordWrap(bool on);
bool wordWrap() const;

// 设置自动换行
void setTextElideMode(Qt::TextElideMode mode);
Qt::TextElideMode textElideMode() const;
```

## 8. 单元格控件管理

### 控件操作
```cpp
// 设置单元格控件
void setCellWidget(int row, int column, QWidget *widget);
QWidget *cellWidget(int row, int column) const;

// 移除单元格控件
void removeCellWidget(int row, int column);
```

### 索引转换
```cpp
// 从项目获取索引
QModelIndex indexFromItem(const QTableWidgetItem *item) const;
QTableWidgetItem *itemFromIndex(const QModelIndex &index) const;
```

## 9. 选择和范围操作

### 选择范围管理
```cpp
// 选择范围
void setRangeSelected(const QTableWidgetSelectionRange &range, bool select);
QList<QTableWidgetSelectionRange> selectedRanges() const;

// 选择项目
void setItemSelected(const QTableWidgetItem *item, bool select);
bool isItemSelected(const QTableWidgetItem *item) const;

// 选择单元格
void setCurrentCell(int row, int column);
void setCurrentCell(int row, int column, QItemSelectionModel::SelectionFlags command);
```

### 选中项获取
```cpp
// 获取选中的项目
QList<QTableWidgetItem*> selectedItems() const;

// 获取选中的行列
QList<int> selectedRows() const;
QList<int> selectedColumns() const;
```

## 10. 拖放操作

### 拖放设置
```cpp
// 设置拖放模式
void setDragDropMode(QAbstractItemView::DragDropMode behavior);
QAbstractItemView::DragDropMode dragDropMode() const;

// 设置拖放覆盖模式
void setDragDropOverwriteMode(bool overwrite);
bool dragDropOverwriteMode() const;

// 设置默认拖放动作
void setDefaultDropAction(Qt::DropAction dropAction);
Qt::DropAction defaultDropAction() const;
```

## 11. 信号接口

### 交互信号
```cpp
// 单元格点击信号
void cellClicked(int row, int column);
void cellDoubleClicked(int row, int column);
void cellPressed(int row, int column);
void cellActivated(int row, int column);

// 单元格改变信号
void cellChanged(int row, int column);
void currentCellChanged(int currentRow, int currentColumn,
int previousRow, int previousColumn);

// 项目改变信号
void itemChanged(QTableWidgetItem *item);
void itemSelectionChanged();
void itemEntered(QTableWidgetItem *item);
```

### 编辑信号
```cpp
// 编辑相关信号
void itemActivated(QTableWidgetItem *item);
void itemPressed(QTableWidgetItem *item);
void itemClicked(QTableWidgetItem *item);
void itemDoubleClicked(QTableWidgetItem *item);
```

## 12. 高级功能接口

### 持久化编辑器
```cpp
// 持久化编辑器管理
bool isPersistentEditorOpen(QTableWidgetItem *item) const;
```

### 数据角色操作
```cpp
// 设置项目数据
virtual void setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles);
virtual QMap<int, QVariant> itemData(const QModelIndex &index) const;
```

### 视觉提示
```cpp
// 设置悬停提示
void setToolTip(const QString &text);
void setStatusTip(const QString &text);
void setWhatsThis(const QString &text);
```

## 13. 性能优化接口

### 批量操作
```cpp
// 批量更新控制
void setUpdatesEnabled(bool enable);
bool updatesEnabled() const;

// 排序控制
void setSortingEnabled(bool enable);
```

### 视图更新
```cpp
// 视图更新控制
void update(const QModelIndex &index);
void updateGeometries();
void doItemsLayout();
```

## 14. 实用工具方法

### 坐标转换
```cpp
// 坐标转换方法
QPoint visualPos(const QPoint &pos) const;
QRect visualRect(const QModelIndex &index) const;
```

### 索引操作
```cpp
// 索引操作
QModelIndex moveCursor(QAbstractItemView::CursorAction cursorAction,
Qt::KeyboardModifiers modifiers);
```

## 15. 完整示例代码

```cpp
#include <QApplication>
#include <QTableWidget>
#include <QTableWidgetItem>
#include <QHeaderView>
#include <QPushButton>
#include <QVBoxLayout>
#include <QWidget>
#include <QDebug>

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

// 创建主窗口
QWidget window;
window.setWindowTitle("QTableWidget 完整示例");
window.resize(800, 600);

QVBoxLayout *layout = new QVBoxLayout(&window);

// 创建表格
QTableWidget *table = new QTableWidget(5, 4);

// 设置表头
QStringList headers;
headers << "ID" << "姓名" << "年龄" << "部门";
table->setHorizontalHeaderLabels(headers);

// 填充数据
for (int row = 0; row < table->rowCount(); ++row) {
for (int col = 0; col < table->columnCount(); ++col) {
QTableWidgetItem *item = new QTableWidgetItem();

switch (col) {
case 0:
item->setText(QString::number(row + 1));
item->setTextAlignment(Qt::AlignCenter);
break;
case 1:
item->setText(QString("用户%1").arg(row + 1));
break;
case 2:
item->setText(QString::number(20 + row));
item->setTextAlignment(Qt::AlignRight | Qt::AlignVCenter);
break;
case 3:
item->setText(row % 2 == 0 ? "技术部" : "市场部");
break;
}

table->setItem(row, col, item);
}
}

// 设置表格属性
table->setAlternatingRowColors(true);
table->setSortingEnabled(true);
table->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch);
table->setSelectionBehavior(QAbstractItemView::SelectRows);

// 连接信号
QObject::connect(table, &QTableWidget::cellClicked, [](int row, int col) {
qDebug() << "点击了单元格:" << row << "," << col;
});

QObject::connect(table, &QTableWidget::cellChanged, [](int row, int col) {
qDebug() << "单元格内容改变:" << row << "," << col;
});

layout->addWidget(table);
window.show();

return app.exec();
}
```

## 16. 重要注意事项

1. **性能考虑**：对于大数据集，考虑使用 QTableView + QAbstractTableModel
2. **内存管理**：QTableWidgetItem 需要手动管理内存
3. **信号处理**：注意 cellChanged 和 itemChanged 信号的区别
4. **线程安全**：UI 操作必须在主线程中进行

这个完整的接口列表涵盖了 QTableWidget 的所有功能，从基本的单元格操作到高级的拖放和排序功能。

查看全文

http://www.dtcms.com/a/353515.html