Qt表格性能优化实战：从QTableWidget到QTableView自定义模型

做了这么多年Qt，几乎每个从入门往进阶走的同学都会在表格这关卡一下。刚开始用 QTableWidget 觉得真香，setItem、setText 一行行写就能跑；等数据量到了几千行、几万行，界面开始卡顿、内存开始膨胀，才意识到 Qt 的表格远不是"往里塞数据"这么简单。我见过太多帖子问"为什么我的 Qt 表格 1 万行数据就卡成 PPT"，其实问题往往不在硬件，而在切入姿势不对。

这篇文章定位成"入门之后、优化之前"必读的一篇。主线非常明确：从 QTableWidget 换到 QTableView 加自定义模型，再配合刷新策略、委托绘制、数据缓存这些手段，把表格从"能显示"拉到"抗得住"的级别。适合用过基础控件、写过简单增删改查、但没搞明白性能瓶颈在哪的 Qt 新手，也适合项目里表格已经开始拖垮界面、想从架构层重新梳理一遍的开发者。文章里的代码我都基于 Qt 5.15.2 验证过，后面会放一组这台环境下的实测数据给你参考。

1. 项目概述：先搞清楚Qt表格优化的边界

1.1 你卡在哪一步：QTableWidget和QTableView差在哪

很多新手不知道，Qt 其实提供了两套表格接口。QTableWidget 是给人快速上手的"便捷款"，底层是 QTableView + 内部自带的模型，你每写一行 setItem(row, col, new QTableWidgetItem(...))，它就在内部帮你创建了一个 QTableWidgetItem 对象，把数据、文字颜色、背景色、图标、对齐方式全部挂在这个对象身上。

听起来很方便，对吧？但在数据量上来之后，这种方便就是原罪。一张 1000 行 × 20 列的表格，意味着你要创建 2 万个 QTableWidgetItem，每个对象带自己的 flags、data、background，加上 QString 的深拷贝，轻松吃掉几 MB 甚至十几 MB。更麻烦的是，插入 item 的过程中表格会频繁触发布局和重绘，数据一多，插入阶段就开始肉眼可见地卡。

QTableView 不一样。它本身不保管数据，只负责"按需绘制"。你给它一个模型，它滚动到哪一行就只问模型要那一行的数据，屏幕上不可见的行根本不会去创建任何对象。同样是 100 万行数据，QTableView 只关心当前视口里能看见的那几十行，这才是它能扛大数据的根本原因。

1.2 模型/视图架构为什么是性能分水岭

模型/视图（Model/View）架构听起来高大上，其实道理很朴素：数据和显示分离。你的业务数据放在自己的内存结构里（比如 QVector<QVector<QVariant>>），模型负责给视图提供"标准格式"的数据访问接口，视图负责把数据画出来。视图完全不需要知道你底层是数组、数据库还是文件，它只调 data() 这个方法。

理解这一点之后，你也就理解了优化的大方向：所有优化，都要围绕"如何让模型更快地回答问题"和"如何让视图更少地问问题"来做。比如数据加载慢，就优化模型的查询逻辑；滚动卡，就减少视图的重复计算（固定行高、缓存）；界面闪烁，就是刷新粒度太大，把 reset 改成精准的 dataChanged。这篇文章后面的所有内容，本质都是在反复实践这两句话。

2. 第一步落地：从QTableWidget换到QTableView加自定义模型

2.1 自定义模型的核心代码长什么样

直接上代码。这个模型是我平时项目里最常用的骨架，只读、数据存在内存二维数组里，够应付绝大多数展示场景：

cpp复制#include <QAbstractTableModel>
#include <QVector>

class SampleTableModel : public QAbstractTableModel
{
    Q_OBJECT

public:
    explicit SampleTableModel(QObject *parent = nullptr)
        : QAbstractTableModel(parent)
    {
    }

    int rowCount(const QModelIndex &parent = QModelIndex()) const override
    {
        if (parent.isValid())
            return 0;
        return m_data.size();
    }

    int columnCount(const QModelIndex &parent = QModelIndex()) const override
    {
        if (parent.isValid())
            return 0;
        return m_cols;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        if (!index.isValid())
            return QVariant();

        if (role == Qt::DisplayRole)
            return m_data.value(index.row()).value(index.column());

        return QVariant();
    }

