QListView自定义委托绘制完整示例

手把手教你实现 QListView 高度自定义绘制：从模型到委托的完整实践

你有没有遇到过这样的需求？
一个简单的任务列表，不仅要显示标题，还要根据类型用不同颜色标识，左侧加个状态徽章，右侧留出操作箭头，鼠标悬停时有微妙反馈，选中后高亮——而且数据量可能上千条，滚动必须流畅。

这时候，传统的“一堆QLabel套QHBoxLayout”方式就捉襟见肘了：内存爆炸、卡顿、维护困难。
而QListView+ 自定义委托，正是为这类场景量身打造的解决方案。

本文不讲理论套话，带你从零开始搭建一套完整的自定义绘制系统，涵盖模型设计、委托绘制、视觉优化和实战技巧，让你真正掌握QListView的高级玩法。

为什么非要用 QListView？别再堆 Widget 了！

先说清楚一件事：QListView不是一个容器控件，它是个“虚拟化渲染器”。

什么意思？

假设你要展示 10,000 条日志。如果用垂直布局放 10,000 个QWidget，那你的程序早就崩了。但QListView只会为当前屏幕上可见的几十个条目创建绘制对象，其余的“看不见”，就不画。

这就是所谓的虚拟滚动（Virtual Scrolling）—— Qt 模型-视图架构的核心优势。

它把三件事彻底分开：
-数据在哪？→ 模型（Model）
-长啥样？→ 委托（Delegate）
-怎么排布？点哪里？→ 视图（View）

这种解耦让你可以自由替换任意一环，而不影响其他部分。比如同一个任务模型，既能用在列表里，也能塞进下拉框或树形结构中。

✅ 小贴士：如果你还在用QVBoxLayout动态添加控件做列表，请立刻停下来。这不是“灵活”，是给自己挖坑。

先搭骨架：构建支持多角色的数据模型

要让委托知道该怎么画，模型得能提供足够的信息。

我们来写一个典型的任务模型，不只是返回字符串，而是携带类型、时间戳等额外数据：

