克拉玛依市网站建设_网站建设公司_网站开发_seo优化

用像素级控制打造流畅列表：QListView自定义委托实战手记

你有没有遇到过这样的需求？
一个下载管理器需要展示文件名、实时进度条、暂停按钮，甚至预估剩余时间——全都挤在一个列表项里。如果用传统方式，可能得堆一堆QWidget和布局管理器，结果就是内存暴涨、滚动卡顿、代码难以维护。

其实，Qt 早就为我们准备了更优雅的解法：自定义委托（Custom Delegate） +QListView。

这不是炫技，而是一种工程上的必然选择。今天我就带你从零开始，深入剖析如何通过重写QStyledItemDelegate，实现既美观又高效的列表界面，并分享我在实际项目中踩过的坑和优化思路。

为什么是“委托”而不是“控件堆叠”？

先说结论：当你需要展示上百条甚至上千条结构化数据时，别再手动 new 控件了。

我曾经参与开发一款工业监控软件，最初团队为了快速出原型，在主窗口上动态添加了数百个ListWidgetItem，每个 item 都包含多个子控件（标签、进度条、按钮）。结果一接入真实设备数据，UI 直接卡死。

后来我们重构为QListView + 自定义委托方案后，内存占用下降 70%，滚动如丝般顺滑。

关键就在于 Qt 的模型-视图架构（Model-View Architecture）提供了天然的数据与表现分离机制：

• Model负责提供数据；
• View负责布局与交互；
• Delegate负责绘制和编辑。

这意味着：只有当前可见的项才会被绘制，不可见的项不会消耗任何 UI 资源。这正是QListView高性能的核心所在。

📌 小贴士：QListView不保存数据，也不持有控件实例。它只是“画布”，真正决定怎么画、画什么的是它的委托。

自定义委托的本质：接管每一帧的绘制权

要理解自定义委托，就得明白一件事：你在写的不是一个“控件”，而是一段绘图脚本。

当QListView滚动时，系统会不断调用委托的paint()方法，传入三个关键参数：

void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const;

• painter：画笔，你可以用它画文字、矩形、图片……
• option：包含了当前项的位置、状态（是否选中）、字体颜色等样式信息；
• index：指向模型中的某一行数据。

换句话说，你拥有对每一个像素的完全控制权。

我们能做什么？

想象一下这些场景：
- 在列表项里嵌入动态更新的进度条；
- 点击某个区域触发“删除”操作；
- 异步加载缩略图并圆角裁剪；
- 显示多行文本 + 图标 + 状态指示灯；

这些都可以在一个轻量级的paint()函数中完成，无需创建额外控件。

动手实现一个带进度条和按钮的列表项

下面这个例子来自我做过的一个云同步客户端。每一条任务都要显示文件名、传输速度、进度条和一个“暂停”按钮。

我们来一步步构建这个CustomDelegate。

第一步：继承QStyledItemDelegate

class TaskDelegate : public QStyledItemDelegate { Q_OBJECT public: explicit TaskDelegate(QObject *parent = nullptr) : QStyledItemDelegate(parent) {} void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override; QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override; bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override; signals: void pauseButtonClicked(int row); };

注意这里没有使用QItemDelegate，而是推荐使用的QStyledItemDelegate——它能更好地适配平台原生风格（比如 macOS 的圆角、Windows 的高对比度模式）。

第二步：编写paint()函数

我们要画的内容有：
1. 背景（支持选中高亮）
2. 主标题（文件名，加粗）
3. 副标题（传输速度，灰色小字）
4. 进度条边框 + 已完成部分
5. 百分比数字
6. 右侧虚拟“暂停”按钮

void TaskDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const { // 获取数据 QString filename = index.data(Qt::DisplayRole).toString(); QString speed = index.data(Qt::UserRole).toString(); // 如 "1.2 MB/s" int progress = index.data(Qt::UserRole + 1).toInt(); // 0~100 // 【1】绘制背景 painter->save(); if (option.state & QStyle::State_Selected) { painter->setBrush(option.palette.highlight()); painter->setPen(Qt::NoPen); painter->drawRect(option.rect); painter->setPen(option.palette.highlightedText().color()); } else { painter->fillRect(option.rect, option.palette.base()); painter->setPen(option.palette.text().color()); } painter->restore(); // 内边距调整 QRect contentRect = option.rect.adjusted(12, 8, -12, -8); // 【2】绘制主标题 QFont boldFont = painter->font(); boldFont.setBold(true); painter->setFont(boldFont); painter->drawText(contentRect.adjusted(0, 0, 0, -20), Qt::AlignLeft | Qt::AlignTop, filename); // 【3】绘制副标题 QFont smallFont = painter->font(); smallFont.setPointSize(smallFont.pointSize() - 1); painter->setFont(smallFont); painter->setPen(QColor(100, 100, 100)); painter->drawText(contentRect.adjusted(0, 18, 0, 0), Qt::AlignLeft | Qt::AlignTop, speed); // 【4】绘制进度条外框 QRect progressOuter = contentRect.adjusted(0, 40, -60, -30); painter->setPen(Qt::lightGray); painter->setBrush(Qt::NoBrush); painter->drawRect(progressOuter); // 【5】绘制已填充部分 int filledWidth = (progressOuter.width() * progress) / 100; QRect filledRect(progressOuter.topLeft(), QSize(filledWidth, progressOuter.height())); painter->setBrush(QColor("#4CAF50")); painter->setPen(Qt::NoPen); painter->drawRect(filledRect); // 【6】绘制百分比 painter->setPen(option.palette.text().color()); painter->setFont(boldFont); painter->drawText(progressOuter, Qt::AlignCenter, QString("%1%").arg(progress)); // 【7】绘制“暂停”按钮（仅视觉） QRect buttonRect = option.rect.adjusted(option.rect.width() - 50, 25, -10, -25); painter->setBrush(QColor(240, 70, 70)); painter->setPen(Qt::NoPen); painter->drawRoundedRect(buttonRect, 6, 6); painter->setPen(Qt::white); painter->drawText(buttonRect, Qt::AlignCenter, "⏸"); }

看到没？所有内容都在一次paint()调用中完成，没有任何子控件生成。

第三步：处理点击事件

虽然我们画了个“按钮”，但它不是真正的控件。所以我们必须自己判断用户是否点到了那个区域。

这就是editorEvent()的作用：

bool TaskDelegate::editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) { if (event->type() == QEvent::MouseButtonPress) { QMouseEvent *mouse = static_cast<QMouseEvent*>(event); QRect buttonArea = option.rect.adjusted(option.rect.width() - 50, 25, -10, -25); if (buttonArea.contains(mouse->pos())) { emit pauseButtonClicked(index.row()); // 触发信号 return true; // 表示已处理，不再传递事件 } } // 其他事件交给父类处理（如双击进入编辑） return QStyledItemDelegate::editorEvent(event, model, option, index); }

然后在主窗口连接信号即可：

connect(customDelegate, &TaskDelegate::pauseButtonClicked, this, &MainWindow::onPauseTask);

第四步：设置固定高度提升性能

为了让QListView更高效地计算滚动范围，建议返回固定尺寸：

QSize TaskDelegate::sizeHint(const QStyleOptionViewItem &, const QModelIndex &) const { return QSize(300, 80); // 宽度由容器决定，高度固定 }

如果你确实需要变高（比如折叠/展开），记得在数据变更后调用：

listView->doItemsLayout(); // 强制重新计算布局

否则可能出现滚动错位或空白区域。

实战经验：那些文档不会告诉你的坑

🔹 坑点一：频繁构造对象导致卡顿

错误写法：

void paint(...) { QFont f("Arial", 10); // 每次都新建！ QPen p(Qt::red); ... }

正确做法：声明为static或成员变量复用。

static const QFont s_titleFont("Arial", 10, QFont::Bold); static const QPen s_redPen(Qt::red);

🔹 坑点二：异步加载图片后忘记刷新

如果你要在列表项中显示网络图片，通常是这样做的：

void onImageDownloaded(const QPixmap &pix, int row) { m_cache[row] = pix; // 必须手动触发重绘！ listView->update(listModel->index(row, 0)); }

否则即使图片拿到了，界面也不会更新。

🔹 坑点三：HiDPI 缩放失真

高清屏下，直接绘制普通QPixmap会导致模糊。解决方案是设置像素比：

pixmap.setDevicePixelRatio(screen()->devicePixelRatio());

或者使用矢量图（SVG）配合QSvgRenderer。

🔹 坑点四：暗黑模式适配失败

很多开发者硬编码颜色，导致切换主题时 UI 断裂。正确的做法是：

QColor textColor = option.palette.text().color(); // 自动取当前主题色 QColor highlightColor = option.palette.highlight().color();

让 Qt 自己去读系统主题配置。

更进一步：可编辑委托怎么做？

上面的例子只能“看”不能“改”。如果你想让用户点击某一项时弹出滑块或开关，就需要重写createEditor()。

举个例子：做一个带开关的设置项列表。

QWidget* createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override { QCheckBox *box = new QCheckBox(parent); box->setStyleSheet("margin-left:50%;"); // 居中 return box; } void setEditorData(QWidget *editor, const QModelIndex &index) const override { QCheckBox *box = static_cast<QCheckBox*>(editor); bool value = index.model()->data(index, Qt::EditRole).toBool(); box->setChecked(value); } void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override { QCheckBox *box = static_cast<QCheckBox*>(editor); model->setData(index, box->isChecked(), Qt::EditRole); }

这样就能实现内联编辑，就像 Excel 单元格一样。

性能调优 checklist

结语：掌控细节，才能做出好产品

回到开头的问题：为什么要学自定义委托？

因为它让你从“被动使用控件”进化到“主动设计交互”。你可以：
- 把复杂的 UI 压缩进一个高效渲染的列表；
- 实现原生控件无法提供的交互逻辑；
- 在低资源环境下依然保持流畅体验。

这不是花拳绣腿，而是现代 Qt 开发者必须掌握的核心技能之一。

下次当你面对“这个功能好像要用很多控件”的时候，不妨停下来想想：
能不能用一个paint()来解决？

也许你会发现，答案比你想象的更简单。

如果你在实现过程中遇到了其他挑战，欢迎在评论区分享讨论。