    QVariant headerData(int section, Qt::Orientation orientation, int role) const override
    {
        if (role != Qt::DisplayRole)
            return QVariant();

        if (orientation == Qt::Horizontal)
            return QStringLiteral("第 %1 列").arg(section + 1);

        return QString::number(section + 1);
    }

    void appendRow(const QVector<QVariant> &row)
    {
        beginInsertRows(QModelIndex(), m_data.size(), m_data.size());
        m_data.append(row);
        if (m_cols < row.size())
            m_cols = row.size();
        endInsertRows();
    }

private:
    QVector<QVector<QVariant>> m_data;
    int m_cols = 0;
};

要注意两个最容易写错的地方。第一，rowCount() 和 columnCount() 里如果传进来的 parent 是有效的，一定要返回 0。表格模型是"无父子"的平面结构，乱返回数据会让视图在递归遍历时产生莫名其妙的问题。第二，data() 里只处理你需要的 role，最常见的就是 Qt::DisplayRole 和 Qt::EditRole。如果你把每个 role 都去查一遍数据源，性能会成倍下降。

2.2 界面侧挂载时要注意的三个细节

模型写完后，挂到界面上很简单，但三个细节决定了你能不能享受到性能红利：

cpp复制auto *view = new QTableView(this);
auto *model = new SampleTableModel(this);

view->setModel(model);
view->setUniformRowHeights(true);
view->verticalHeader()->setDefaultSectionSize(28);
view->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch);

第一，setUniformRowHeights(true) 一定要设。它告诉视图"所有行高度一致"，视图在滚动时就可以用简单的乘法算出应该显示哪些行，不需要逐行测量高度。如果你的行高不是统一的，视图每次滚动都要调用 sizeHintForRow() 去计算，行数一多滚动就发飘。

第二，verticalHeader()->setDefaultSectionSize(28) 是配合上一条用的。设一个稳定的行高，默认值一般是 30 左右，具体看你字号。别让用户随便拖动行高，一旦行高变得不统一，setUniformRowHeights 就白设了。

第三，列宽模式要按照业务来。固定列数和固定内容宽度的表格用 QHeaderView::Stretch 或 QHeaderView::Fixed 最稳；列数不固定、需要横向滚动的，用 QHeaderView::Interactive，但别在滚动区域里放太多列。列宽也是同样的道理，列少的时候看不出来，列一多，每个单元格都要重新计算宽度，代价直接翻倍。

2.3 批量灌数据的正确姿势：reset和insert要选对

我在刚写模型的时候踩过一个坑：用 appendRow() 循环插入 10 万行，结果比 QTableWidget 还慢。原因很简单，beginInsertRows()/endInsertRows() 每调用一次，视图就要做一次布局刷新，10 万次插入就是 10 万次刷新，不卡才怪。

正确做法是：数据量小、需要动态追加用 insert 系列；数据量大、一次性加载用 reset 系列。比如在构造函数或者加载函数里，先把数据全部塞进 m_data，然后一次性通知视图：

cpp复制void SampleTableModel::bulkLoad(const QVector<QVector<QVariant>> &rows)
{
    beginResetModel();
    m_data = rows;
    m_cols = rows.isEmpty() ? 0 : rows.first().size();
    endResetModel();
}

beginResetModel()/endResetModel() 会让视图丢弃所有缓存、完全重建，代价也不小，但相比几万次增量 insert，这个代价完全值得。实际项目里我更推荐折中方案：分页加载，比如每 500 行调用一次 beginInsertRows，这样既不会卡死界面，又能保持视图增量更新的能力。

3. 刷新与更新策略：把全量重绘变成精准通知

3.1 批量改数据必须知道的三个开关

模型/视图架构下，界面刷新是"模型发信号、视图接收信号后自动重绘"的链路。性能优化很多就是在管这条链路的粗细。有三个开关我建议你写到肌肉记忆里。

第一个是 setUpdatesEnabled(false)。当你需要在界面上批量修改表格属性（比如批量设置列宽、批量 setSpan 合并单元格）时，先禁用更新，改完再启用，能避免中间过程反复重绘。这个接口对任何 QWidget 都有效，不只是表格。

第二个是 setSortingEnabled(false)。如果你要在表格里大批量更新数据，排序功能会跟着每次数据变化重新排序，这是巨大的性能黑洞。先把排序关掉，数据更新完再打开，再手动排一次。