class TaskModel : public QAbstractListModel { Q_OBJECT public: // 自定义角色，用于传递非显示数据 enum TaskRoles { TitleRole = Qt::DisplayRole, // 主文本（兼容默认行为） TypeRole = Qt::UserRole + 1, // 类型："info" / "warning" / "error" TimestampRole // 时间戳，可用于排序 }; Q_ENUM(TaskRoles) int rowCount(const QModelIndex &parent = {}) const override { return parent.isValid() ? 0 : m_tasks.size(); } QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override { if (!index.isValid() || index.row() >= m_tasks.count()) return {}; const auto &task = m_tasks.at(index.row()); switch (role) { case TitleRole: return task.title; case TypeRole: return task.type; case TimestampRole: return task.timestamp; default: return {}; } } bool setData(const QModelIndex &index, const QVariant &value, int role) override { if (!index.isValid() || role != TitleRole) return false; m_tasks[index.row()].title = value.toString(); emit dataChanged(index, index, {role}); // 只刷新这一项 return true; } QHash<int, QByteArray> roleNames() const override { QHash<int, QByteArray> roles; roles[TitleRole] = "title"; roles[TypeRole] = "type"; roles[TimestampRole] = "timestamp"; return roles; } void addTask(const QString &title, const QString &type) { beginInsertRows({}, m_tasks.size(), m_tasks.size()); m_tasks.append({title, type, QDateTime::currentSecsSinceEpoch()}); endInsertRows(); } private: struct Task { QString title; QString type; qint64 timestamp; }; QList<Task> m_tasks; };

重点来了：

• roleNames()让你在 QML 中可以直接写model.type，非常方便。
• 插入数据时使用beginInsertRows()/endInsertRows()，这是线程安全和索引同步的关键。
• 修改数据后调用dataChanged()，通知视图局部重绘，而不是整个刷新。

这个模型现在不仅能告诉委托“画什么文字”，还能说清“这是警告还是错误”。

核心突破：手写一个全能型自定义委托

接下来才是重头戏 —— 绘制逻辑。

我们继承QStyledItemDelegate，因为它比QItemDelegate更尊重系统样式，适配暗色主题也更轻松。

#include <QStyledItemDelegate> #include <QPainter> #include <QApplication> class CustomItemDelegate : public QStyledItemDelegate { Q_OBJECT public: explicit CustomItemDelegate(QObject *parent = nullptr) : QStyledItemDelegate(parent) {} QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override { return QSize(200, 48); // 固定高度，宽度随容器 } void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override { // 开启抗锯齿，线条更平滑 painter->setRenderHint(QPainter::Antialiasing); // 获取数据 QString title = index.data(Qt::DisplayRole).toString(); QString type = index.data(TypeRole).toString(); // === 背景绘制 === drawBackground(painter, option); // === 左侧彩色标识块 === QRect colorRect(option.rect.left() + 12, option.rect.center().y() - 7, 14, 14); QColor badgeColor = getColorForType(type); painter->setBrush(badgeColor); painter->setPen(Qt::NoPen); painter->drawRoundedRect(colorRect, 3, 3); // === 文字区域 === QRect textRect = option.rect.adjusted(35, 5, -30, -5); // 避开左右元素 painter->setPen(option.palette.text().color()); painter->setFont(getTitleFont(option)); painter->drawText(textRect, Qt::AlignVCenter | Qt::AlignLeft, elidedText(painter->fontMetrics(), textRect.width(), title)); // === 右侧箭头（模拟可点击）=== if (option.features.testFlag(QStyleOptionViewItem::HasDecoration)) { drawArrow(painter, option); } } private: void drawBackground(QPainter *painter, const QStyleOptionViewItem &option) const { if (option.state & QStyle::State_Selected) { painter->fillRect(option.rect, option.palette.highlight()); painter->setPen(option.palette.highlightedText().color()); } else if (option.state & QStyle::State_MouseOver) { // 悬停效果：浅灰色背景 + 圆角边框 painter->setBrush(QColor(240, 240, 240)); painter->setPen(QPen(QColor(200, 200, 200), 1)); painter->drawRoundedRect(option.rect.adjusted(1, 1, -1, -1), 6, 6); } else { painter->fillRect(option.rect, option.palette.base()); painter->setPen(option.palette.text().color()); } } QColor getColorForType(const QString &type) const { if (type == "error") return QColor("#d32f2f"); if (type == "warning") return QColor("#f57c00"); if (type == "info") return QColor("#1976d2"); return QColor("#4caf50"); // default success } QFont getTitleFont(const QStyleOptionViewItem &option) const { QFont font = option.font; font.setPointSize(font.pointSize() + 1); font.setBold(false); return font; } QString elidedText(const QFontMetrics &fm, int maxWidth, const QString &text) const { return fm.elidedText(text, Qt::ElideRight, maxWidth); } void drawArrow(QPainter *painter, const QStyleOptionViewItem &option) const { QPolygon arrow; QPoint centerRight(option.rect.right() - 15, option.rect.center().y()); arrow << QPoint(centerRight.x(), centerRight.y()) << QPoint(centerRight.x() - 5, centerRight.y() - 5) << QPoint(centerRight.x() - 5, centerRight.y() + 5); painter->setPen(QPen(Qt::gray, 1.5)); painter->setBrush(Qt::NoBrush); painter->drawPolyline(arrow); } static constexpr int TypeRole = Qt::UserRole + 1; };

关键细节解析：

🎯 状态感知绘制

if (option.state & QStyle::State_Selected) { ... } else if (option.state & QStyle::State_MouseOver) { ... }

这行代码实现了真正的交互感。选中变蓝，悬停加边框，用户一眼就知道自己在哪。

🎨 颜色策略

没直接用Qt::red这种原始色，而是用了 Material Design 的标准色值（如#d32f2f），这样整体风格更协调，也容易统一 UI 调性。

🔤 文本截断

长标题怎么办？用fontMetrics.elidedText()自动加省略号，避免文字溢出。

⚙️ 性能考虑

字体、颜色等都应在函数内快速计算，不要每次去查配置文件或数据库。如果有复杂资源（比如图标），建议提前缓存成QPixmap。

接入 UI：三行代码完成绑定

模型和委托都写好了，接入QListView就像拼积木一样简单：

// 创建模型 TaskModel *model = new TaskModel(this); // 添加几条测试数据 model->addTask("系统启动成功", "info"); model->addTask("磁盘空间不足", "warning"); model->addTask("网络连接失败", "error"); // 设置到视图 QListView *listView = new QListView(this); listView->setModel(model); listView->setItemDelegate(new CustomItemDelegate(listView)); // 可选：关闭默认焦点虚线框 listView->setFocusPolicy(Qt::StrongFocus); listView->setEditTriggers(QListView::NoEditTriggers);

就这么几行，一个带状态标识、悬停反馈、专业配色的任务列表就出来了。

实战避坑指南：那些文档不会告诉你的事

❌ 别在paint()里做耗时操作

有人喜欢在paint()里加载图片、解析 JSON、甚至发网络请求……
结果就是：一滚动就卡成幻灯片。

✅ 正确做法：
- 图片提前解码并缓存为QPixmap
- 复杂布局尺寸提前算好存入私有类
- 使用QCache或QMap缓存已计算的结果

🖼️ 高分屏适配别忘了 DPI

如果你的应用要在 4K 屏上运行，记得获取设备像素比：

qreal ratio = option.widget ? option.widget->devicePixelRatioF() : qApp->devicePixelRatio(); int size = 16 * ratio;

否则图标会模糊。

🌐 国际化支持 RTL 布局

中东用户从右往左读，你的“右侧箭头”就得变成“左侧箭头”。可以用：

bool isRtl = (option.direction == Qt::RightToLeft); int margin = isRtl ? 10 : -30;

动态调整位置。

🛠️ 调试小技巧：临时画出矩形边界

当你搞不清option.rect到底在哪，可以在paint()最后加上：

#ifdef DEBUG_DELEGATE painter->setPen(QPen(Qt::magenta, 1, Qt::DashLine)); painter->drawRect(option.rect.adjusted(0, 0, -1, -1)); #endif

编译时加DEBUG_DELEGATE宏就能看到每个 item 的真实范围，排查错位问题超有用。

还能怎么玩？扩展思路推荐

掌握了基础之后，你可以轻松实现更多酷炫效果：

甚至可以把这套机制迁移到QTableView或QTreeView上，做出企业级管理后台常见的复杂表格。

写在最后：别小看这一行列表

很多人觉得“不就是个列表嘛”，直到项目做大了才发现：
当初随手堆的十几个QLabel，现在成了性能瓶颈；
临时写的样式代码，根本没法换皮肤；
想加个新功能，牵一发动全身……

而今天这一整套基于模型-视图-委托的方案，从一开始就做到了：

• 数据与界面分离
• 样式集中可控
• 性能经得起考验
• 易于单元测试和复用

这才是专业级 Qt 开发该有的样子。

下次当你又要“新建一个垂直布局”之前，不妨问问自己：
我是不是其实需要一个QListView？

如果你正在做日志系统、消息中心、配置面板或者任何涉及大量条目的界面，欢迎试试这套模式。实际用起来你会发现，它不仅更高效，连代码都变得清爽多了。

💬 互动时间：你在项目中用过哪些惊艳的QListView自定义效果？欢迎在评论区分享你的实战经验！