自定义 Model 实战
从零实现可编辑表格模型,并用委托定制渲染与编辑控件
#什么时候必须自己写模型
QStandardItemModel 很方便,但它为每条数据创建了一个 QStandardItem 对象——一个 100 万行的表格意味着 100 万个 C++ 对象,外加它们各自的信号连接与内存分配。当你的数据已经存在于别处(数据库结果集、内存中的 QVector<Record>、硬件采集的环形缓冲区、网络流),再拷贝一份进 QStandardItemModel 就是纯粹的浪费,还会带来"两份数据谁才是真的"这个永无止境的同步问题。
自己写模型的三个信号:
- 数据量大(上万行以上),不愿意付
QStandardItem的对象开销; - 数据已有权威来源,不想维护副本;
- 需要特殊的编辑行为、懒加载、分页、虚拟节点等。
继承 QAbstractTableModel,模型只是真实数据的一层适配器,不拥有数据。
#骨架:必须实现的五个函数
下面是一个完整的"联系人表"模型,数据存在 QVector<Contact> 里。先看头文件:
// 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() 信号,视图、代理模型、选择模型全靠这对信号来维持内部状态的一致性。漏掉它们,轻则视图不刷新,重则在删除时因为索引错位而崩溃。
// 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>{})会导致视图做最保守的全量刷新,拖慢性能。
#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
这对函数必须紧贴实际的容器修改,中间不能有任何可能触发视图查询的代码:
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 作为编辑器:
// 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;
};// 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() | 编辑前后 | 模型 ↔ 控件 数据搬运 |
#组装与性能提示
#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。
#小结
- 数据已有权威来源或量大时,应继承
QAbstractTableModel做适配器,而不是复制进QStandardItemModel。 - 结构变更必须用
beginInsertRows/endInsertRows等成对函数包裹,否则视图状态错乱。 setData()承担业务校验,返回false即拒绝修改;成功时要发dataChanged并指定变更角色。- 委托的四个钩子是
paint、sizeHint、createEditor、setEditorData/setModelData;paint()必须先画标准背景。 data()是性能热点,任何 IO、加锁、正则都应移出;批量变更优于逐行变更。
#练习
- 给
ContactModel增加QVariant headerData()的垂直表头(显示行号)与Qt::DecorationRole(姓名列前显示头像图标)。 - 实现
insertColumns()/removeColumns(),让表格能动态增删列(提示:同样需要beginInsertColumns/endInsertColumns)。 - 编写一个"进度条委托",把 0~100 的整数渲染成
QStyle风格的进度条,并提供QSlider编辑器。 - 为一个 100 万行的模型实现
canFetchMore()/fetchMore()分页加载,用QElapsedTimer对比"全量加载"与"懒加载"的启动耗时。