QC++ / Qt 学习之路

自定义 Model 实战

从零实现可编辑表格模型,并用委托定制渲染与编辑控件

进阶第 27 / 48 章第四篇 · Qt 进阶

#什么时候必须自己写模型

QStandardItemModel 很方便,但它为每条数据创建了一个 QStandardItem 对象——一个 100 万行的表格意味着 100 万个 C++ 对象,外加它们各自的信号连接与内存分配。当你的数据已经存在于别处(数据库结果集、内存中的 QVector<Record>、硬件采集的环形缓冲区、网络流),再拷贝一份进 QStandardItemModel 就是纯粹的浪费,还会带来"两份数据谁才是真的"这个永无止境的同步问题。

自己写模型的三个信号:

  1. 数据量大(上万行以上),不愿意付 QStandardItem 的对象开销;
  2. 数据已有权威来源,不想维护副本;
  3. 需要特殊的编辑行为、懒加载、分页、虚拟节点等。

继承 QAbstractTableModel,模型只是真实数据的一层适配器,不拥有数据。

#骨架:必须实现的五个函数

下面是一个完整的"联系人表"模型,数据存在 QVector<Contact> 里。先看头文件:

C++
// contactmodel.h
#pragma once
#include <QAbstractTableModel>
#include <QVector>
#include <QString>

struct Contact {
    QString name;
    QString phone;
    int     age = 0;
    bool    vip = false;
};

class ContactModel : public QAbstractTableModel
{
    Q_OBJECT
public:
    explicit ContactModel(QObject *parent = nullptr);

    int rowCount(const QModelIndex &parent = QModelIndex()) const override;
    int columnCount(const QModelIndex &parent = QModelIndex()) const override;
    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
    QVariant headerData(int section, Qt::Orientation orientation,
                        int role = Qt::DisplayRole) const override;
    Qt::ItemFlags flags(const QModelIndex &index) const override;
    bool setData(const QModelIndex &index, const QVariant &value,
                 int role = Qt::EditRole) override;

    bool insertRows(int row, int count,
                    const QModelIndex &parent = QModelIndex()) override;
    bool removeRows(int row, int count,
                    const QModelIndex &parent = QModelIndex()) override;

    const QVector<Contact> &contacts() const { return m_data; }

private:
    QVector<Contact> m_data;
};

实现文件里最需要注意的,是每个可能改变结构的操作都必须用 beginXxx() / endXxx() 包起来。这对函数不是可有可无的装饰:它们负责在修改前后发出 rowsAboutToBeInserted() 和 rowsInserted() 信号,视图、代理模型、选择模型全靠这对信号来维持内部状态的一致性。漏掉它们,轻则视图不刷新,重则在删除时因为索引错位而崩溃。

C++
// contactmodel.cpp
#include "contactmodel.h"

ContactModel::ContactModel(QObject *parent) : QAbstractTableModel(parent) {}

int ContactModel::rowCount(const QModelIndex &) const
{
    return m_data.size();          // 列表/表格模型:parent 无效,直接忽略
}

int ContactModel::columnCount(const QModelIndex &) const
{
    return 4;                      // 姓名 / 电话 / 年龄 / VIP
}

QVariant ContactModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid() || index.row() >= m_data.size()) {
        return {};
    }
    const Contact &c = m_data.at(index.row());

    switch (index.column()) {
    case 0:
        if (role == Qt::DisplayRole) return c.name;
        break;
    case 1:
        if (role == Qt::DisplayRole) return c.phone;
        break;
    case 2:
        if (role == Qt::DisplayRole || role == Qt::EditRole) return c.age;
        if (role == Qt::TextAlignmentRole) return int(Qt::AlignCenter);
        break;
    case 3:
        if (role == Qt::CheckStateRole)
            return c.vip ? Qt::Checked : Qt::Unchecked;
        if (role == Qt::DisplayRole) return c.vip ? "是" : "否";
        break;
    }
    // 悬停提示:任何列都提供
    if (role == Qt::ToolTipRole)
        return QString("%1 · %2 岁").arg(c.name).arg(c.age);
    return {};
}

QVariant ContactModel::headerData(int section, Qt::Orientation orientation, int role) const
{
    if (role != Qt::DisplayRole || orientation != Qt::Horizontal) {
        return QAbstractTableModel::headerData(section, orientation, role);
    }
    static const char *headers[] = {"姓名", "电话", "年龄", "VIP"};
    return section >= 0 && section < 4 ? QString(headers[section]) : QVariant{};
}

