QC++ / Qt 学习之路

案例:Todo 待办清单(Model/View 实战)

自定义 Model 与委托绘制待办项,增删改查并持久化到 JSON

实战第 44 / 48 章第六篇 · 案例实战

#这个案例做什么

写一个能真正管住日常事务的待办清单:顶部一行输入框敲下回车就新增一条,列表里每条待办有复选框、优先级彩色标签和截止时间,点击复选框即完成,可以编辑、删除、按状态筛选、按优先级排序,所有数据退出时自动存成 JSON,下次启动原样恢复,连窗口大小和列宽都记得。更重要的是,这个案例把"数据"和"显示"彻底分开——模型只管数据,委托只管画,视图只管滚动和选中,任何一处改动都不会牵连其他部分,这是 Qt Model/View 架构最值得体会的地方。

待办清单 · QListView + 自定义委托 文件 编辑 视图 帮助 添加新任务… 添加 完成第 3 章习题 高 删除 整理 Qt 信号与槽笔记 中 删除 购买《C++ Primer》 低 删除 提交上周实验报告 高 删除 预习虚函数与多态 中 删除 共 8 项 · 3 项已完成 剩余 5 项 QLineEdit + QPushButton QListView QStyledItemDelegate
Todo 界面结构——顶部输入区 + 列表视图 + 底部状态栏统计

功能清单:

  • 新增待办:输入标题 + 选择优先级(高/中/低)+ 可选的截止时间;
  • 勾选完成:点击复选框切换状态,已完成项标题自动加删除线并变灰;
  • 编辑与删除:双击标题就地编辑,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 核心数据类型

#项目结构

Text
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
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。

C++
// 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);
    }
};
C++
// 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;
};
C++
// 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(),绘制和点击共用同一份代码——这是避免"看着能点却点不中"的唯一可靠办法。

C++
// 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);
};
C++
// 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() 把代理索引换算回源模型行号,这是最容易出错的一步。

C++
// 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;
};
C++
// 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 就是干这件事的。

C++
// 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;
};
C++
// 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);
}
C++
// 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 存界面状态,三者配合才能做到"关掉再打开一模一样"。

#练习

  1. 增加"编辑优先级"的右键菜单:为列表设置 setContextMenuPolicy(Qt::ActionsContextMenu),加上三个 QAction 分别把选中项设为高/中/低,内部调用 m_model->setData(srcIdx, int(Priority::High), TodoModel::PriorityRole)。
  2. 实现"按标题搜索":在 StatusFilter 里再加一个 setKeyword(const QString &),filterAcceptsRow 同时要求标题包含关键字(contains(keyword, Qt::CaseInsensitive)),并接一个 QLineEdit 的 textChanged 信号。
  3. 加一个"逾期提醒":用 QTimer 每分钟触发一次,遍历模型找出 isOverdue() 且距截止时间 30 分钟内的项,用 statusBar()->showMessage 提示;注意定时器回调里不要修改模型结构。
  4. 把列表改成 QTableView:给 TodoModel 增加 columnCount() 返回 4、headerData() 返回列名,四个角色分列显示;体会模型不变、只换视图与委托就能彻底改头换面。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。