案例:Todo 待办清单(Model/View 实战)
自定义 Model 与委托绘制待办项,增删改查并持久化到 JSON
#这个案例做什么
写一个能真正管住日常事务的待办清单:顶部一行输入框敲下回车就新增一条,列表里每条待办有复选框、优先级彩色标签和截止时间,点击复选框即完成,可以编辑、删除、按状态筛选、按优先级排序,所有数据退出时自动存成 JSON,下次启动原样恢复,连窗口大小和列宽都记得。更重要的是,这个案例把"数据"和"显示"彻底分开——模型只管数据,委托只管画,视图只管滚动和选中,任何一处改动都不会牵连其他部分,这是 Qt Model/View 架构最值得体会的地方。
功能清单:
- 新增待办:输入标题 + 选择优先级(高/中/低)+ 可选的截止时间;
- 勾选完成:点击复选框切换状态,已完成项标题自动加删除线并变灰;
- 编辑与删除:双击标题就地编辑,
Delete键或工具栏删除选中项,一键清除全部已完成; - 筛选与排序:
QSortFilterProxyModel提供"全部 / 未完成 / 已完成"三种过滤,按优先级、截止时间排序; - 持久化:退出时写入
~/.config下的 JSON 文件,启动时读回; - 界面状态:
QSettings记住窗口几何、QSplitter比例与筛选条件; - 状态栏实时显示总数、已完成数与逾期数。
#用到的知识点
| 知识点 | 出处 |
|---|---|
QAbstractListModel 自定义模型 | 第四篇第 3 章 自定义 Model 实战 |
| Model/View 架构、模型索引与角色 | 第四篇第 2 章 Model/View 架构 |
QStyledItemDelegate 自定义委托、editorEvent | 第四篇第 2、4 章 |
QSortFilterProxyModel 排序与过滤 | 第四篇第 2 章 Model/View 架构 |
QPainter 绘制复选框、圆角标签 | 第四篇第 5 章 绘图系统 QPainter |
QJsonDocument / QJsonArray 序列化 | 第四篇第 6 章 文件与数据持久化 |
QSettings / QStandardPaths | 第四篇第 6 章 文件与数据持久化 |
QListView、QLineEdit、QComboBox 等控件 | 第三篇第 6 章 常用基础控件 |
布局管理与 QMainWindow 框架 | 第三篇第 7、8 章 |
QVector / 隐式共享与 Q_DECLARE_METATYPE | 第三篇第 5 章 Qt 核心数据类型 |
#项目结构
todo/
├── CMakeLists.txt
└── src/
├── main.cpp
├── todoitem.h # 纯数据结构 + 优先级枚举
├── todomodel.h
├── todomodel.cpp # QAbstractListModel 子类
├── statusfilter.h
├── statusfilter.cpp # 按状态过滤的代理模型
├── tododelegate.h
├── tododelegate.cpp # 自绘复选框、优先级标签
├── mainwindow.h
└── mainwindow.cpp # 界面组装、JSON 存取、QSettings数据流向是单向的:MainWindow 把用户输入交给 TodoModel,模型内部 beginInsertRows 通知视图,视图通过 TodoDelegate 把每个索引画出来;任何展示形态的修改(换皮肤、换布局)都不需要碰数据层。
cmake_minimum_required(VERSION 3.16)
project(Todo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_add_executable(Todo
src/main.cpp
src/todomodel.cpp
src/todomodel.h
src/statusfilter.cpp
src/statusfilter.h
src/tododelegate.cpp
src/tododelegate.h
src/mainwindow.cpp
src/mainwindow.h
src/todoitem.h
)
target_link_libraries(Todo PRIVATE Qt6::Widgets)
if(MSVC)
target_compile_options(Todo PRIVATE /utf-8)
endif()#核心实现
#数据项与 Model:一份数据多种角色
TodoItem 是不含任何 Qt 元对象逻辑的纯结构,方便序列化与单测。TodoModel 继承 QAbstractListModel,只为一条数据提供多种角色:Qt::DisplayRole 给标题,Qt::CheckStateRole 给完成状态,Qt::DecorationRole 不需要(交给委托画),自定义角色给优先级和截止时间。视图请求什么,模型就按角色返回什么。
最关键的纪律是:任何会改变行数或行内内容的操作,都必须用 beginXxx/endXxx 包起来。少了这对括号,视图的选中状态、滚动位置、代理模型的行映射全部会错乱,表现为"删了一条结果刷新出两条"这类诡异 bug。
// src/todoitem.h
#pragma once
#include <QDateTime>
#include <QString>
enum class Priority { Low = 0, Normal = 1, High = 2 };
struct TodoItem
{
QString title;
bool done = false;
Priority priority = Priority::Normal;
QDateTime created = QDateTime::currentDateTime();
QDateTime due; // 无效值表示没有截止时间
bool isOverdue() const
{
return !done && due.isValid() && due < QDateTime::currentDateTime();
}
static QString priorityText(Priority p)
{
switch (p) {
case Priority::High: return QStringLiteral("高");
case Priority::Normal: return QStringLiteral("中");
case Priority::Low: return QStringLiteral("低");
}
return QStringLiteral("中");
}
static QColor priorityColor(Priority p)
{
switch (p) {
case Priority::High: return QColor(214, 69, 65);
case Priority::Normal: return QColor(58, 138, 198);
case Priority::Low: return QColor(120, 145, 120);
}
return QColor(120, 145, 120);
}
};// src/todomodel.h
#pragma once
#include <QAbstractListModel>
#include <QVector>
#include "todoitem.h"
class TodoModel : public QAbstractListModel
{
Q_OBJECT
public:
// 自定义角色一律从 Qt::UserRole + 1 开始,不要占用 Qt 保留值
enum Role {
PriorityRole = Qt::UserRole + 1,
DueRole,
OverdueRole,
CreatedRole
};
explicit TodoModel(QObject *parent = nullptr);
int rowCount(const QModelIndex &parent = QModelIndex()) const override;
QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
bool setData(const QModelIndex &index, const QVariant &value,
int role = Qt::EditRole) override;
Qt::ItemFlags flags(const QModelIndex &index) const override;
void addItem(const TodoItem &item);
void removeItem(int row);
void removeRows_(const QList<int> &rows); // 逆序批量删除
int clearDone(); // 返回清除的条数
void setItems(const QVector<TodoItem> &items);
QVector<TodoItem> items() const { return m_items; }
int totalCount() const { return m_items.size(); }
int doneCount() const;
int overdueCount() const;
signals:
void statsChanged(); // 任意增删改后发出,驱动状态栏
private:
QVector<TodoItem> m_items;
};// src/todomodel.cpp
#include "todomodel.h"
TodoModel::TodoModel(QObject *parent) : QAbstractListModel(parent) {}
int TodoModel::rowCount(const QModelIndex &parent) const
{
// 列表模型没有子层级,parent 有效时必须返回 0
return parent.isValid() ? 0 : m_items.size();
}
QVariant TodoModel::data(const QModelIndex &index, int role) const
{
if (!index.isValid() || index.row() >= m_items.size())
return {};
const TodoItem &item = m_items.at(index.row());
switch (role) {
case Qt::DisplayRole:
case Qt::EditRole:
return item.title;
case Qt::CheckStateRole:
return item.done ? Qt::Checked : Qt::Unchecked;
case Qt::ToolTipRole:
return item.due.isValid()
? QStringLiteral("截止:%1").arg(item.due.toString(QStringLiteral("yyyy-MM-dd HH:mm")))
: QStringLiteral("无截止时间");
case Qt::ForegroundRole:
return item.done ? QColor(130, 130, 135) : QColor(30, 30, 34);
case PriorityRole:
return int(item.priority);
case DueRole:
return item.due;
case OverdueRole:
return item.isOverdue();
case CreatedRole:
return item.created;
case Qt::SizeHintRole:
return QSize(0, 44);
}
return {};
}
bool TodoModel::setData(const QModelIndex &index, const QVariant &value, int role)
{
if (!index.isValid() || index.row() >= m_items.size())
return false;
TodoItem &item = m_items[index.row()];
switch (role) {
case Qt::CheckStateRole:
item.done = (value.toInt() == Qt::Checked);
break;
case Qt::EditRole:
item.title = value.toString().trimmed();
if (item.title.isEmpty()) return false;
break;
case PriorityRole:
item.priority = static_cast<Priority>(value.toInt());
break;
case DueRole:
item.due = value.toDateTime();
break;
default:
return false;
}
emit dataChanged(index, index, { role, Qt::DisplayRole, Qt::ForegroundRole });
emit statsChanged();
return true;
}
Qt::ItemFlags TodoModel::flags(const QModelIndex &index) const
{
if (!index.isValid()) return Qt::NoItemFlags;
// 可选中 + 可编辑 + 可勾选,三者缺一就无法双击改名或点击复选框
return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable
| Qt::ItemIsUserCheckable;
}
void TodoModel::addItem(const TodoItem &item)
{
const int row = m_items.size();
beginInsertRows(QModelIndex(), row, row);
m_items.append(item);
endInsertRows();
emit statsChanged();
}
void TodoModel::removeItem(int row)
{
if (row < 0 || row >= m_items.size()) return;
beginRemoveRows(QModelIndex(), row, row);
m_items.removeAt(row);
endRemoveRows();
emit statsChanged();
}
void TodoModel::removeRows_(const QList<int> &rows)
{
// 必须从大到小删,否则前面的删除会让后面的行号失效
QList<int> sorted = rows;
std::sort(sorted.begin(), sorted.end(), std::greater<int>());
for (int row : std::as_const(sorted))
removeItem(row);
}
int TodoModel::clearDone()
{
QList<int> rows;
for (int i = 0; i < m_items.size(); ++i)
if (m_items.at(i).done) rows << i;
removeRows_(rows);
return rows.size();
}
void TodoModel::setItems(const QVector<TodoItem> &items)
{
beginResetModel();
m_items = items;
endResetModel();
emit statsChanged();
}
int TodoModel::doneCount() const
{
int n = 0;
for (const TodoItem &item : m_items)
if (item.done) ++n;
return n;
}
int TodoModel::overdueCount() const
{
int n = 0;
for (const TodoItem &item : m_items)
if (item.isOverdue()) ++n;
return n;
}#自定义委托:复选框、优先级标签与命中判定
委托是 Model/View 里唯一负责"像素"的环节。这里要画四样东西:左侧的圆形复选框、优先级彩色标签、可就地编辑的标题、右对齐的截止时间。绘制的顺序就是布局顺序,QPainter 没有自动排版,每个元素的矩形都得自己算。
复选框的点击不通过创建编辑器实现,而是在 editorEvent 里做命中判定:拿到鼠标位置,判断它是否落在我们自己画的复选框矩形内,是就改模型的 CheckStateRole。判定矩形必须和绘制时用的矩形完全一致,所以把它抽成静态函数 checkRect(),绘制和点击共用同一份代码——这是避免"看着能点却点不中"的唯一可靠办法。
// src/tododelegate.h
#pragma once
#include <QRect>
#include <QStyledItemDelegate>
class TodoDelegate : public QStyledItemDelegate
{
Q_OBJECT
public:
explicit TodoDelegate(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;
bool editorEvent(QEvent *event, QAbstractItemModel *model,
const QStyleOptionViewItem &option,
const QModelIndex &index) override;
private:
static QRect checkRect(const QStyleOptionViewItem &option);
static QRect tagRect(const QStyleOptionViewItem &option);
};// src/tododelegate.cpp
#include "tododelegate.h"
#include <QApplication>
#include <QDateTime>
#include <QMouseEvent>
#include <QPainter>
#include "todomodel.h"
namespace {
constexpr int kMargin = 10;
constexpr int kCheckSize = 18;
constexpr int kTagWidth = 26;
}
QRect TodoDelegate::checkRect(const QStyleOptionViewItem &option)
{
return QRect(option.rect.left() + kMargin,
option.rect.center().y() - kCheckSize / 2,
kCheckSize, kCheckSize);
}
QRect TodoDelegate::tagRect(const QStyleOptionViewItem &option)
{
return QRect(option.rect.left() + kMargin + kCheckSize + 8,
option.rect.center().y() - 9,
kTagWidth, 18);
}
TodoDelegate::TodoDelegate(QObject *parent) : QStyledItemDelegate(parent) {}
QSize TodoDelegate::sizeHint(const QStyleOptionViewItem &, const QModelIndex &) const
{
return QSize(320, 44);
}
void TodoDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option,
const QModelIndex &index) const
{
const bool done = index.data(Qt::CheckStateRole).toInt() == Qt::Checked;
const bool overdue = index.data(TodoModel::OverdueRole).toBool();
const bool selected = option.state & QStyle::State_Selected;
const auto priority = static_cast<Priority>(index.data(TodoModel::PriorityRole).toInt());
const QString title = index.data(Qt::DisplayRole).toString();
const QDateTime due = index.data(TodoModel::DueRole).toDateTime();
painter->save();
painter->setRenderHint(QPainter::Antialiasing, true);
painter->setRenderHint(QPainter::TextAntialiasing, true);
// 1. 背景:选中态自己画,避免不同平台上默认高亮色刺眼
if (selected)
painter->fillRect(option.rect, QColor(58, 122, 197, 45));
else if (option.state & QStyle::State_MouseOver)
painter->fillRect(option.rect, QColor(127, 127, 127, 20));
// 2. 复选框:空心圆 + 勾选后填充并画对勾
const QRect cr = checkRect(option);
QPen pen(done ? TodoItem::priorityColor(priority) : QColor(150, 150, 158), 1.6);
painter->setPen(pen);
if (done)
painter->setBrush(TodoItem::priorityColor(priority));
else
painter->setBrush(Qt::NoBrush);
painter->drawEllipse(cr);
if (done) {
painter->setPen(QPen(Qt::white, 2.0, Qt::SolidLine, Qt::RoundCap, Qt::RoundJoin));
const QPointF a(cr.left() + 4.5, cr.center().y() + 0.5);
const QPointF b(cr.center().x() - 0.5, cr.bottom() - 5.0);
const QPointF c(cr.right() - 4.5, cr.top() + 5.0);
painter->drawPolyline(QVector<QPointF>{ a, b, c });
}
// 3. 优先级标签:圆角矩形 + 白字
const QRect tr = tagRect(option);
painter->setPen(Qt::NoPen);
painter->setBrush(TodoItem::priorityColor(priority));
painter->drawRoundedRect(tr, 4, 4);
painter->setPen(Qt::white);
QFont tagFont = option.font;
tagFont.setPointSize(tagFont.pointSize() - 2);
painter->setFont(tagFont);
painter->drawText(tr, Qt::AlignCenter, TodoItem::priorityText(priority));
// 4. 标题:已完成加删除线并置灰
const int textLeft = tr.right() + 10;
const int dueWidth = due.isValid() ? 96 : 0;
const QRect textRect(textLeft, option.rect.top(),
option.rect.right() - textLeft - dueWidth - kMargin,
option.rect.height());
QFont titleFont = option.font;
titleFont.setStrikeOut(done);
painter->setFont(titleFont);
painter->setPen(done ? QColor(140, 140, 145) : QColor(32, 32, 36));
painter->drawText(textRect, Qt::AlignLeft | Qt::AlignVCenter,
painter->fontMetrics().elidedText(title, Qt::ElideRight,
textRect.width()));
// 5. 截止时间:逾期显示红色
if (due.isValid()) {
const QRect dueRect(option.rect.right() - dueWidth - kMargin,
option.rect.top(), dueWidth, option.rect.height());
QFont dueFont = option.font;
dueFont.setPointSize(dueFont.pointSize() - 2);
painter->setFont(dueFont);
painter->setPen(overdue ? QColor(214, 69, 65) : QColor(120, 120, 128));
painter->drawText(dueRect, Qt::AlignRight | Qt::AlignVCenter,
due.toString(QStringLiteral("MM-dd HH:mm")));
}
painter->restore();
}
bool TodoDelegate::editorEvent(QEvent *event, QAbstractItemModel *model,
const QStyleOptionViewItem &option,
const QModelIndex &index)
{
if (event->type() == QEvent::MouseButtonRelease) {
auto *me = static_cast<QMouseEvent *>(event);
// 只有点在复选框里才拦截,点别处放行给视图处理选中/双击编辑
if (me->button() == Qt::LeftButton && checkRect(option).contains(me->pos())) {
const bool done = index.data(Qt::CheckStateRole).toInt() == Qt::Checked;
model->setData(index, done ? Qt::Unchecked : Qt::Checked, Qt::CheckStateRole);
return true;
}
}
if (event->type() == QEvent::KeyPress) {
auto *ke = static_cast<QKeyEvent *>(event);
if (ke->key() == Qt::Key_Space) {
const bool done = index.data(Qt::CheckStateRole).toInt() == Qt::Checked;
model->setData(index, done ? Qt::Unchecked : Qt::Checked, Qt::CheckStateRole);
return true;
}
}
// 双击编辑交给基类的默认流程(会创建 QLineEdit 编辑器)
return QStyledItemDelegate::editorEvent(event, model, option, index);
}#代理模型:过滤与排序
筛选不能改源模型,否则"隐藏已完成"就等于把数据删了。用 QSortFilterProxyModel 子类重写 filterAcceptsRow,按状态标志决定该行是否保留;排序则重写 lessThan,让"高"优先级排在前面、无截止时间的排在最后。
代理模型插在源模型和视图之间,视图拿到的是代理索引。删除时必须用 mapToSource() 把代理索引换算回源模型行号,这是最容易出错的一步。
// src/statusfilter.h
#pragma once
#include <QSortFilterProxyModel>
class StatusFilter : public QSortFilterProxyModel
{
Q_OBJECT
public:
enum Status { All, Active, Done };
explicit StatusFilter(QObject *parent = nullptr);
void setStatus(Status status);
protected:
bool filterAcceptsRow(int sourceRow, const QModelIndex &sourceParent) const override;
bool lessThan(const QModelIndex &left, const QModelIndex &right) const override;
private:
Status m_status = All;
};// src/statusfilter.cpp
#include "statusfilter.h"
#include "todomodel.h"
StatusFilter::StatusFilter(QObject *parent) : QSortFilterProxyModel(parent) {}
void StatusFilter::setStatus(Status status)
{
if (m_status == status) return;
m_status = status;
invalidateFilter(); // 通知代理重新筛选所有行
}
bool StatusFilter::filterAcceptsRow(int sourceRow, const QModelIndex &sourceParent) const
{
const QModelIndex idx = sourceModel()->index(sourceRow, 0, sourceParent);
if (!idx.isValid()) return false;
if (m_status == All) return true;
const bool done = idx.data(Qt::CheckStateRole).toInt() == Qt::Checked;
return (m_status == Done) ? done : !done;
}
bool StatusFilter::lessThan(const QModelIndex &left, const QModelIndex &right) const
{
// 排序键:优先级列按数字倒序(高在前),其余按截止时间升序
if (sortColumn() == 1) {
const int lp = left.data(TodoModel::PriorityRole).toInt();
const int rp = right.data(TodoModel::PriorityRole).toInt();
if (lp != rp) return lp > rp;
}
const QDateTime ld = left.data(TodoModel::DueRole).toDateTime();
const QDateTime rd = right.data(TodoModel::DueRole).toDateTime();
// 没有截止时间的排在最后,而不是被当成"1970 年"排到最前
if (!ld.isValid()) return false;
if (!rd.isValid()) return true;
return ld < rd;
}#持久化与主窗口组装
JSON 比二进制格式的好处是手写也能改、出问题能直接看。QStandardPaths::writableLocation(QStandardPaths::AppConfigLocation) 在三大桌面系统上分别落到 ~/.config/组织名/应用名、~/Library/Application Support、%APPDATA%,一行代码跨平台正确。
写文件要用"先写临时文件再 rename"的原子替换:直接 QFile::write 打开原文件,写到一半崩溃就会留下一半的 JSON,下次启动解析失败、数据全丢。QSaveFile 就是干这件事的。
// src/mainwindow.h
#pragma once
#include <QMainWindow>
#include <QVector>
#include "todoitem.h"
class TodoModel;
class StatusFilter;
class QListView;
class QLineEdit;
class QComboBox;
class QLabel;
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
explicit MainWindow(QWidget *parent = nullptr);
~MainWindow() override;
protected:
void closeEvent(QCloseEvent *event) override;
private:
void buildUi();
void buildActions();
void addFromInput();
void removeSelected();
void clearDone();
void updateStats();
void loadFromDisk();
void saveToDisk() const;
static QString dataPath();
TodoModel *m_model = nullptr;
StatusFilter *m_proxy = nullptr;
QListView *m_list = nullptr;
QLineEdit *m_input = nullptr;
QComboBox *m_priority = nullptr;
QComboBox *m_filter = nullptr;
QLabel *m_stats = nullptr;
};// src/mainwindow.cpp
#include "mainwindow.h"
#include <QCloseEvent>
#include <QComboBox>
#include <QHBoxLayout>
#include <QInputDialog>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QLabel>
#include <QLineEdit>
#include <QListView>
#include <QMessageBox>
#include <QPushButton>
#include <QSaveFile>
#include <QSettings>
#include <QStandardPaths>
#include <QStatusBar>
#include <QToolBar>
#include <QVBoxLayout>
#include "statusfilter.h"
#include "tododelegate.h"
#include "todomodel.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
, m_model(new TodoModel(this))
, m_proxy(new StatusFilter(this))
{
m_proxy->setSourceModel(m_model);
m_proxy->setSortCaseSensitivity(Qt::CaseInsensitive);
buildUi();
buildActions();
loadFromDisk();
// 从磁盘恢复界面状态:几何 + 筛选条件
QSettings settings;
restoreGeometry(settings.value(QStringLiteral("geometry")).toByteArray());
m_filter->setCurrentIndex(settings.value(QStringLiteral("filter"), 0).toInt());
}
MainWindow::~MainWindow() = default;
void MainWindow::buildUi()
{
auto *inputBar = new QWidget(this);
auto *h = new QHBoxLayout(inputBar);
h->setContentsMargins(8, 8, 8, 4);
m_input = new QLineEdit(inputBar);
m_input->setPlaceholderText(QStringLiteral("要做点什么?回车添加"));
m_input->setClearButtonEnabled(true);
m_priority = new QComboBox(inputBar);
m_priority->addItem(QStringLiteral("高"), int(Priority::High));
m_priority->addItem(QStringLiteral("中"), int(Priority::Normal));
m_priority->addItem(QStringLiteral("低"), int(Priority::Low));
m_priority->setCurrentIndex(1);
auto *add = new QPushButton(QStringLiteral("添加"), inputBar);
add->setDefault(true);
h->addWidget(m_input, 1);
h->addWidget(m_priority);
h->addWidget(add);
m_filter = new QComboBox(this);
m_filter->addItem(QStringLiteral("全部"), int(StatusFilter::All));
m_filter->addItem(QStringLiteral("未完成"), int(StatusFilter::Active));
m_filter->addItem(QStringLiteral("已完成"), int(StatusFilter::Done));
m_list = new QListView(this);
m_list->setModel(m_proxy);
m_list->setItemDelegate(new TodoDelegate(m_list));
m_list->setSelectionMode(QAbstractItemView::ExtendedSelection);
m_list->setAlternatingRowColors(false); // 委托自绘背景,交替色会打架
m_list->setUniformItemSizes(true); // 高度一致时视图可以省掉大量测算
m_list->setMouseTracking(true); // 委托需要 State_MouseOver 才能画悬停
auto *central = new QWidget(this);
auto *v = new QVBoxLayout(central);
v->setContentsMargins(0, 0, 0, 0);
v->addWidget(inputBar);
v->addWidget(m_list, 1);
v->addWidget(m_filter);
setCentralWidget(central);
m_stats = new QLabel(this);
statusBar()->addPermanentWidget(m_stats);
connect(add, &QPushButton::clicked, this, &MainWindow::addFromInput);
connect(m_input, &QLineEdit::returnPressed, this, &MainWindow::addFromInput);
connect(m_filter, &QComboBox::currentIndexChanged, this, [this](int i) {
m_proxy->setStatus(static_cast<StatusFilter::Status>(
m_filter->itemData(i).toInt()));
QSettings().setValue(QStringLiteral("filter"), i);
});
connect(m_model, &TodoModel::statsChanged, this, &MainWindow::updateStats);
resize(560, 640);
updateStats();
}
void MainWindow::buildActions()
{
auto *tb = addToolBar(QStringLiteral("操作"));
tb->setMovable(false);
auto *del = new QAction(QStringLiteral("删除"), this);
del->setShortcut(QKeySequence::Delete);
connect(del, &QAction::triggered, this, &MainWindow::removeSelected);
tb->addAction(del);
auto *due = new QAction(QStringLiteral("设置截止时间"), this);
connect(due, &QAction::triggered, this, [this] {
const QModelIndex idx = m_list->currentIndex();
if (!idx.isValid()) return;
const QDateTime old = idx.data(TodoModel::DueRole).toDateTime();
const QString text = QInputDialog::getText(
this, QStringLiteral("截止时间"),
QStringLiteral("格式 yyyy-MM-dd HH:mm,留空表示清除"),
QLineEdit::Normal,
old.isValid() ? old.toString(QStringLiteral("yyyy-MM-dd HH:mm")) : QString());
if (text.simplified().isEmpty()) {
m_model->setData(m_proxy->mapToSource(idx), QDateTime(), TodoModel::DueRole);
return;
}
const QDateTime dt = QDateTime::fromString(text, QStringLiteral("yyyy-MM-dd HH:mm"));
if (!dt.isValid()) {
QMessageBox::warning(this, QStringLiteral("格式不对"),
QStringLiteral("请按 yyyy-MM-dd HH:mm 输入"));
return;
}
m_model->setData(m_proxy->mapToSource(idx), dt, TodoModel::DueRole);
});
tb->addAction(due);
auto *clear = new QAction(QStringLiteral("清除已完成"), this);
connect(clear, &QAction::triggered, this, &MainWindow::clearDone);
tb->addAction(clear);
tb->addSeparator();
auto *sortByPriority = new QAction(QStringLiteral("按优先级排序"), this);
connect(sortByPriority, &QAction::triggered, this, [this] {
m_proxy->sort(1, Qt::AscendingOrder);
});
tb->addAction(sortByPriority);
auto *sortByDue = new QAction(QStringLiteral("按截止时间排序"), this);
connect(sortByDue, &QAction::triggered, this, [this] {
m_proxy->sort(0, Qt::AscendingOrder);
});
tb->addAction(sortByDue);
}
void MainWindow::addFromInput()
{
const QString title = m_input->text().trimmed();
if (title.isEmpty()) return;
TodoItem item;
item.title = title;
item.priority = static_cast<Priority>(m_priority->currentData().toInt());
m_model->addItem(item);
m_input->clear();
// 新增后滚动到末行并选中,连续录入时手不用离开键盘
const QModelIndex last = m_proxy->index(m_proxy->rowCount() - 1, 0);
m_list->setCurrentIndex(last);
m_list->scrollTo(last);
}
void MainWindow::removeSelected()
{
const QModelIndexList sel = m_list->selectionModel()->selectedIndexes();
if (sel.isEmpty()) return;
QList<int> rows;
for (const QModelIndex &proxyIdx : sel)
rows << m_proxy->mapToSource(proxyIdx).row(); // 代理索引 → 源模型行号
// 逆序删除保证行号始终有效
std::sort(rows.begin(), rows.end(), std::greater<int>());
for (int row : std::as_const(rows))
m_model->removeItem(row);
}
void MainWindow::clearDone()
{
const int n = m_model->clearDone();
statusBar()->showMessage(QStringLiteral("已清除 %1 条").arg(n), 3000);
}
void MainWindow::updateStats()
{
m_stats->setText(QStringLiteral("共 %1 条 已完成 %2 逾期 %3")
.arg(m_model->totalCount())
.arg(m_model->doneCount())
.arg(m_model->overdueCount()));
}
QString MainWindow::dataPath()
{
// 三个系统各自的"应用配置目录",不要手写 ~/.config
const QString dir = QStandardPaths::writableLocation(
QStandardPaths::AppConfigLocation);
return dir + QStringLiteral("/todos.json");
}
void MainWindow::loadFromDisk()
{
QFile file(dataPath());
if (!file.open(QIODevice::ReadOnly))
return;
const QJsonDocument doc = QJsonDocument::fromJson(file.readAll());
if (!doc.isObject()) return;
QVector<TodoItem> items;
const QJsonArray arr = doc.object().value(QStringLiteral("items")).toArray();
for (const QJsonValue &v : arr) {
const QJsonObject o = v.toObject();
TodoItem item;
item.title = o.value(QStringLiteral("title")).toString();
item.done = o.value(QStringLiteral("done")).toBool(false);
item.priority = static_cast<Priority>(
o.value(QStringLiteral("priority")).toInt(int(Priority::Normal)));
item.created = QDateTime::fromString(
o.value(QStringLiteral("created")).toString(), Qt::ISODate);
item.due = QDateTime::fromString(
o.value(QStringLiteral("due")).toString(), Qt::ISODate);
if (!item.title.isEmpty())
items.append(item);
}
m_model->setItems(items);
}
void MainWindow::saveToDisk() const
{
QJsonArray arr;
for (const TodoItem &item : m_model->items()) {
QJsonObject o;
o[QStringLiteral("title")] = item.title;
o[QStringLiteral("done")] = item.done;
o[QStringLiteral("priority")] = int(item.priority);
o[QStringLiteral("created")] = item.created.toUTC().toString(Qt::ISODate);
o[QStringLiteral("due")] = item.due.isValid()
? item.due.toUTC().toString(Qt::ISODate) : QString();
arr.append(o); // 空的 due 存成空串,读回来 fromString 得到无效 QDateTime
}
QJsonObject root;
root[QStringLiteral("version")] = 1;
root[QStringLiteral("items")] = arr;
// QSaveFile 写临时文件再原子替换,崩溃也不会留下半个 JSON
QSaveFile file(dataPath());
if (!file.open(QIODevice::WriteOnly)) return;
file.write(QJsonDocument(root).toJson(QJsonDocument::Indented));
file.commit();
}
void MainWindow::closeEvent(QCloseEvent *event)
{
saveToDisk();
QSettings settings;
settings.setValue(QStringLiteral("geometry"), saveGeometry());
QMainWindow::closeEvent(event);
}// src/main.cpp
#include <QApplication>
#include <QCoreApplication>
#include <QSettings>
#include "mainwindow.h"
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
// 必须在使用 QSettings 之前设置,否则三个平台会写到不同地方
QCoreApplication::setOrganizationName(QStringLiteral("QtTutorial"));
QCoreApplication::setApplicationName(QStringLiteral("Todo"));
QSettings::setDefaultFormat(QSettings::IniFormat);
MainWindow w;
w.show();
return app.exec();
}#关键细节与踩坑
1. 改了数据界面不刷新,或者刷新错行。 新手最常见的错误是直接改 m_items 然后 update(),视图根本不知道数据变了。规矩是:插入用 beginInsertRows/endInsertRows,删除用 beginRemoveRows/endRemoveRows,改内容发 dataChanged(topLeft, bottomRight, roles),整体替换用 beginResetModel/endResetModel(代价是丢失选中状态和滚动位置,能用前三种就别用它)。dataChanged 的第三个参数把变化的角色精确列出来,视图就不会做无谓的重绘。
2. 点击复选框没反应,或者点标题也能切换。 因为复选框是我们自己画出来的像素,Qt 并不知道那里有个可点的东西。解决方式是绘制和点击共用同一个 checkRect() 函数,在 editorEvent 里判断 contains(me->pos()),命中就 model->setData(...) 并返回 true 表示事件已被消费;不命中就交给基类,否则双击编辑会被一起吞掉。
3. 删除时行号对不上,删错了条目。 视图和代理模型给的是代理索引,它的 row() 是过滤后的行号,不是源模型的行号。所有对源模型的操作都必须先 mapToSource()。反过来,源模型行号要转成代理索引用 mapFromSource()。批量删除还要从大到小删:删掉第 2 行之后,原来的第 5 行变成了第 4 行。
4. 滚动列表时 CPU 占用飙升。 QListView 默认会对每个项调用 sizeHint()。setUniformItemSizes(true) 让它只测一次,滚动性能提升非常明显。另外委托的 paint() 里不要创建 QFont、QPen 之外的重对象(比如每次都 QFontMetrics 构造是允许的,但别在里面读写文件或加载图片),绘制函数每帧都会被调用几百次。
5. 隐藏已完成项之后数据"消失"了。 筛选绝不能改源模型。代理模型的 invalidateFilter() 触发重新筛选,源数据始终保持完整,切换回"全部"就都回来了。同理,排序也是视图侧的映射,不要真去 std::sort 源数据——那样连撤销都做不了。
6. 退出时数据丢失。 两个原因:一是数据在 closeEvent 才保存,用 QApplication::aboutToQuit 更稳妥(系统关机、注销时也会触发);二是直接 QFile::write 覆盖原文件,中途失败文件就残废了。用 QSaveFile 做原子替换,它先写 .tmp 再 rename,同分区下 rename 是原子操作。
#还能怎么扩展
- 拖拽排序:模型重写
dropMimeData/mimeData(至少序列化行号),视图设置setDragDropMode(QAbstractItemView::InternalMove),就能手拖调整优先级顺序。 - 分组树形展示:改用
QTreeModel按"今天 / 本周 / 已完成"分组,父节点只做分组、不存数据;QAbstractItemModel的接口已经为这种树形预留好了parent()与hasChildren()。 - 撤销重做:引入
QUndoStack(第三篇第 8 章),把每次增删改封装成QUndoCommand,Ctrl+Z就能回退,注意撤销后要同步刷新QSettings。 - 富文本备注:给
TodoItem加一个QString note,双击弹出QTextEdit对话框编辑,用QTextDocument::toHtml()存进 JSON;注意 HTML 存进 JSON 时要保证是 UTF-8。 - 数据量大时的懒加载:上万条待办时改用
QSqlTableModel(第四篇第 7 章),视图只取可视区域的行,模型结构与现在完全兼容,界面代码一处不用改——这正是 Model/View 分层的回报。
#小结
- Model 只回答"第几行、什么角色、什么值",Delegate 只回答"这一行画成什么样",View 只管滚动与选中,三者职责绝不交叉。
- 任何改变数据形态的操作都要用
beginXxx/endXxx包起来,否则视图的内部映射会错乱。 - 自绘控件上的可点区域,绘制与命中判定必须共用同一个矩形函数。
- 视图里拿到的是代理索引,对源模型操作前一律
mapToSource();批量删除从大到小;setUniformItemSizes(true)与精确的dataChanged角色列表是列表性能最简单有效的两个开关。 - 持久化用
QSaveFile做原子写、QStandardPaths定位路径、QSettings存界面状态,三者配合才能做到"关掉再打开一模一样"。
#练习
- 增加"编辑优先级"的右键菜单:为列表设置
setContextMenuPolicy(Qt::ActionsContextMenu),加上三个QAction分别把选中项设为高/中/低,内部调用m_model->setData(srcIdx, int(Priority::High), TodoModel::PriorityRole)。 - 实现"按标题搜索":在
StatusFilter里再加一个setKeyword(const QString &),filterAcceptsRow同时要求标题包含关键字(contains(keyword, Qt::CaseInsensitive)),并接一个QLineEdit的textChanged信号。 - 加一个"逾期提醒":用
QTimer每分钟触发一次,遍历模型找出isOverdue()且距截止时间 30 分钟内的项,用statusBar()->showMessage提示;注意定时器回调里不要修改模型结构。 - 把列表改成
QTableView:给TodoModel增加columnCount()返回 4、headerData()返回列名,四个角色分列显示;体会模型不变、只换视图与委托就能彻底改头换面。