Qt::ItemFlags ContactModel::flags(const QModelIndex &index) const
{
    if (!index.isValid()) {
        return Qt::NoItemFlags;
    }
    Qt::ItemFlags f = QAbstractTableModel::flags(index);
    if (index.column() != 3) {
        f |= Qt::ItemIsEditable;              // 前三列可编辑
    } else {
        f |= Qt::ItemIsUserCheckable;         // 第四列是复选框
    }
    return f;
}

data() 里的防御性检查不是多余的:视图可能在模型重置的瞬间用旧索引来查询,此时 index.row() 可能已经越界。返回空 QVariant 是最安全的处理方式。

flags() 决定交互能力。Qt::ItemIsEditable 让双击可以编辑,Qt::ItemIsUserCheckable 让 Qt::CheckStateRole 生效。如果某一列显示但不可改,就不要加 ItemIsEditable——这比在 setData() 里默默拒绝要清晰得多。

#编辑:setData 与 dataChanged

setData() 必须返回是否真的改了。返回 true 时必须发出 dataChanged(index, index, {role})——第三个参数指定哪些角色变了,视图据此决定是否需要重排、重绘。省略角色列表(传空 QVector<int>{})会导致视图做最保守的全量刷新,拖慢性能。

C++
#include <QRegularExpression>

bool ContactModel::setData(const QModelIndex &index, const QVariant &value, int role)
{
    if (!index.isValid() || index.row() >= m_data.size()) {
        return false;
    }
    Contact &c = m_data[index.row()];

    if (index.column() == 3 && role == Qt::CheckStateRole) {
        c.vip = (value.toInt() == Qt::Checked);
        emit dataChanged(index, index, {Qt::CheckStateRole, Qt::DisplayRole});
        return true;
    }

    if (role != Qt::EditRole) {
        return false;                          // 只处理编辑角色
    }

    switch (index.column()) {
    case 0: {
        QString name = value.toString().trimmed();
        if (name.isEmpty()) {
            return false;                      // 校验失败:拒绝写入,单元格恢复原值
        }
        c.name = name;
        break;
    }
    case 1: {
        QString phone = value.toString().trimmed();
        static const QRegularExpression re(R"(^1[3-9]\d{9}$)");
        if (!re.match(phone).hasMatch()) {
            return false;                      // 手机号格式不合法
        }
        c.phone = phone;
        break;
    }
    case 2: {
        bool ok = false;
        int age = value.toInt(&ok);
        if (!ok || age < 0 || age > 150) {
            return false;
        }
        c.age = age;
        break;
    }
    default:
        return false;
    }

    emit dataChanged(index, index, {Qt::DisplayRole});
    return true;
}

这里体现了 Model/View 的一个设计哲学:模型负责业务校验,委托负责交互呈现。当 setData() 返回 false,委托会自动关闭编辑器且不写入,用户看到单元格"弹回原值"。这比弹一个 QMessageBox 打断用户输入更友好;如果需要强提示,可以额外发一个自定义信号让界面显示状态栏消息。

#增删行:beginInsertRows / endInsertRows

这对函数必须紧贴实际的容器修改,中间不能有任何可能触发视图查询的代码:

C++
bool ContactModel::insertRows(int row, int count, const QModelIndex &parent)
{
    if (row < 0 || row > m_data.size() || count <= 0) {
        return false;
    }
    beginInsertRows(parent, row, row + count - 1);   // 先宣告范围
    for (int i = 0; i < count; ++i) {
        m_data.insert(row, Contact{});               // 再改容器
    }
    endInsertRows();                                 // 最后发信号
    return true;
}

bool ContactModel::removeRows(int row, int count, const QModelIndex &parent)
{
    if (row < 0 || count <= 0 || row + count > m_data.size()) {
        return false;
    }
    beginRemoveRows(parent, row, row + count - 1);
    m_data.remove(row, count);
    endRemoveRows();
    return true;
}

beginInsertRows(parent, first, last) 的三个参数要理解清楚:parent 是父节点索引(表格模型传无效索引),first/last 是插入后这些新行将占据的行号区间,且必须连续。循环插入时若每次都 insert(row, ...),count 行的顺序会反——这里因为都是空对象无所谓,插入有数据的行时要留意顺序,或直接 m_data.insert(row + i, item)。