第三个是 blockSignals(true)。有时候你会批量操作表格的 selection、currentIndex 等，如果不想每次操作都触发一堆信号，可以在批量操作期间 block 掉。但这个要小心用，因为 blockSignals 把所有信号都屏蔽了，容易误伤业务逻辑，我用得比较少，主要还是前面两个。

3.2 dataChanged 不要乱发，index 是优化弹药

很多人在写完自定义模型后，更新数据只会一招：beginResetModel() + endResetModel()。这个组合的副作用是视图全量重绘，如果只是几十行数据变化，性能浪费很明显。正确的做法是发 dataChanged 信号，告诉视图"只有某一小片区域的某个 role 变了"。

cpp复制void SampleTableModel::updateCell(int row, int column, const QVariant &value)
{
    if (row < 0 || row >= m_data.size())
        return;
    if (column < 0 || column >= m_data.at(row).size())
        return;

    m_data[row][column] = value;

    QModelIndex topLeft = createIndex(row, column);
    QModelIndex bottomRight = createIndex(row, column);
    emit dataChanged(topLeft, bottomRight, {Qt::DisplayRole});
}

这里有两个坑必须记住。第一，createIndex(row, column) 的参数顺序是行在前、列在后，千万别写反，写反了视图会刷新一块完全错误的地方，而且很难排查。第二，第三个参数是 roles 列表，标出你改了哪些角色。如果只改了显示内容，就传 {Qt::DisplayRole}；如果改了背景色，就把 Qt::BackgroundRole 也加进去。传得越精准，视图内部需要重绘的工作量就越小。

如果是一整行数据更新，就把 topLeft 设成 createIndex(row, 0)，bottomRight 设成 createIndex(row, columnCount() - 1)。如果动态插删行，还是老老实实用 insertRows/removeRows 的 begin/end 系列，不要偷懒用 reset，否则视图的选中状态、滚动位置全都会被破坏。

3.3 排序筛选走代理：QSortFilterProxyModel的正确用法

表格带排序和筛选是刚需。不少新手直接改底层数据顺序，后果是视图原来的行号对不上数据，选中、编辑全乱套。正确做法是套一个 QSortFilterProxyModel 代理模型，把排序筛选逻辑放到数据源和视图之间：

cpp复制auto *sourceModel = new SampleTableModel(this);
auto *proxyModel = new QSortFilterProxyModel(this);
proxyModel->setSourceModel(sourceModel);
proxyModel->setDynamicSortFilter(false); // 数据量大时先关掉动态排序

view->setModel(proxyModel);
view->setSortingEnabled(true);

QSortFilterProxyModel 的好处是它不改动源模型的任何数据。点击表头排序时，它维护一张"源模型行号 → 代理模型行号"的映射表，视图只感知代理模型，源数据顺序完全不受影响。这样业务逻辑里你仍然可以用原始行号定位数据，不用在界面层做一层反查。

性能方面记住一条原则：数据量大的时候把 setDynamicSortFilter(false) 设上。动态排序开启时，源模型每次数据变化都会触发一次过滤排序，数据量大就是无底洞。关掉之后，你可以自己决定什么时候调用 proxyModel->sort()，主动权在自己手里。筛选类做模糊搜索的场景，我一般还会加一层 QTimer 防抖，用户停止输入 300ms 之后再真正过滤。

4. 视觉与绘制优化：委托(Delegate)让表格又快又好看

4.1 用委托画进度条：一个能直接抄的案例

表格光有文字不够用，比如任务列表要显示进度。新手朋友第一反应是往单元格里塞 QProgressBar，用 setCellWidget 挂在表格上。这种方案在几十行内还凑合，行数一过百，你就知道痛了：每个 QProgressBar 都是一个独立的重量级控件，滚动、重绘、内存全都要付出代价。

正确方案是自定义委托（Delegate），用绘制的方式"画"出进度条。下面这个委托是我项目里一直在用的简化版：

cpp复制#include <QStyledItemDelegate>
#include <QPainter>

class ProgressBarDelegate : public QStyledItemDelegate
{
public:
    using QStyledItemDelegate::QStyledItemDelegate;

