简介面向Qt开发者的QTableView功能扩展示例包聚焦委托、分页与搜索三项常见表格需求。通过继承QItemDelegate自定义单元格样式与交互可绘制按钮、复选框、下拉框、编辑框、进度条等控件并针对不同业务场景包装相应委托类分页功能由独立组件实现支持页码切换与视图同步搜索功能则依托代理模型执行实时过滤。资源共17个文件含11个头文件、5个源文件与1个工程配置文件压缩包仅18KB结构紧凑。工程内部划分主视图、数据模型、分页模块与委托控件头文件负责接口声明源文件实现具体逻辑pri文件便于Qt工程直接引用。已有420人学习使用内容覆盖委托事件处理、分页切换、过滤规则、模型刷新等关键环节适合初中级Qt开发者快速理解并复用到实际表格场景也可作为课程设计或业务模块的起步代码。 把 QTableView 的委托、翻页、搜索三个功能放进同一个项目里做是我在开发一个设备台账管理工具时被逼出来的。用户的诉求其实很朴素双击状态列不要弹出光秃秃的输入框而是给一个下拉选择一页别滚出几千行只想看 20 条输入关键字能在几秒内定位到设备而不是靠肉眼在表里扫。这三个需求拆开看都是 Qt 文档里的常规操作真正麻烦的是它们同时叠在一张表上之后索引关系瞬间变得复杂。这篇文章把我在整个过程中的设计取舍、核心代码和踩坑记录完整写出来给正在做桌面端数据管理界面的同行一个参考。1. 为什么一个设备管理小工具会被这三个功能逼到重写刚开始我图省事表格控件直接用了 QTableWidget。小规模数据、简单展示的场景下QTableWidget 确实快双击编辑、表头排序全都现成。但需求一旦走到“状态列只能从下拉框选”“进度列要显示进度条”“要接搜索过滤”这一步QTableWidget 就不够用了。原因很简单QTableWidget 把所有东西都封装死了你能拿到的是一个完整的 item但如果要干预“格子怎么画”“编辑器用什么组件”你通常得绕到它内部去非常别扭。QTableView 这套体系就不一样。它的核心思路是把数据、视图、编辑彻底分层QAbstractItemModel 管数据长什么样QTableView 管布局和展示QStyledItemDelegate 管每个单元格的画法和编辑器。这个分层在初期看起来代码量比 QTableWidget 多但到了定制阶段每一层都能单独替换完全不会互相牵扯。我梳理了一下实际需求最终落到这四件事上设备状态列双击时弹出下拉框只能选“正常/维护中/停用”禁止自由输入生命周期进度列直接画一个进度条样式不需要进入编辑状态表格默认每页显示 20 行顶部提供上一页、下一页、页码和每页条数搜索框输入关键字后按“设备名称、类型、所属责任人”三列做不区分大小写的匹配。这四个需求对应到 Qt 的组件上正好是 QStyledItemDelegate、分页模型、QSortFilterProxyModel 三块内容。把它们放一起之后我才意识到真正的难点不在某一个功能而是它们组合在一起时的协作。后面每一章会按这个顺序拆开讲。2. 委托怎么写才能既改了样式又不影响编辑链路委托delegate是刚开始最容易理解偏的地方。很多人把它当成“改单元格样式的工具”其实 QStyledItemDelegate 管的远不止样式。它管的是“绘制 编辑”一整条链路正常状态下单元格怎么画双击后用什么编辑器编辑器打开时怎么把当前值塞进去编辑器关闭时怎么把新值写回模型这几个环节全部由 delegate 接管。我当时一口气写了两个 delegate。一个是状态列的下拉编辑器另一个是进度条列的自定义绘制。两个都基于 QStyledItemDelegate 派生而不是老旧的 QItemDelegate原因在于 QStyledItemDelegate 会优先服从全局 QSS 样式表和项目的主题风格保持一致QItemDelegate 则不会。状态列下拉委托的核心代码是这样class StatusDelegate : public QStyledItemDelegate { Q_OBJECT public: explicit StatusDelegate(QObject *parent nullptr) : QStyledItemDelegate(parent) {} QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem option, const QModelIndex index) const override { Q_UNUSED(option); Q_UNUSED(index); auto *editor new QComboBox(parent); editor-addItem(tr(正常), normal); editor-addItem(tr(维护中), maintenance); editor-addItem(tr(已停用), disabled); return editor; } void setEditorData(QWidget *editor, const QModelIndex index) const override { auto *combo qobject_castQComboBox *(editor); if (!combo) return; const QString value index.data(Qt::EditRole).toString(); const int idx combo-findData(value); combo-setCurrentIndex(idx 0 ? idx : 0); } void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex index) const override { auto *combo qobject_castQComboBox *(editor); if (!combo) return; model-setData(index, combo-currentData(), Qt::EditRole); } void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem option, const QModelIndex index) const override { Q_UNUSED(index); editor-setGeometry(option.rect); } };这里有一个非常实际的建议QComboBox 的 itemData 里存状态码而不是存界面文案。setEditorData 用findData去定位当前值setModelData 用currentData写回模型。这样模型里存的一直是 normal、maintenance 这种稳定代号界面上显示的中文只是 DisplayRole 的表现层内容。将来要对接接口、写日志、做持久化都不会因为 UI 文案调整而出现脏数据。很容易踩的坑有两个。第一个setModelData 里拿到的editor是 QWidget 指针实际是 QComboBox必须qobject_cast判断一下万一某一列误挂了这个 delegate程序不至于直接崩掉。第二个updateEditorGeometry 如果不调用editor-setGeometry(option.rect)编辑器弹出的位置会和格子错位这个现象很隐蔽排查起来浪费不少时间。进度条列就完全是另一种用法了不需要编辑器只需要重写paintvoid ProgressDelegate::paint(QPainter *painter, const QStyleOptionViewItem option, const QModelIndex index) const { const int progress index.data(Qt::EditRole).toInt(); QStyleOptionProgressBar bar; bar.rect option.rect.adjusted(4, 4, -4, -4); bar.minimum 0; bar.maximum 100; bar.progress progress; bar.text QString(%1%).arg(progress); bar.textVisible true; QApplication::style()-drawControl(QStyle::CE_ProgressBar, bar, painter); }这里要理解 QStyleOptionViewItem 的作用它把当前格子的位置、选中态、焦点态全部封装好了。所以画进度条时必须以option.rect为基准而不是自己写死坐标。另外如果不判断option.state QStyle::State_Selected选中这一行时自定义绘制的内容可能会把系统的高亮背景盖掉观感上很奇怪。实际操作时我给进度条 rect 做了 4 像素的adjusted让画出来的进度条和格子边缘留一点空隙视觉上会舒服不少。挂载到表格上的方式是按列指定ui-tableView-setItemDelegateForColumn(1, new StatusDelegate(ui-tableView)); ui-tableView-setItemDelegateForColumn(3, new ProgressDelegate(ui-tableView));委托部分到这里基本够用。真正复杂的是下面这个分页功能它从一开始就让我重新思考了 Model 的职责边界。3. 翻页我为什么不直接滚动表格而要自己做控制条这个问题我一开始也犯嘀咕QTableView 自带滚动条数据多了滚一滚不就行了为什么非要翻页但真实场景会很快告诉你答案。几千行的设备表用户想改第 700 行某条数据的状态靠滚动条去定位非常痛苦。而且数据一旦来自数据库全量加载既不现实也不合理。翻页本质上解决的是“数据加载范围”和“用户定位效率”两个问题而不只是滚动体验。先说我考虑过的两种常见实现方向。第一种是 SQL 分页。如果底层用的是 QSqlQueryModel可以直接拼SELECT ... LIMIT offset, pageSize这样的语句每次翻页重新查询。这种方式适合数据量巨大、不能全部驻留内存的场景。缺点也很明显每次翻页都要访问数据库搜索条件还要拼进 SQL 里逻辑分散在 SQL 字符串中维护起来比较头疼。第二种是内存全量加载翻页时把当前页的数据复制到 QStandardItemModel 里。这种方式简单直接但每次翻页都要removeRows再插入新行数据量大时会有明显开销而且和搜索过滤联动时容易乱。我最终选择了一条更符合 Qt 模型思想的写法自定义一个分页模型内部挂着一个 QSortFilterProxyModel重写rowCount让模型只暴露当前页的数据重写data把页内行号映射回过滤后的真实行号。截取关键代码class DevicePageModel : public QAbstractTableModel { Q_OBJECT public: void setSourceProxy(QSortFilterProxyModel *proxy) { m_proxy proxy; } void setPageSize(int size) { if (size 0) return; m_pageSize size; refresh(); } void setCurrentPage(int page) { const int newPage qBound(1, page, m_totalPages); if (m_currentPage newPage) return; m_currentPage newPage; beginResetModel(); endResetModel(); } int pageCount() const { return m_totalPages; } int currentPage() const { return m_currentPage; } void refresh() { m_totalPages qMax(1, (m_proxy-rowCount() m_pageSize - 1) / m_pageSize); m_currentPage qBound(1, m_currentPage, m_totalPages); beginResetModel(); endResetModel(); } int rowCount(const QModelIndex parent QModelIndex()) const override { if (parent.isValid()) return 0; const int total m_proxy-rowCount(); if (total 0) return 0; const int start (m_currentPage - 1) * m_pageSize; return qMin(m_pageSize, total - start); } int columnCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_proxy-columnCount(); } QVariant data(const QModelIndex index, int role) const override { if (!index.isValid()) return {}; const int srcRow (m_currentPage - 1) * m_pageSize index.row(); const QModelIndex proxyIndex m_proxy-index(srcRow, index.column()); return m_proxy-data(proxyIndex, role); } private: QSortFilterProxyModel *m_proxy nullptr; int m_pageSize 20; int m_currentPage 1; int m_totalPages 1; };这里有几个要点值得单独强调。总页数计算必须用(total pageSize - 1) / pageSize而不是total / pageSize 1。前者在恰好整除时能得到正确的页数后者会在整除时多算一页。这个细节很多网上示例都写错了新手抄过去会发现最后一页是空的。页码一定要在setPageSize和refresh时用qBound做限制。如果当前在第 10 页每页条数从 20 改成 50总页数可能只剩 8 页这时候m_currentPage不校正rowCount里算出来的 start 就会超出范围轻则显示错乱重则越界崩溃。另外表头、按钮和页码标签的联动我是用一个普通 QWidget 控制条做的布局非常简单左侧放“共 N 条 / 第 x / y 页”的 Label右侧放“上一页 / 下一页”按钮再放一个每页条数的 QComboBox。控制条只负责调用 DevicePageModel 的接口不直接操作表格数据职责非常单一。有了分页模型接下来要解决的就是搜索过滤了。这两个功能看似独立实则在索引层面纠缠得非常深。4. 搜索框敲入关键字后数据到底该在哪里过滤搜索过滤有几种常见做法重查 SQL、手动遍历 QStandardItemModel 后重新 setData、还有用 QSortFilterProxyModel。本地内存数据这个场景我强烈建议优先用 QSortFilterProxyModel因为它在不破坏原始数据的前提下把过滤和排序一起免费给你了。我写了一个专用的过滤代理类核心是重写filterAcceptsRowclass SearchFilterProxy : public QSortFilterProxyModel { Q_OBJECT public: void setFilterColumns(const QVectorint cols) { m_columns cols; } void setKeyword(const QString kw) { const QString trimmed kw.trimmed(); if (m_keyword trimmed) return; m_keyword trimmed; invalidateFilter(); emit keywordChanged(m_keyword); } protected: bool filterAcceptsRow(int sourceRow, const QModelIndex sourceParent) const override { if (m_keyword.isEmpty()) return true; for (int col : m_columns) { const QModelIndex idx sourceModel()-index(sourceRow, col, sourceParent); const QString cell idx.data(Qt::DisplayRole).toString(); if (cell.contains(m_keyword, Qt::CaseInsensitive)) return true; } return false; } signals: void keywordChanged(const QString kw); private: QString m_keyword; QVectorint m_columns; };这里我做了两个细节处理。第一setKeyword里先 trim 再比较如果新旧关键字一样就直接返回避免输入空格等无意义字符时频繁触发invalidateFilter。第二匹配用contains加Qt::CaseInsensitive满足“不区分大小写”的需求。搜索范围按列配置将来要增加搜索字段只需要把列号加进 m_columns 就行。在界面上搜索框的textChanged信号不能直接粗暴地绑定setKeyword。每敲一个字符都会触发一次信号数据量稍大时连续过滤会让界面明显卡顿。我习惯加一个 200 到 300 毫秒的防抖m_searchTimer new QTimer(this); m_searchTimer-setSingleShot(true); m_searchTimer-setInterval(200); connect(ui-searchEdit, QLineEdit::textChanged, this, [this]() { m_searchTimer-start(); }); connect(m_searchTimer, QTimer::timeout, this, [this]() { m_proxy-setKeyword(ui-searchEdit-text()); });原理很简单用户每敲一个字定时器就被重置只有停下来超过 200 毫秒才真正执行过滤。这种防抖在搜索场景里几乎是标配值得养成习惯。另外我看网上很多人问“QTableView 搜索高亮”。如果只是快速定位数据用代理过滤就够了因为过滤后非匹配行直接隐藏眼睛只需要扫剩下的结果。高亮匹配文本则需要重写 delegate 的 paint 去画背景复杂度上来不少。建议先评估产品是不是真的需要这个效果不要为了炫技把搜索链路搅复杂。到这里委托、分页、搜索三个功能各自都能跑了。但把它们组合起来以后真正的麻烦才刚开始。5. 三个功能叠在一起后索引映射和数据刷新才是最大的坑如果只单独看前面每一章每个功能都不算难。但把 delegate 挂到分页模型上再让分页模型去包一个过滤代理索引关系一下子就变成多层了。我自己在这个阶段踩过不少坑有几个非常典型值得一个个说清楚。第一个坑delegate 收到的 index 不是 source model 的 index。当tableView-setModel(pageModel)以后delegate 的setModelData里拿到的 index 是“页面模型”内部的索引比如第 1 页第 3 行。如果你不管三七二十一直接拿这个 index 去调model-setData就必须让 DevicePageModel 自己实现 setData并且把页内行号映射回真实数据行否则数据根本写不进去。DevicePageModel 的 setData 需要这样实现bool DevicePageModel::setData(const QModelIndex index, const QVariant value, int role) { if (!index.isValid()) return false; const int srcRow (m_currentPage - 1) * m_pageSize index.row(); const QModelIndex proxyIndex m_proxy-index(srcRow, index.column()); const QModelIndex sourceIndex m_proxy-mapToSource(proxyIndex); return m_proxy-sourceModel()-setData(sourceIndex, value, role); }这个映射链路是页面行号 → 过滤代理行号 → 原始模型行号。少任何一环数据就会写到错误的位置。第二个坑搜索和翻页必须联动刷新。当用户清空搜索词时过滤代理的 rowCount 可能从几十一下子变成几千DevicePageModel 内部的总页数和当前页如果不重新计算页数标签、翻页按钮状态、当前显示的行就会全部错乱。我之前遇到过一个很典型的 bug搜索“张三”匹配到 40 条用户点到第 2 页然后清空搜索词页码还停在 2/2但底下其实已经有几千条数据了。解决办法是我在 SearchFilterProxy 里定义了一个keywordChanged信号上层收到后调用pageModel-refresh()把总页数和当前页一次性校正。这个信号是必须的因为 DevicePageModel 无法主动感知代理内部过滤结果的变化。第三个坑删除行的逻辑绝不能直接用界面 currentIndex 去删原始数据。正确顺序是先通过 PageModel 映射到代理索引再调用mapToSource得到原始索引最后在 sourceModel 上执行删除QModelIndex current ui-tableView-currentIndex(); int srcRow m_pageModel-mapRowToProxy(current.row()); QModelIndex proxyIndex m_proxy-index(srcRow, current.column()); QModelIndex sourceIndex m_proxy-mapToSource(proxyIndex); m_sourceModel-removeRow(sourceIndex.row());我后来把mapRowToProxy直接封装成了 DevicePageModel 的公开接口这样 delegate、外部槽函数、还有控制条都能复用同一套映射逻辑避免到处写重复代码。第四个坑性能相关的小开关。在填充数据之前最好先调用ui-tableView-setUniformRowHeights(true);这个设置告诉 view 所有行的高度一致Qt 在布局时就不需要对每一行单独测量高度几千行数据时能明显减少计算量。如果开启表头排序还要让代理设置setDynamicSortFilter(true)这样排序和过滤能联动。但注意点击表头排序之后PageModel 的当前页内容可能会变化建议监听排序信号后也调用一次pageModel-refresh()。第五个坑表头样式。这是 QTableView 使用中特别高频的需求顺带一起说了。我用一行 QSS 就解决了表头背景、边框和字体问题ui-tableView-horizontalHeader()-setStyleSheet( QHeaderView::section { background: #f5f5f5; border: 1px solid #dcdcdc; padding: 4px; } );如果启用了排序表头默认还会显示排序箭头颜色可以自己再调但注意 QSS 里不要写死亮度太高的颜色否则和选中态混在一起时容易看不清。注意用 QSortFilterProxyModel 时如果 sourceModel 的数据发生了增删一定要确保 sourceModel 正确发出 beginInsertRows / endInsertRows、beginRemoveRows / endRemoveRows 这组信号。否则代理内部的行数缓存不会更新过滤结果也不会自动刷新。这个 bug 的表现很诡异页面数据明明变了表格却还是旧的。把 QTableView 的委托、翻页、搜索放进一个项目里做完之后我最大的感受是Qt 的 Model/View 体系单独看每个概念都不难真正的复杂度在于“索引到底属于哪个模型”。哪怕只是包了两层模型一个 mapToSource 漏掉程序就会在特定翻页、特定搜索词下出现诡异行为还很难复现。现在我再遇到类似的表格需求基本固定用这套组合QStandardItemModel 管原始数据QSortFilterProxyModel 管搜索和排序DevicePageModel 管分页QStyledItemDelegate 管定制绘制和编辑。每一层职责单一出问题最多十分钟就能定位到具体是哪一层。如果你也正准备做这类功能我的建议是动手写代码之前先把模型层级和索引映射关系画清楚这个顺序能帮你少走一大截弯路。本文还有配套的精品资源点击获取
Qt表格控件实战：QTableView委托分页搜索组合方案
简介面向Qt开发者的QTableView功能扩展示例包聚焦委托、分页与搜索三项常见表格需求。通过继承QItemDelegate自定义单元格样式与交互可绘制按钮、复选框、下拉框、编辑框、进度条等控件并针对不同业务场景包装相应委托类分页功能由独立组件实现支持页码切换与视图同步搜索功能则依托代理模型执行实时过滤。资源共17个文件含11个头文件、5个源文件与1个工程配置文件压缩包仅18KB结构紧凑。工程内部划分主视图、数据模型、分页模块与委托控件头文件负责接口声明源文件实现具体逻辑pri文件便于Qt工程直接引用。已有420人学习使用内容覆盖委托事件处理、分页切换、过滤规则、模型刷新等关键环节适合初中级Qt开发者快速理解并复用到实际表格场景也可作为课程设计或业务模块的起步代码。 把 QTableView 的委托、翻页、搜索三个功能放进同一个项目里做是我在开发一个设备台账管理工具时被逼出来的。用户的诉求其实很朴素双击状态列不要弹出光秃秃的输入框而是给一个下拉选择一页别滚出几千行只想看 20 条输入关键字能在几秒内定位到设备而不是靠肉眼在表里扫。这三个需求拆开看都是 Qt 文档里的常规操作真正麻烦的是它们同时叠在一张表上之后索引关系瞬间变得复杂。这篇文章把我在整个过程中的设计取舍、核心代码和踩坑记录完整写出来给正在做桌面端数据管理界面的同行一个参考。1. 为什么一个设备管理小工具会被这三个功能逼到重写刚开始我图省事表格控件直接用了 QTableWidget。小规模数据、简单展示的场景下QTableWidget 确实快双击编辑、表头排序全都现成。但需求一旦走到“状态列只能从下拉框选”“进度列要显示进度条”“要接搜索过滤”这一步QTableWidget 就不够用了。原因很简单QTableWidget 把所有东西都封装死了你能拿到的是一个完整的 item但如果要干预“格子怎么画”“编辑器用什么组件”你通常得绕到它内部去非常别扭。QTableView 这套体系就不一样。它的核心思路是把数据、视图、编辑彻底分层QAbstractItemModel 管数据长什么样QTableView 管布局和展示QStyledItemDelegate 管每个单元格的画法和编辑器。这个分层在初期看起来代码量比 QTableWidget 多但到了定制阶段每一层都能单独替换完全不会互相牵扯。我梳理了一下实际需求最终落到这四件事上设备状态列双击时弹出下拉框只能选“正常/维护中/停用”禁止自由输入生命周期进度列直接画一个进度条样式不需要进入编辑状态表格默认每页显示 20 行顶部提供上一页、下一页、页码和每页条数搜索框输入关键字后按“设备名称、类型、所属责任人”三列做不区分大小写的匹配。这四个需求对应到 Qt 的组件上正好是 QStyledItemDelegate、分页模型、QSortFilterProxyModel 三块内容。把它们放一起之后我才意识到真正的难点不在某一个功能而是它们组合在一起时的协作。后面每一章会按这个顺序拆开讲。2. 委托怎么写才能既改了样式又不影响编辑链路委托delegate是刚开始最容易理解偏的地方。很多人把它当成“改单元格样式的工具”其实 QStyledItemDelegate 管的远不止样式。它管的是“绘制 编辑”一整条链路正常状态下单元格怎么画双击后用什么编辑器编辑器打开时怎么把当前值塞进去编辑器关闭时怎么把新值写回模型这几个环节全部由 delegate 接管。我当时一口气写了两个 delegate。一个是状态列的下拉编辑器另一个是进度条列的自定义绘制。两个都基于 QStyledItemDelegate 派生而不是老旧的 QItemDelegate原因在于 QStyledItemDelegate 会优先服从全局 QSS 样式表和项目的主题风格保持一致QItemDelegate 则不会。状态列下拉委托的核心代码是这样class StatusDelegate : public QStyledItemDelegate { Q_OBJECT public: explicit StatusDelegate(QObject *parent nullptr) : QStyledItemDelegate(parent) {} QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem option, const QModelIndex index) const override { Q_UNUSED(option); Q_UNUSED(index); auto *editor new QComboBox(parent); editor-addItem(tr(正常), normal); editor-addItem(tr(维护中), maintenance); editor-addItem(tr(已停用), disabled); return editor; } void setEditorData(QWidget *editor, const QModelIndex index) const override { auto *combo qobject_castQComboBox *(editor); if (!combo) return; const QString value index.data(Qt::EditRole).toString(); const int idx combo-findData(value); combo-setCurrentIndex(idx 0 ? idx : 0); } void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex index) const override { auto *combo qobject_castQComboBox *(editor); if (!combo) return; model-setData(index, combo-currentData(), Qt::EditRole); } void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem option, const QModelIndex index) const override { Q_UNUSED(index); editor-setGeometry(option.rect); } };这里有一个非常实际的建议QComboBox 的 itemData 里存状态码而不是存界面文案。setEditorData 用findData去定位当前值setModelData 用currentData写回模型。这样模型里存的一直是 normal、maintenance 这种稳定代号界面上显示的中文只是 DisplayRole 的表现层内容。将来要对接接口、写日志、做持久化都不会因为 UI 文案调整而出现脏数据。很容易踩的坑有两个。第一个setModelData 里拿到的editor是 QWidget 指针实际是 QComboBox必须qobject_cast判断一下万一某一列误挂了这个 delegate程序不至于直接崩掉。第二个updateEditorGeometry 如果不调用editor-setGeometry(option.rect)编辑器弹出的位置会和格子错位这个现象很隐蔽排查起来浪费不少时间。进度条列就完全是另一种用法了不需要编辑器只需要重写paintvoid ProgressDelegate::paint(QPainter *painter, const QStyleOptionViewItem option, const QModelIndex index) const { const int progress index.data(Qt::EditRole).toInt(); QStyleOptionProgressBar bar; bar.rect option.rect.adjusted(4, 4, -4, -4); bar.minimum 0; bar.maximum 100; bar.progress progress; bar.text QString(%1%).arg(progress); bar.textVisible true; QApplication::style()-drawControl(QStyle::CE_ProgressBar, bar, painter); }这里要理解 QStyleOptionViewItem 的作用它把当前格子的位置、选中态、焦点态全部封装好了。所以画进度条时必须以option.rect为基准而不是自己写死坐标。另外如果不判断option.state QStyle::State_Selected选中这一行时自定义绘制的内容可能会把系统的高亮背景盖掉观感上很奇怪。实际操作时我给进度条 rect 做了 4 像素的adjusted让画出来的进度条和格子边缘留一点空隙视觉上会舒服不少。挂载到表格上的方式是按列指定ui-tableView-setItemDelegateForColumn(1, new StatusDelegate(ui-tableView)); ui-tableView-setItemDelegateForColumn(3, new ProgressDelegate(ui-tableView));委托部分到这里基本够用。真正复杂的是下面这个分页功能它从一开始就让我重新思考了 Model 的职责边界。3. 翻页我为什么不直接滚动表格而要自己做控制条这个问题我一开始也犯嘀咕QTableView 自带滚动条数据多了滚一滚不就行了为什么非要翻页但真实场景会很快告诉你答案。几千行的设备表用户想改第 700 行某条数据的状态靠滚动条去定位非常痛苦。而且数据一旦来自数据库全量加载既不现实也不合理。翻页本质上解决的是“数据加载范围”和“用户定位效率”两个问题而不只是滚动体验。先说我考虑过的两种常见实现方向。第一种是 SQL 分页。如果底层用的是 QSqlQueryModel可以直接拼SELECT ... LIMIT offset, pageSize这样的语句每次翻页重新查询。这种方式适合数据量巨大、不能全部驻留内存的场景。缺点也很明显每次翻页都要访问数据库搜索条件还要拼进 SQL 里逻辑分散在 SQL 字符串中维护起来比较头疼。第二种是内存全量加载翻页时把当前页的数据复制到 QStandardItemModel 里。这种方式简单直接但每次翻页都要removeRows再插入新行数据量大时会有明显开销而且和搜索过滤联动时容易乱。我最终选择了一条更符合 Qt 模型思想的写法自定义一个分页模型内部挂着一个 QSortFilterProxyModel重写rowCount让模型只暴露当前页的数据重写data把页内行号映射回过滤后的真实行号。截取关键代码class DevicePageModel : public QAbstractTableModel { Q_OBJECT public: void setSourceProxy(QSortFilterProxyModel *proxy) { m_proxy proxy; } void setPageSize(int size) { if (size 0) return; m_pageSize size; refresh(); } void setCurrentPage(int page) { const int newPage qBound(1, page, m_totalPages); if (m_currentPage newPage) return; m_currentPage newPage; beginResetModel(); endResetModel(); } int pageCount() const { return m_totalPages; } int currentPage() const { return m_currentPage; } void refresh() { m_totalPages qMax(1, (m_proxy-rowCount() m_pageSize - 1) / m_pageSize); m_currentPage qBound(1, m_currentPage, m_totalPages); beginResetModel(); endResetModel(); } int rowCount(const QModelIndex parent QModelIndex()) const override { if (parent.isValid()) return 0; const int total m_proxy-rowCount(); if (total 0) return 0; const int start (m_currentPage - 1) * m_pageSize; return qMin(m_pageSize, total - start); } int columnCount(const QModelIndex parent QModelIndex()) const override { return parent.isValid() ? 0 : m_proxy-columnCount(); } QVariant data(const QModelIndex index, int role) const override { if (!index.isValid()) return {}; const int srcRow (m_currentPage - 1) * m_pageSize index.row(); const QModelIndex proxyIndex m_proxy-index(srcRow, index.column()); return m_proxy-data(proxyIndex, role); } private: QSortFilterProxyModel *m_proxy nullptr; int m_pageSize 20; int m_currentPage 1; int m_totalPages 1; };这里有几个要点值得单独强调。总页数计算必须用(total pageSize - 1) / pageSize而不是total / pageSize 1。前者在恰好整除时能得到正确的页数后者会在整除时多算一页。这个细节很多网上示例都写错了新手抄过去会发现最后一页是空的。页码一定要在setPageSize和refresh时用qBound做限制。如果当前在第 10 页每页条数从 20 改成 50总页数可能只剩 8 页这时候m_currentPage不校正rowCount里算出来的 start 就会超出范围轻则显示错乱重则越界崩溃。另外表头、按钮和页码标签的联动我是用一个普通 QWidget 控制条做的布局非常简单左侧放“共 N 条 / 第 x / y 页”的 Label右侧放“上一页 / 下一页”按钮再放一个每页条数的 QComboBox。控制条只负责调用 DevicePageModel 的接口不直接操作表格数据职责非常单一。有了分页模型接下来要解决的就是搜索过滤了。这两个功能看似独立实则在索引层面纠缠得非常深。4. 搜索框敲入关键字后数据到底该在哪里过滤搜索过滤有几种常见做法重查 SQL、手动遍历 QStandardItemModel 后重新 setData、还有用 QSortFilterProxyModel。本地内存数据这个场景我强烈建议优先用 QSortFilterProxyModel因为它在不破坏原始数据的前提下把过滤和排序一起免费给你了。我写了一个专用的过滤代理类核心是重写filterAcceptsRowclass SearchFilterProxy : public QSortFilterProxyModel { Q_OBJECT public: void setFilterColumns(const QVectorint cols) { m_columns cols; } void setKeyword(const QString kw) { const QString trimmed kw.trimmed(); if (m_keyword trimmed) return; m_keyword trimmed; invalidateFilter(); emit keywordChanged(m_keyword); } protected: bool filterAcceptsRow(int sourceRow, const QModelIndex sourceParent) const override { if (m_keyword.isEmpty()) return true; for (int col : m_columns) { const QModelIndex idx sourceModel()-index(sourceRow, col, sourceParent); const QString cell idx.data(Qt::DisplayRole).toString(); if (cell.contains(m_keyword, Qt::CaseInsensitive)) return true; } return false; } signals: void keywordChanged(const QString kw); private: QString m_keyword; QVectorint m_columns; };这里我做了两个细节处理。第一setKeyword里先 trim 再比较如果新旧关键字一样就直接返回避免输入空格等无意义字符时频繁触发invalidateFilter。第二匹配用contains加Qt::CaseInsensitive满足“不区分大小写”的需求。搜索范围按列配置将来要增加搜索字段只需要把列号加进 m_columns 就行。在界面上搜索框的textChanged信号不能直接粗暴地绑定setKeyword。每敲一个字符都会触发一次信号数据量稍大时连续过滤会让界面明显卡顿。我习惯加一个 200 到 300 毫秒的防抖m_searchTimer new QTimer(this); m_searchTimer-setSingleShot(true); m_searchTimer-setInterval(200); connect(ui-searchEdit, QLineEdit::textChanged, this, [this]() { m_searchTimer-start(); }); connect(m_searchTimer, QTimer::timeout, this, [this]() { m_proxy-setKeyword(ui-searchEdit-text()); });原理很简单用户每敲一个字定时器就被重置只有停下来超过 200 毫秒才真正执行过滤。这种防抖在搜索场景里几乎是标配值得养成习惯。另外我看网上很多人问“QTableView 搜索高亮”。如果只是快速定位数据用代理过滤就够了因为过滤后非匹配行直接隐藏眼睛只需要扫剩下的结果。高亮匹配文本则需要重写 delegate 的 paint 去画背景复杂度上来不少。建议先评估产品是不是真的需要这个效果不要为了炫技把搜索链路搅复杂。到这里委托、分页、搜索三个功能各自都能跑了。但把它们组合起来以后真正的麻烦才刚开始。5. 三个功能叠在一起后索引映射和数据刷新才是最大的坑如果只单独看前面每一章每个功能都不算难。但把 delegate 挂到分页模型上再让分页模型去包一个过滤代理索引关系一下子就变成多层了。我自己在这个阶段踩过不少坑有几个非常典型值得一个个说清楚。第一个坑delegate 收到的 index 不是 source model 的 index。当tableView-setModel(pageModel)以后delegate 的setModelData里拿到的 index 是“页面模型”内部的索引比如第 1 页第 3 行。如果你不管三七二十一直接拿这个 index 去调model-setData就必须让 DevicePageModel 自己实现 setData并且把页内行号映射回真实数据行否则数据根本写不进去。DevicePageModel 的 setData 需要这样实现bool DevicePageModel::setData(const QModelIndex index, const QVariant value, int role) { if (!index.isValid()) return false; const int srcRow (m_currentPage - 1) * m_pageSize index.row(); const QModelIndex proxyIndex m_proxy-index(srcRow, index.column()); const QModelIndex sourceIndex m_proxy-mapToSource(proxyIndex); return m_proxy-sourceModel()-setData(sourceIndex, value, role); }这个映射链路是页面行号 → 过滤代理行号 → 原始模型行号。少任何一环数据就会写到错误的位置。第二个坑搜索和翻页必须联动刷新。当用户清空搜索词时过滤代理的 rowCount 可能从几十一下子变成几千DevicePageModel 内部的总页数和当前页如果不重新计算页数标签、翻页按钮状态、当前显示的行就会全部错乱。我之前遇到过一个很典型的 bug搜索“张三”匹配到 40 条用户点到第 2 页然后清空搜索词页码还停在 2/2但底下其实已经有几千条数据了。解决办法是我在 SearchFilterProxy 里定义了一个keywordChanged信号上层收到后调用pageModel-refresh()把总页数和当前页一次性校正。这个信号是必须的因为 DevicePageModel 无法主动感知代理内部过滤结果的变化。第三个坑删除行的逻辑绝不能直接用界面 currentIndex 去删原始数据。正确顺序是先通过 PageModel 映射到代理索引再调用mapToSource得到原始索引最后在 sourceModel 上执行删除QModelIndex current ui-tableView-currentIndex(); int srcRow m_pageModel-mapRowToProxy(current.row()); QModelIndex proxyIndex m_proxy-index(srcRow, current.column()); QModelIndex sourceIndex m_proxy-mapToSource(proxyIndex); m_sourceModel-removeRow(sourceIndex.row());我后来把mapRowToProxy直接封装成了 DevicePageModel 的公开接口这样 delegate、外部槽函数、还有控制条都能复用同一套映射逻辑避免到处写重复代码。第四个坑性能相关的小开关。在填充数据之前最好先调用ui-tableView-setUniformRowHeights(true);这个设置告诉 view 所有行的高度一致Qt 在布局时就不需要对每一行单独测量高度几千行数据时能明显减少计算量。如果开启表头排序还要让代理设置setDynamicSortFilter(true)这样排序和过滤能联动。但注意点击表头排序之后PageModel 的当前页内容可能会变化建议监听排序信号后也调用一次pageModel-refresh()。第五个坑表头样式。这是 QTableView 使用中特别高频的需求顺带一起说了。我用一行 QSS 就解决了表头背景、边框和字体问题ui-tableView-horizontalHeader()-setStyleSheet( QHeaderView::section { background: #f5f5f5; border: 1px solid #dcdcdc; padding: 4px; } );如果启用了排序表头默认还会显示排序箭头颜色可以自己再调但注意 QSS 里不要写死亮度太高的颜色否则和选中态混在一起时容易看不清。注意用 QSortFilterProxyModel 时如果 sourceModel 的数据发生了增删一定要确保 sourceModel 正确发出 beginInsertRows / endInsertRows、beginRemoveRows / endRemoveRows 这组信号。否则代理内部的行数缓存不会更新过滤结果也不会自动刷新。这个 bug 的表现很诡异页面数据明明变了表格却还是旧的。把 QTableView 的委托、翻页、搜索放进一个项目里做完之后我最大的感受是Qt 的 Model/View 体系单独看每个概念都不难真正的复杂度在于“索引到底属于哪个模型”。哪怕只是包了两层模型一个 mapToSource 漏掉程序就会在特定翻页、特定搜索词下出现诡异行为还很难复现。现在我再遇到类似的表格需求基本固定用这套组合QStandardItemModel 管原始数据QSortFilterProxyModel 管搜索和排序DevicePageModel 管分页QStyledItemDelegate 管定制绘制和编辑。每一层职责单一出问题最多十分钟就能定位到具体是哪一层。如果你也正准备做这类功能我的建议是动手写代码之前先把模型层级和索引映射关系画清楚这个顺序能帮你少走一大截弯路。本文还有配套的精品资源点击获取