操作包裹函数
插入行beginInsertRows / endInsertRows
删除行beginRemoveRows / endRemoveRows
移动行beginMoveRows / endMoveRows
插入列beginInsertColumns / endInsertColumns
整体重置beginResetModel / endResetModel

beginResetModel() 是"核选项":它告诉视图一切都变了,请丢弃所有缓存、重置滚动位置、清空选中。代价很大(视图状态全丢),只在数据结构整体替换时使用;日常增删改绝不能用它。

#委托:自定义渲染与编辑控件

委托(QStyledItemDelegate)管两件事:paint() 画什么、createEditor() 用什么编辑。默认委托已经处理了文本、图标、复选框,你要介入的通常是特殊显示(进度条、星级、色块)或特殊编辑器(下拉框、日期选择器、滑块)。

下面这个委托把"评分"列画成星星,并提供 QSpinBox 作为编辑器:

C++
// starratingdelegate.h
#pragma once
#include <QStyledItemDelegate>

class StarRatingDelegate : public QStyledItemDelegate
{
    Q_OBJECT
public:
    explicit StarRatingDelegate(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;

    QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,
                          const QModelIndex &index) const override;
    void setEditorData(QWidget *editor, const QModelIndex &index) const override;
    void setModelData(QWidget *editor, QAbstractItemModel *model,
                      const QModelIndex &index) const override;
};
C++
// starratingdelegate.cpp
#include "starratingdelegate.h"
#include <QPainter>
#include <QSpinBox>
#include <QApplication>
#include <QPolygonF>
#include <cmath>

StarRatingDelegate::StarRatingDelegate(QObject *parent) : QStyledItemDelegate(parent) {}

void StarRatingDelegate::paint(QPainter *painter,
                               const QStyleOptionViewItem &option,
                               const QModelIndex &index) const
{
    // 1) 先让基类画好背景、选中高亮、焦点框
    QStyleOptionViewItem opt(option);
    initStyleOption(&opt, index);
    opt.text.clear();                       // 我们不显示文字
    QApplication::style()->drawControl(QStyle::CE_ItemViewItem, &opt, painter);

    int score = index.data(Qt::DisplayRole).toInt();
    painter->save();
    painter->setRenderHint(QPainter::Antialiasing);
    painter->translate(option.rect.topLeft());

    for (int i = 0; i < 5; ++i) {
        painter->setPen(Qt::NoPen);
        painter->setBrush(i < score ? QColor("#f5a623") : QColor("#d8d8d8"));
        // 用 drawPolygon 画一颗星
        QPolygonF star;
        for (int k = 0; k < 10; ++k) {
            double r = (k % 2 == 0) ? 6.0 : 2.8;
            double a = M_PI / 5 * k - M_PI / 2;
            star << QPointF(10 + i * 16 + r * std::cos(a), 10 + r * std::sin(a));
        }
        painter->drawPolygon(star);
    }
    painter->restore();
}

QSize StarRatingDelegate::sizeHint(const QStyleOptionViewItem &,
                                   const QModelIndex &) const
{
    return {5 * 16, 20};
}

QWidget *StarRatingDelegate::createEditor(QWidget *parent,
                                          const QStyleOptionViewItem &,
                                          const QModelIndex &) const
{
    auto *spin = new QSpinBox(parent);
    spin->setRange(0, 5);
    spin->setSuffix(" 星");
    return spin;
}

void StarRatingDelegate::setEditorData(QWidget *editor, const QModelIndex &index) const
{
    auto *spin = qobject_cast<QSpinBox *>(editor);
    if (spin) {
        spin->setValue(index.data(Qt::EditRole).toInt());
    }
}

void StarRatingDelegate::setModelData(QWidget *editor, QAbstractItemModel *model,
                                      const QModelIndex &index) const
{
    auto *spin = qobject_cast<QSpinBox *>(editor);
    if (spin) {
        spin->interpretText();               // 确保读取到界面上的最新文本
        model->setData(index, spin->value(), Qt::EditRole);
    }
}

paint() 里最重要的一行是先调用基类风格的 drawControl。很多手写委托的界面看起来"不像原生"——选中行的高亮色不对、鼠标悬停没反馈、禁用状态没有灰化——根源就是跳过了这一步,自己刷了背景。正确做法是让 QStyle 画好标准背景,再在上面叠加你的自定义内容。