    void paint(QPainter *painter, const QStyleOptionViewItem &option,
               const QModelIndex &index) const override
    {
        // 进度值存在 UserRole+1 里，避开 DisplayRole 的文本处理
        const int progress = index.data(Qt::UserRole + 1).toInt();

        if (progress < 0 || progress > 100) {
            QStyledItemDelegate::paint(painter, option, index);
            return;
        }

        painter->save();
        // 背景
        painter->fillRect(option.rect.adjusted(2, 4, -2, -4), QColor("#e8eaed"));
        // 进度条
        const int barWidth = qRound((option.rect.width() - 4) * progress / 100.0);
        painter->fillRect(
            QRect(option.rect.left() + 2, option.rect.top() + 4,
                  qMax(0, barWidth), option.rect.height() - 8),
            QColor("#34a853"));
        painter->restore();
    }
};

在视图中启用委托只需要一行：view->setItemDelegateForColumn(3, new ProgressBarDelegate(view));。委托只对可见单元格执行 paint，所以即使模型有 10 万行，真正被调用的 paint 也只是屏幕上那几十个单元格。视图滚动时，委托跟在可见区域后不断绘制，性能比 setCellWidget 高一个数量级不止。

4.2 委托绘制的四条规定

自定义委托写多了，我总结出四条不成文的规定，能帮你把绘制性能压到极限。

第一，不要在 paint 里频繁创建对象。QPen、QBrush、QColor 这些尽量定义成委托的成员变量或者局部复用，不要在每次调用里新建。一次 paint 可能被 Qt 内部连续调用几十次，每次 new 一个对象，虽然单个不贵，累积起来就是肉眼可见的 CPU 占用。

第二，所有绘制都要基于 option.rect。千万不能假设单元格在某个固定坐标，表格滚动、缩放之后所有坐标都变了。option.rect 是视图算好给你的"当前可见区域中的单元格矩形"，你只需要在它内部做绘制，其余交给视图处理。

第三，能用一个颜色涂满的，绝对不要用渐变。渐变、阴影、圆角这些视觉效果好看，但都是处理器密集操作。大数据量的表格，我建议把花哨效果留给表头和合计行，正文区坚持朴素路线。

第四，sizeHint 永远要轻量。委托的 sizeHint() 会被视图反复调用，尤其在没有固定行高的情况下。不要在 sizeHint 里做字符串截断、换行计算之类操作，返回一个估算值就够。真需要复杂排版，宁可牺牲一点精确度，也不要让 sizeHint 成为性能瓶颈。

5. 超大表格的缓存方案：10万行不卡的落地细节

5.1 懒加载与行缓存

到这里，模型/视图、刷新策略、委托绘制都到位了，10 万行纯文本展示一般已经不在话下。但如果你碰到 100 万行甚至更多，还要从数据库、文件里读数据，那就得引入"懒加载"思路了。核心是：视图需要哪一行，模型才去真正读哪一行，读过的行放进缓存供下次直接取。

cpp复制class LazyTableModel : public QAbstractTableModel
{
public:
    int rowCount(const QModelIndex &parent = QModelIndex()) const override
    {
        return parent.isValid() ? 0 : m_totalRows;
    }

    int columnCount(const QModelIndex &parent = QModelIndex()) const override
    {
        return parent.isValid() ? 0 : m_totalColumns;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        if (!index.isValid() || role != Qt::DisplayRole)
            return QVariant();

        const int row = index.row();
        if (!m_cache.contains(row))
            m_cache.insert(row, fetchRowFromSource(row));

        return m_cache.value(row).value(index.column());
    }

private:
    QVector<QVariant> fetchRowFromSource(int row) const
    {
        // 这里才真正访问数据库/文件，按 row 读取这一行数据
        return queryRowFromDatabase(row);
    }

    int m_totalRows = 1000000;
    int m_totalColumns = 10;
    mutable QHash<int, QVector<QVariant>> m_cache; // 只缓存被访问过的行
};

这套写法的精髓是：rowCount() 只是告诉视图"我有 100 万行"，但不做任何数据准备。视图滚动到第 999999 行时，data() 才真正去查那一行，查完放进 QHash 缓存。用户如果是逐页往下翻的典型场景，缓存里永远只保存最近访问过的几千行，内存占用非常可控。

如果数据是从数据库来的，强烈建议再加一层"分页查询 + 局部缓存淘汰"。比如只缓存最近 500 行，超过就清理最早的数据，这样内存不会无限增长。我见过不少人在这套模型上翻车，原因是 data() 里直接查 SQL，视图快速滚动时瞬间发了几百条查询，卡得比全量加载还严重。解决办法是缓存命中优先，查询结果必须先进缓存。

