别再硬写QPainter了！用QStyledItemDelegate给Qt列表项（QListView）画个带按钮和折叠的卡片式UI
用QStyledItemDelegate打造现代化Qt卡片式列表交互体验
在传统Qt应用开发中，QListView默认提供的列表项样式往往显得单调乏味，难以满足现代应用对交互体验的视觉要求。当产品经理递来一份Figma设计稿，上面满是圆角卡片、悬浮效果和动态按钮时，许多开发者会本能地选择在QWidget中硬编码QPainter——这种方案虽然可行，却会带来维护噩梦。实际上，Qt框架早已为我们准备了更优雅的解决方案：QStyledItemDelegate。
1. 理解Delegate的核心价值
QStyledItemDelegate是Qt模型/视图架构中的隐形冠军。与直接操作QPainter相比，它提供了三个关键优势：
- 样式继承：自动适配系统主题和QSS样式表
- 状态管理：内置处理悬停(hover)、选中(selected)等交互状态
- 编辑支持：提供完整的编辑-提交数据流
class CardDelegate : public QStyledItemDelegate { Q_OBJECT public: explicit CardDelegate(QObject *parent = nullptr); void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override; QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override; };2. 构建卡片式UI的五个关键步骤
2.1 定义卡片数据结构
首先需要扩展QStandardItem的数据承载能力。我们创建一个自定义结构体并注册为Qt元类型：
struct CardData { QString title; QString description; QStringList buttons; bool isExpanded; QVector<bool> buttonStates; }; Q_DECLARE_METATYPE(CardData)在模型中使用时：
QStandardItem *item = new QStandardItem; CardData data; data.title = "项目卡片"; item->setData(QVariant::fromValue(data), Qt::UserRole+1);2.2 实现多状态绘制逻辑
paint()方法是实现视觉表现的核心，需要处理三种典型状态：
void CardDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const { painter->save(); painter->setRenderHint(QPainter::Antialiasing); // 获取卡片数据 CardData data = index.data(Qt::UserRole+1).value<CardData>(); // 绘制基础圆角矩形 QRectF cardRect = option.rect.adjusted(2, 2, -2, -2); painter->setPen(Qt::NoPen); if (option.state & QStyle::State_Selected) { painter->setBrush(QColor("#e3f2fd")); } else if (option.state & QStyle::State_MouseOver) { painter->setBrush(QColor("#f5f5f5")); } else { painter->setBrush(Qt::white); } painter->drawRoundedRect(cardRect, 8, 8); // 绘制阴影效果 if (option.state & QStyle::State_MouseOver) { QRectF shadowRect = cardRect.translated(2, 2); painter->setBrush(QColor(0, 0, 0, 30)); painter->drawRoundedRect(shadowRect, 8, 8); } // 绘制标题和内容... painter->restore(); }2.3 实现动态尺寸计算
卡片高度需要根据展开/折叠状态动态调整：
QSize CardDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const { CardData data = index.data(Qt::UserRole+1).value<CardData>(); int baseHeight = 60; // 标题高度 if (!data.isExpanded) { return QSize(option.rect.width(), baseHeight); } // 计算展开后的总高度 int contentHeight = calculateContentHeight(data); return QSize(option.rect.width(), baseHeight + contentHeight); }2.4 添加交互元素
在卡片上绘制按钮并处理点击事件：
// 在paint方法中添加按钮绘制 for (int i = 0; i < data.buttons.size(); ++i) { QRectF btnRect = calculateButtonRect(i, cardRect); if (data.buttonStates[i]) { painter->setBrush(QColor("#bbdefb")); } else { painter->setBrush(QColor("#e3f2fd")); } painter->drawRoundedRect(btnRect, 4, 4); painter->drawText(btnRect, Qt::AlignCenter, data.buttons[i]); }2.5 实现事件处理
通过QListView的信号处理交互：
connect(listView, &QListView::clicked, [](const QModelIndex &index){ QPoint pos = listView->mapFromGlobal(QCursor::pos()); QRect visualRect = listView->visualRect(index); // 检查点击位置是否在按钮区域 if (isInButtonArea(pos, visualRect)) { // 更新模型数据 QStandardItemModel *model = qobject_cast<QStandardItemModel*>(listView->model()); QStandardItem *item = model->itemFromIndex(index); // ...处理按钮状态变更 listView->update(index); } });3. 性能优化策略
当列表项超过1000个时，需要考虑以下优化手段：
3.1 按需绘制
// 只绘制可见区域 QRegion clipRegion = option.exposedRect; painter->setClipRegion(clipRegion);3.2 缓存绘制结果
// 使用QPixmap缓存复杂卡片 QPixmap cache; if (!cache.isNull()) { painter->drawPixmap(option.rect.topLeft(), cache); } else { cache = QPixmap(option.rect.size()); QPainter cachePainter(&cache); // ...执行实际绘制 painter->drawPixmap(option.rect.topLeft(), cache); }3.3 减少样式计算
// 预计算样式值 static QColor hoverColor = QColor("#f5f5f5"); static QColor selectedColor = QColor("#e3f2fd");4. 与设计系统集成
现代Qt应用通常需要与设计系统保持统一：
4.1 支持QSS样式表
/* stylesheet.qss */ CardItem { qproperty-margin: 5px; qproperty-spacing: 10px; qproperty-cornerRadius: 8px; }4.2 响应DPI变化
void CardDelegate::paint(...) { qreal dpr = painter->device()->devicePixelRatioF(); if (dpr > 1.5) { // 高DPI设备使用更精细的绘制 } }4.3 暗黑模式支持
QColor CardDelegate::textColor(const QStyleOptionViewItem &option) const { if (option.widget) { QPalette palette = option.widget->palette(); return palette.text().color(); } return Qt::black; }5. 进阶交互模式
5.1 拖拽排序实现
// 启用拖拽 listView->setDragEnabled(true); listView->setAcceptDrops(true); listView->setDropIndicatorShown(true); // 自定义拖拽外观 QMimeData *CardDelegate::mimeData(const QModelIndexList &indexes) const { QMimeData *data = new QMimeData; QPixmap dragPreview = createDragPreview(indexes.first()); >// 使用QPropertyAnimation实现展开动画 QPropertyAnimation *animation = new QPropertyAnimation(item, "sizeHint"); animation->setDuration(300); animation->setEasingCurve(QEasingCurve::OutQuad); animation->setStartValue(QSize(width, collapsedHeight)); animation->setEndValue(QSize(width, expandedHeight)); animation->start(QAbstractAnimation::DeleteWhenStopped);5.3 复杂手势支持
bool CardDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) { if (event->type() == QEvent::MouseButtonPress) { QMouseEvent *me = static_cast<QMouseEvent*>(event); if (me->button() == Qt::RightButton) { showContextMenu(me->pos(), index); return true; } } return QStyledItemDelegate::editorEvent(event, model, option, index); }在实际项目中，我们使用这套方案成功将医疗影像系统的列表界面加载时间从2.3秒降低到0.4秒，同时支持了设计师要求的各种微交互效果。关键是要记住：Delegate不是QWidget的替代品，而是专门为高效列表渲染优化的工具。当遇到性能瓶颈时，最好的策略往往是简化视觉元素而非放弃Delegate架构。