#委托的四个钩子

函数时机必做
paint()每次绘制单元格先画标准背景,再画自定义
sizeHint()计算行高列宽返回你的内容尺寸
createEditor()开始编辑返回编辑器控件
setEditorData() / setModelData()编辑前后模型 ↔ 控件 数据搬运

#组装与性能提示

C++
#include <QApplication>
#include <QTableView>
#include <QHeaderView>
#include <QPushButton>
#include <QVBoxLayout>
#include <QWidget>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    auto *model = new ContactModel(&app);
    model->insertRows(0, 3);
    model->setData(model->index(0, 0), "张三");
    model->setData(model->index(0, 1), "13800138000");
    model->setData(model->index(0, 2), 28);

    auto *view = new QTableView();
    view->setModel(model);
    view->setItemDelegateForColumn(2, new StarRatingDelegate(view)); // 指定列用委托
    view->horizontalHeader()->setSectionResizeMode(QHeaderView::ResizeToContents);
    view->verticalHeader()->setDefaultSectionSize(24);

    auto *addBtn = new QPushButton("添加一行");
    QObject::connect(addBtn, &QPushButton::clicked, view, [model, view] {
        int row = model->rowCount();
        model->insertRows(row, 1);
        view->edit(model->index(row, 0));       // 自动进入编辑
    });

    auto *delBtn = new QPushButton("删除选中行");
    QObject::connect(delBtn, &QPushButton::clicked, view, [model, view] {
        QModelIndex cur = view->currentIndex();
        if (cur.isValid()) {
            model->removeRows(cur.row(), 1);
        }
    });

    auto *w = new QWidget();
    auto *lay = new QVBoxLayout(w);
    lay->addWidget(view);
    lay->addWidget(addBtn);
    lay->addWidget(delBtn);
    w->resize(520, 360);
    w->show();

    return app.exec();
}

setItemDelegateForColumn() / setItemDelegateForRow() 让你只对特定列应用委托,比整表替换高效且安全。

#大模型的性能清单

优化点做法
data() 要快它每秒被调用成百上千次,避免其中做 IO、加锁、正则匹配;结果缓存
精确发 dataChanged指定具体角色,避免视图全量重排
批量插入一次 beginInsertRows(0, 0, 999) 优于 1000 次单行插入
均匀行高view->verticalHeader()->setUniformItemSizes(true) 或 setSectionResizeMode(Fixed)
懒加载canFetchMore() / fetchMore() 分页加载
别用 resetModel改用细粒度的插入/删除信号

data() 的性能是第一位的。视图在滚动时对每个可见单元格调用它多次(不同 role),10 行 × 5 列 × 3 个角色就是 150 次调用。任何在里面放 QFile::readAll() 或数据库查询的写法都会让界面卡死。

Qt 5 提示:Qt 6 的 dataChanged 第三个参数是 QList<int>,Qt 5 是 QVector<int>,两者都可用初始化列表 {} 书写,代码兼容。此外 Qt 6 移除了 QStyleOptionViewItemV4 等版本化类型,统一使用 QStyleOptionViewItem。

#小结

  1. 数据已有权威来源或量大时,应继承 QAbstractTableModel 做适配器,而不是复制进 QStandardItemModel。
  2. 结构变更必须用 beginInsertRows/endInsertRows 等成对函数包裹,否则视图状态错乱。
  3. setData() 承担业务校验,返回 false 即拒绝修改;成功时要发 dataChanged 并指定变更角色。
  4. 委托的四个钩子是 paint、sizeHint、createEditor、setEditorData/setModelData;paint() 必须先画标准背景。
  5. data() 是性能热点,任何 IO、加锁、正则都应移出;批量变更优于逐行变更。

#练习

  1. 给 ContactModel 增加 QVariant headerData() 的垂直表头(显示行号)与 Qt::DecorationRole(姓名列前显示头像图标)。
  2. 实现 insertColumns() / removeColumns(),让表格能动态增删列(提示:同样需要 beginInsertColumns/endInsertColumns)。
  3. 编写一个"进度条委托",把 0~100 的整数渲染成 QStyle 风格的进度条,并提供 QSlider 编辑器。
  4. 为一个 100 万行的模型实现 canFetchMore() / fetchMore() 分页加载,用 QElapsedTimer 对比"全量加载"与"懒加载"的启动耗时。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。