Qt 代理（Delegate）学习笔记
一、代理的基本概念
代理（Delegate）是Qt模型/视图架构的核心组件，用于控制数据的显示和编辑方式。它允许你自定义特定单元格的编辑器和渲染器。
二、代理的类型与使用场景
1. 自定义显示（QItemDelegate）
cpp
// 继承 QItemDelegate，重写 paint() 方法
class CustomDisplayDelegate : public QItemDelegate {
void paint(QPainter *painter, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
// 自定义绘制逻辑
}
};2. 自定义编辑器（QItemDelegate 或 QStyledItemDelegate）
cpp
// 继承 QItemDelegate，实现完整的编辑器生命周期
class CustomEditorDelegate : public QItemDelegate {
QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,
const QModelIndex &index) const override;
void setEditorData(QWidget *editor, const QModelIndex &index) const override;
void setModelData(QWidget *editor, QAbstractItemModel *model,
const QModelIndex &index) const override;
};三、使用代理的完整步骤
步骤1：创建代理类
cpp
// 示例1：复选框代理（不创建实际编辑器）
class CheckBoxDelegate : public QItemDelegate {
public:
CheckBoxDelegate(QObject *parent = nullptr) : QItemDelegate(parent) {}
// 关键：不创建编辑器，直接通过绘制实现
QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
return nullptr; // 不创建编辑器
}
// 绘制复选框
void paint(QPainter *painter, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
bool value = index.model()->data(index, Qt::DisplayRole).toBool();
// 配置复选框样式
QStyleOptionButton checkBoxOption;
checkBoxOption.state = value ? QStyle::State_On : QStyle::State_Off;
checkBoxOption.state |= QStyle::State_Enabled;
// 计算居中位置
checkBoxOption.rect = option.rect;
int checkboxWidth = 16;
int x = option.rect.center().x() - checkboxWidth / 2;
checkBoxOption.rect.setX(x);
checkBoxOption.rect.setWidth(checkboxWidth);
// 绘制复选框
QApplication::style()->drawControl(QStyle::CE_CheckBox,
&checkBoxOption, painter);
}
// 处理点击事件
bool editorEvent(QEvent *event, QAbstractItemModel *model,
const QStyleOptionViewItem &option,
const QModelIndex &index) override {
if (event->type() == QEvent::MouseButtonRelease) {
// 切换复选框状态
bool currentValue = model->data(index, Qt::DisplayRole).toBool();
model->setData(index, !currentValue, Qt::DisplayRole);
return true;
}
return QItemDelegate::editorEvent(event, model, option, index);
}
};
cpp
// 示例2：组合框代理（使用QComboBox作为编辑器）
class SpeedDelegate : public QItemDelegate {
public:
explicit SpeedDelegate(QObject *parent = nullptr) : QItemDelegate(parent) {}
// 创建编辑器
QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
QComboBox *editor = new QComboBox(parent);
editor->addItems(QStringList() << "1倍速" << "2倍速" << "5倍速");
return editor;
}
// 将模型数据设置到编辑器
void setEditorData(QWidget *editor, const QModelIndex &index) const override {
int value = index.model()->data(index, Qt::DisplayRole).toInt();
QComboBox *combo = static_cast<QComboBox*>(editor);
if (value == 1) combo->setCurrentIndex(0);
else if (value == 2) combo->setCurrentIndex(1);
else if (value == 5) combo->setCurrentIndex(2);
}
// 将编辑器数据保存到模型
void setModelData(QWidget *editor, QAbstractItemModel *model,
const QModelIndex &index) const override {
QComboBox *combo = static_cast<QComboBox*>(editor);
int speed = 1;
if (combo->currentIndex() == 1) speed = 2;
else if (combo->currentIndex() == 2) speed = 5;
model->setData(index, speed, Qt::DisplayRole);
}
// 更新编辑器位置
void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
editor->setGeometry(option.rect);
}
};步骤2：初始化代理
cpp
void MyWidget::initUI() {
// 创建代理实例
m_checkBoxDelegate = new CheckBoxDelegate(this);
m_speedDelegate = new SpeedDelegate(this);
// 为特定列设置代理
m_tableWidget->setItemDelegateForColumn(1, m_checkBoxDelegate); // 复选框列
m_tableWidget->setItemDelegateForColumn(9, m_speedDelegate); // 组合框列
// 必须启用编辑触发器
m_tableWidget->setEditTriggers(QAbstractItemView::AllEditTriggers);
}步骤3：清理代理（防止内存泄漏）
cpp
MyWidget::~MyWidget() {
delete m_checkBoxDelegate;
delete m_speedDelegate;
}四、代理的关键方法详解
1. createEditor()
- 作用：创建用于编辑数据的控件
- 返回值：QWidget* 类型的编辑器
- 常见编辑器：QLineEdit、QComboBox、QSpinBox、自定义控件
- 注意 ：返回
nullptr表示不创建编辑器（如只读显示）
2. setEditorData()
- 作用：将模型中的数据加载到编辑器
- 参数 ：
editor: 编辑器控件index: 模型索引，包含要编辑的数据
3. setModelData()
- 作用：将编辑器中的数据保存回模型
- 参数 ：
editor: 编辑器控件model: 数据模型index: 模型索引，指定保存位置
4. updateEditorGeometry()
- 作用：调整编辑器在视图中的位置和大小
- 通常实现 ：
editor->setGeometry(option.rect);
5. paint()
- 作用：自定义单元格的绘制方式
- 应用场景 ：
- 绘制特殊图形（复选框、进度条、星星评分）
- 条件格式化（不同数据用不同颜色/样式显示）
- 数据转换显示（数字转文字、日期格式化）
6. editorEvent()
- 作用：处理编辑事件（鼠标点击、键盘输入等）
- 返回值：bool，表示事件是否被处理
- 常见用途 ：
- 点击复选框直接切换状态
- 双击单元格触发特定操作
- 右键菜单
五、最佳实践与注意事项
1. 选择正确的基类
- QItemDelegate：适用于Qt4风格的代理，需要更多自定义
- QStyledItemDelegate：Qt5推荐，更好的样式集成
2. 代理的生命周期管理
cpp
// 正确：代理作为成员变量，在析构时清理
class MyWidget {
private:
QItemDelegate *m_delegate;
};
// 错误：局部变量可能提前被销毁
void MyWidget::initUI() {
QItemDelegate *delegate = new MyDelegate(this);
// 如果delegate不是成员变量，可能无法正确清理
}3. 数据类型的处理
cpp
// 在setEditorData和setModelData中正确处理数据类型
void MyDelegate::setEditorData(QWidget *editor,
const QModelIndex &index) const {
// 获取正确的数据类型
QVariant value = index.model()->data(index, Qt::EditRole);
int intValue = value.toInt();
QString stringValue = value.toString();
// ... 根据实际情况处理
}4. 代理复用
cpp
// 同一个代理可以用于多个列
m_tableWidget->setItemDelegateForColumn(1, m_checkBoxDelegate);
m_tableWidget->setItemDelegateForColumn(8, m_checkBoxDelegate); // 复用5. 编辑器关闭处理
cpp
// 确保编辑器关闭时提交或取消编辑
void MyDelegate::commitAndCloseEditor() {
QWidget *editor = qobject_cast<QWidget*>(sender());
emit commitData(editor);
emit closeEditor(editor);
}六、常见问题与解决方案
问题1：代理不响应点击
原因 ：没有正确实现 editorEvent() 或 createEditor() 返回 nullptr
解决：
cpp
// 检查editorEvent实现
bool editorEvent(QEvent *event, ...) override {
if (event->type() == QEvent::MouseButtonRelease) {
// 处理点击逻辑
return true; // 重要：返回true表示已处理
}
return false;
}问题2：编辑器位置不正确
原因 ：没有实现 updateEditorGeometry()
解决：
cpp
void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option,
const QModelIndex &index) const override {
editor->setGeometry(option.rect);
}问题3：编辑器数据不保存
原因 ：setModelData() 没有被调用
解决：
- 确保编辑器发出
editingFinished()信号 - 或者重写
closeEditor()逻辑
七、示例：完整的使用流程
cpp
// 1. 定义代理类
class MyDelegate : public QItemDelegate {
// ... 实现必要的方法
};
// 2. 在视图中设置代理
void setupTable() {
MyDelegate *delegate = new MyDelegate(this);
tableView->setItemDelegateForColumn(0, delegate);
tableView->setEditTriggers(QAbstractItemView::AllEditTriggers);
}
// 3. 处理数据变化
connect(model, &QAbstractItemModel::dataChanged,
this, &MyWidget::onDataChanged);总结
- 控制数据显示：自定义单元格的绘制方式
- 控制数据编辑：为不同数据类型提供合适的编辑器
- 提高用户体验：提供直观、友好的编辑界面
- 保持数据一致性：确保用户输入的数据格式正确