5.2 行高、列宽、样式这些看似无关的优化

很多新手只盯着模型和委托，忽略了表格自身的属性设置，结果优化半天没效果。有几个"看起来不起眼、实际上影响巨大"的设置，我再啰嗦一遍。

setUniformRowHeights(true) 之前提过，这里要再强调一次。统一行高时，视图可以用纯数学计算定位行；不统一时，它得逐个测量。前者是 O(1)，后者退化成 O(n)，数据量大时直接决定滚动是否顺滑。如果你需要某几行特殊高度，建议用多个视图或分区域处理，别让所有行都背上"可能变高"的包袱。

setVerticalScrollMode(QAbstractItemView::ScrollPerPixel) 也值得留意。默认的 ScrollPerItem 是按"行"滚动，视觉上是一格一格跳；改成像素级滚动后，配合固定行高，体验会自然很多。代价是绘制频率更高，但统一行高下这个代价在可接受范围内。

还有 QSS 样式。给 QTableView::item 写复杂样式（比如圆角、渐变背景、自定义 border-radius）会让每个单元格的绘制代价大幅上升。表格数据量一般超过几千行，我就建议把复杂的单元格样式换成委托里用纯色绘制，或者只在表头保留样式。样式的花哨程度和表格的数据量，天生就是一对矛盾，取舍清楚才能跑得又稳又好看。

6. 实测数据与常见问题速查

6.1 一组能拿来当说服力的实测对比

光说不练假把式。我在自己的机器上（Qt 5.15.2，8GB 内存，Windows 10）做了一个简单对比，数据是 10 列字符串，你拿这个结果去评估自己的方案会有个参照：

要在意的是量级关系，不是具体数值。第一行的关键在于创建了几十万个 QTableWidgetItem 对象，每个都有独立开销；第二行把数据放到连续内存里，视图按需访问；第三行连"准备数据"都省了，只在视图需要时才去拿。这个对比基本能说服团队里主张"再用用 QTableWidget 试试"的同事了。

6.2 常见问题排查表

把这几年被问得最多的问题整理成一张速查表，遇到症状直接对号入座：

这张表解决的是"现象到原因"的映射，多数问题背后都是这 7 个根因的组合。排查时先看数据量，再看用的是哪套接口，基本就能锁定方向。

6.3 我自己踩过的几个坑

最后分享几个实战里真实踩过的坑，都是文档里不会写那么细的地方。

第一个坑是 dataChanged 的 roles 参数。在 Qt 5 里它支持传角色列表，但如果你的模型同时返回了 Qt::DisplayRole 和 Qt::ToolTipRole，更新时只传了 Qt::DisplayRole，提示文本可能还是旧值。别问我怎么知道的，用户拿鼠标悬停看到过期提示时，那个画面很尴尬。更新数据的时候，把可能受影响的所有 role 都列进去。

第二个坑是懒加载模型里的 const 函数。data() 是 const 的，但缓存要修改，所以 QHash 缓存必须声明成 mutable。我见过同事为了绕过 const 限制，把缓存做完成员变量然后写了个 const_cast，结果数据竞争导致偶发崩溃。记住 mutable 才是正确姿势。

第三个坑是列宽自动调整。用 QHeaderView::ResizeToContents 看起来很方便，表格会按内容自动调整列宽，但这意味着每次数据变化都要重新测量所有列的所有行。数据一大，这个设置就是性能灾难。我的习惯是：数据量超过 1000 行就改用 Stretch 或者 Fixed，把精确测量留给少数关键列。

第四个坑和滚动范围有关。如果模型的行数是海量，视图默认的滚动条范围计算是用 int 的，极端情况下可能溢出。这时候要给水平滚动条设置一个合理的范围：view->horizontalScrollBar()->setRange(0, 100000) 之类的，别让视图自己傻算。这个问题在普通项目里遇不到，但真遇到了会非常隐蔽。

我从第一次写 QTableWidget 到现在，最大的体会是：表格优化的核心从来不是"哪个类更快"这种单项对比，而是理解数据、绘制、刷新这三条线怎么协同。数据尽量按需提供，绘制尽量只画可见区，刷新尽量发最小粒度的通知，这三条做到位，你的 Qt 表格想卡都难。希望这篇能把你的表格从"能跑"带到"能扛"，剩下的就是在实际项目里多压一压边界，坑踩多了，手感自然就有了。