QC++ / Qt 学习之路

实战项目一:多功能文本编辑器(Qt Widgets)

从零搭建一个带文件、查找、偏好设置的桌面编辑器

进阶第 38 / 48 章第五篇 · QML 与实战项目

#需求与功能清单

第一个实战项目选一个纯 Widgets 的桌面文本编辑器。选它的理由是:功能边界清晰、每个需求都对应你在前面几篇学过的某个知识点,而且能把"项目组织"这件事从头走一遍——目录怎么分、类怎么划、UI 与逻辑怎么解耦。做完它,你就具备独立开发中小桌面工具的能力了。

记事本 · 无标题.txt 文件 编辑 格式 帮助 新建 打开 保存 撤销 重做 Qt 学习笔记 2026-10-20 · 第 3 章 信号与槽 信号与槽(Signal and Slot)是 Qt 的核心机制,用于对象间通信。 connect(sender, &Sender::valueChanged, this, &Main::onValue); 槽函数可以是普通成员函数、lambda 表达式,也可以连到另一个信号。 注意:QObject 子类必须在类声明中加入 Q_OBJECT 宏。 编译环境:Qt 6.5 + MSVC 2019,标准 C++17。 行 12, 列 34 · UTF-8 · 字数 1,024 100% · Windows (CRLF) QMenuBar 菜单栏 QToolBar 工具栏 QTextEdit 编辑区 QStatusBar 状态栏
记事本的界面结构

功能清单(对照着做,不要一次全上):

  • 文件:新建、打开(支持多选拖拽)、保存、另存为、关闭;修改未保存时退出要提示。
  • 编辑:撤销/重做、剪切/复制/粘贴、全选;自动换行开关。
  • 查找替换:查找下一个/上一个、区分大小写、全词匹配、替换、全部替换。
  • 最近文件:记录最近 10 个,菜单可点击打开,能清空。
  • 偏好持久化:窗口大小位置、字体、自动换行、是否显示行号,下次启动自动恢复。
  • 编码:UTF-8 优先,能识别并正确打开 GBK 文件,另存时可指定编码。
  • 视图:状态栏显示行列号、字符数、当前编码、是否修改。

非功能要求:单个文件不超过 400 行;UI 层不出现业务逻辑;所有字符串用 QStringLiteral。

#目录结构与 CMake 配置

CODE
TextEditor/
├── CMakeLists.txt
├── src/
│   ├── main.cpp
│   ├── MainWindow.h/.cpp        # 窗口与菜单、动作管理
│   ├── EditorView.h/.cpp        # 继承 QTextEdit,负责编辑与行号
│   ├── Document.h/.cpp          # 一个打开的文档:路径、内容、编码、脏标记
│   ├── FindReplaceDialog.h/.cpp # 查找替换对话框
│   ├── RecentFiles.h/.cpp       # 最近文件列表(基于 QSettings)
│   └── Settings.h/.cpp          # 偏好设置的读写封装
└── resources/
    ├── icons/                   # 图标(可先用系统内置风格图标替代)
    └── resources.qrc

Document 是关键的一层抽象:它不含任何 QWidget,纯粹是"一份文档的数据 + 行为"(load/save/encoding/isModified)。这样测试时不需要创建窗口,将来换成多标签页也只是管理多个 Document 实例。这叫把"数据模型"从"视图"里剥离出来,是本项目最重要的架构决策。

对照着看三层职责:Document 只管"内容是什么、怎么存盘";EditorView 只管"怎么显示、光标在哪、行号怎么画";MainWindow 只管"菜单点了之后调用谁"。判断某段代码该放哪层的简单标准是——把它单独拿出来,能否用一个不创建窗口的单元测试跑通。如果能,它就不属于视图层。很多初学者写出来的 Qt 程序之所以难以维护,就是因为主窗口类里同时塞了文件 IO、字符串处理、控件样式和业务逻辑,一旦要加个"导出 PDF"的功能,就得在一个三千行的文件里翻找。

另外注意 m_modified 这个脏标记:它是 Document 的状态,而不是窗口的状态。所有"要不要提示保存"的判断都应基于它,而不是去比较内存文本与磁盘文本——后者在编码转换、行尾规范化(\n 与 \r\n)的场景下会误判。

CMake
cmake_minimum_required(VERSION 3.16)
project(TextEditor LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)          # 关键:启用 moc,否则 Q_OBJECT 类编译不过
set(CMAKE_AUTORCC ON)          # 自动编译 .qrc

find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()

qt_add_executable(TextEditor
    src/main.cpp
    src/MainWindow.cpp
    src/EditorView.cpp
    src/Document.cpp
    src/FindReplaceDialog.cpp
    src/RecentFiles.cpp
    src/Settings.cpp
    resources/resources.qrc
)

target_include_directories(TextEditor PRIVATE src)
target_link_libraries(TextEditor PRIVATE Qt6::Widgets)

# macOS 生成 .app  bundle
set_target_properties(TextEditor PROPERTIES MACOSX_BUNDLE TRUE)

CMAKE_AUTOMOC ON 是 Qt 项目的标配。它会在编译前扫描头文件里的 Q_OBJECT,生成 moc_xxx.cpp 并自动加入构建。忘了它,你会看到一堆 undefined reference to vtable for MainWindow。

#文档层:编码与读写

编码处理是这个项目里最"有技术含量"的部分。Qt 6 中 QTextCodec 被移到了 Qt5Compat 兼容模块,处理 GBK 的标准做法是用 QStringConverter(Qt 6 内置支持 GBK via QStringConverter::System 在中文 Windows 上即 GBK),或直接使用 QStringDecoder/QStringEncoder:

C++
// Document.h
#pragma once
#include <QObject>
#include <QString>
#include <QByteArray>

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

    bool load(const QString &path);                 // 自动探测编码
    bool save(const QString &path, const QByteArray &encoding = "UTF-8");
    bool save();                                    // 保存到当前路径

    QString  filePath() const { return m_path; }
    QString  displayName() const;                   // “未命名”或文件名
    QString  text() const { return m_text; }
    void     setText(const QString &t);
    QByteArray encoding() const { return m_encoding; }
    bool     isModified() const { return m_modified; }

signals:
    void modificationChanged(bool modified);
    void encodingDetected(const QByteArray &enc);

private:
    static QByteArray detectEncoding(const QByteArray &raw);

    QString     m_path;
    QString     m_text;
    QByteArray  m_encoding = "UTF-8";
    bool        m_modified = false;
};
C++
// Document.cpp(核心实现)
#include "Document.h"
#include <QFile>
#include <QFileInfo>
#include <QIODevice>

QByteArray Document::detectEncoding(const QByteArray &raw)
{
    // 1. 先检查 BOM
    if (raw.startsWith("\xEF\xBB\xBF")) return "UTF-8";
    if (raw.startsWith("\xFF\xFE"))     return "UTF-16LE";
    if (raw.startsWith("\xFE\xFF"))     return "UTF-16BE";

    // 2. BOM 缺失时,尝试按 UTF-8 严格解码;失败则回退到系统本地编码(中文 Windows 为 GBK)
    QStringDecoder utf8(QStringConverter::Utf8,
                        QStringConverter::Flag::Stateless);
    QString decoded = utf8.decode(raw);
    if (utf8.hasError()) {
        QStringDecoder local(QStringConverter::System);
        decoded = local.decode(raw);
        if (!local.hasError())
            return "System";        // 中文环境即 GBK/GB18030
    }
    return "UTF-8";
}

bool Document::load(const QString &path)
{
    QFile f(path);
    if (!f.open(QIODevice::ReadOnly)) return false;

    const QByteArray raw = f.readAll();
    f.close();

    m_encoding = detectEncoding(raw);

    QStringDecoder dec(m_encoding == "System"
                           ? QStringDecoder(QStringConverter::System)
                           : QStringDecoder(QStringConverter::Utf8));
    m_text = dec.decode(raw);

    m_path = path;
    m_modified = false;
    emit modificationChanged(false);
    emit encodingDetected(m_encoding);
    return true;
}

bool Document::save(const QString &path, const QByteArray &encoding)
{
    QFile f(path);
    if (!f.open(QIODevice::WriteOnly | QIODevice::Truncate)) return false;

    QByteArray out;
    if (encoding == "UTF-8") {
        out = m_text.toUtf8();                    // 可自行决定是否写 BOM
    } else {
        QStringEncoder enc(QStringConverter::System);   // GBK
        out = enc.encode(m_text);
    }

    if (f.write(out) != out.size()) { f.close(); return false; }
    f.close();

    m_path = path;
    m_encoding = encoding;
    m_modified = false;
    emit modificationChanged(false);
    return true;
}

要点:BOM 检测必须放在最前面,因为带 BOM 的文件一定按 BOM 处理;无 BOM 时用"严格 UTF-8 解码是否报错"来猜,这不是 100% 准确(GBK 的某些字节序列恰好是合法 UTF-8),但对日常场景足够。Qt 6 的 QStringConverter::System 在中文 Windows 上等价于 GBK,在中文 Linux 上通常是 UTF-8,这点要在 UI 上如实显示编码名。

#主窗口:菜单、动作与最近文件

主窗口类很容易膨胀成"什么都管"的巨型类,本项目用三条约束控制它:第一,所有 action 的创建集中在一个 createActions() 里,信号连接紧跟其后,读代码时从上往下扫一遍就知道有哪些功能;第二,真正的业务流程(打开、保存、询问是否保存)写成私有槽函数 openFile()/saveFile()/maybeSave(),菜单项只做转发;第三,跨模块的细节一律下沉——文件路径对话框写在主窗口里没问题(它属于交互),但"如何把 QString 存成 GBK"必须属于 Document。

Qt 的 QAction 是"一次定义、多处复用"的典范:同一个 action 可以同时放进菜单、工具栏和右键菜单,勾选状态与可用性自动同步,改一次 setEnabled(false) 三处同时置灰。closeEvent 与 maybeSave 的配合则是桌面程序的通用模式——所有可能丢失数据的出口(关闭、新建、打开另一个文件、退出)都先过一遍 maybeSave(),返回 false 就中止当前操作。

C++
// MainWindow.cpp(节选)
#include "MainWindow.h"
#include "FindReplaceDialog.h"
#include <QMenuBar>
#include <QToolBar>
#include <QStatusBar>
#include <QFileDialog>
#include <QMessageBox>
#include <QCloseEvent>
#include <QSettings>

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
{
    m_doc   = new Document(this);
    m_editor = new EditorView(this);
    setCentralWidget(m_editor);

    createActions();
    createMenus();
    createStatusBar();

    connect(m_editor, &QTextEdit::textChanged, this, [this] {
        m_doc->setText(m_editor->toPlainText());
        updateStatusBar();
    });
    connect(m_editor, &QTextEdit::cursorPositionChanged, this,
            &MainWindow::updateStatusBar);
    connect(m_doc, &Document::modificationChanged,
            this, &MainWindow::setWindowModified);

    m_recent = new RecentFiles(m_recentMenu, this);
    connect(m_recent, &RecentFiles::fileSelected,
            this, &MainWindow::openFile);

    Settings::instance().restoreWindow(this);
    applyFont(Settings::instance().editorFont());
}

void MainWindow::createActions()
{
    auto *actNew = new QAction(QIcon::fromTheme("document-new"), tr("新建"), this);
    actNew->setShortcut(QKeySequence::New);
    connect(actNew, &QAction::triggered, this, &MainWindow::newFile);

    m_actSave = new QAction(QIcon::fromTheme("document-save"), tr("保存"), this);
    m_actSave->setShortcut(QKeySequence::Save);
    m_actSave->setEnabled(false);
    connect(m_actSave, &QAction::triggered, this, &MainWindow::saveFile);
    connect(m_doc, &Document::modificationChanged,
            m_actSave, &QAction::setEnabled);   // 脏标记直接驱动按钮可用状态

    // ... 其余 action 同理
}

bool MainWindow::maybeSave()
{
    if (!m_doc->isModified()) return true;
    auto r = QMessageBox::question(this, tr("未保存的更改"),
        tr("文档已修改,是否保存?"),
        QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
    if (r == QMessageBox::Save)    return saveFile();
    if (r == QMessageBox::Cancel)  return false;
    return true;
}

void MainWindow::closeEvent(QCloseEvent *e)
{
    if (!maybeSave()) { e->ignore(); return; }
    Settings::instance().saveWindow(this);   // 关闭时持久化窗口几何
    e->accept();
}

setWindowModified(true) 配合窗口标题里的 [*] 占位符(setWindowTitle("xxx[*]"))会自动显示星号,这是 Qt 提供的小便利。

#查找替换对话框

查找逻辑放在对话框里,但要通过信号把"执行查找"的请求发给主窗口,因为操作 QTextEdit 光标的权力属于主窗口,对话框不应该持有编辑器指针——这样耦合最小,将来换成多文档只需要换一个响应者。

C++
// FindReplaceDialog.cpp(核心)
void FindReplaceDialog::onFindNext()
{
    QTextDocument::FindFlags flags;
    if (m_caseSensitive->isChecked()) flags |= QTextDocument::FindCaseSensitively;
    if (m_wholeWords->isChecked())    flags |= QTextDocument::FindWholeWords;
    if (!m_forward->isChecked())      flags |= QTextDocument::FindBackward;

    auto *editor = qobject_cast<QTextEdit *>(m_target);
    bool found = editor->find(m_keywordEdit->text(), flags);

    if (!found) {   // 环绕查找:从头再来一次
        QTextCursor c = editor->textCursor();
        c.movePosition(flags & QTextDocument::FindBackward ? QTextCursor::End
                                                           : QTextCursor::Start);
        editor->setTextCursor(c);
        found = editor->find(m_keywordEdit->text(), flags);
    }
    m_statusLabel->setText(found ? tr("") : tr("未找到匹配项"));
    m_statusLabel->setStyleSheet(found ? "" : "color:#F44336");
}

void FindReplaceDialog::onReplaceAll()
{
    auto *editor = qobject_cast<QTextEdit *>(m_target);
    QTextCursor c(editor->document());
    c.beginEditBlock();                       // 合并为一个撤销步骤
    int count = 0;
    c.movePosition(QTextCursor::Start);
    editor->setTextCursor(c);
    while (editor->find(m_keywordEdit->text(),
                        m_caseSensitive->isChecked()
                            ? QTextDocument::FindCaseSensitively
                            : QTextDocument::FindFlags())) {
        QTextCursor cur = editor->textCursor();
        cur.insertText(m_replaceEdit->text()); // 直接替换选区
        ++count;
    }
    c.endEditBlock();
    QMessageBox::information(this, tr("替换完成"),
                             tr("共替换 %1 处").arg(count));
}

beginEditBlock / endEditBlock 让"全部替换"在 QTextEdit 的撤销栈里只占一步,否则用户按一次 Ctrl+Z 只撤销一处,体验很差。

#设置持久化

QSettings 会自动选择后端(Windows 注册表、macOS plist、Linux ini),你只需要关心 key:

C++
// Settings.cpp
#include "Settings.h"
#include <QFont>

Settings &Settings::instance()
{
    static Settings s;      // 函数内静态变量,线程安全的单例
    return s;
}

Settings::Settings() : m_set("MyCompany", "TextEditor") {}

void Settings::saveWindow(QWidget *w)
{
    m_set.beginGroup("Window");
    m_set.setValue("geometry", w->saveGeometry());   // 比手存 x/y/w/h 更可靠
    m_set.setValue("state",    w->saveState());      // 工具栏/停靠窗布局
    m_set.endGroup();
}

void Settings::restoreWindow(QWidget *w)
{
    m_set.beginGroup("Window");
    w->restoreGeometry(m_set.value("geometry").toByteArray());
    w->restoreState(m_set.value("state").toByteArray());
    m_set.endGroup();
}

QFont Settings::editorFont() const
{
    QVariant v = m_set.value("Editor/font");
    if (v.isValid()) return v.value<QFont>();
    return QFont("Menlo", 13);        // 默认值
}

QStringList Settings::recentFiles() const
{
    return m_set.value("Recent/files").toStringList();
}

用 saveGeometry() 而不是手动记坐标,能正确处理多显示器、最大化状态、屏幕 DPI 变化等一堆边界情况。恢复失败时(首次启动)restoreGeometry 会静默失败,窗口保持默认大小,无需额外判断。

#小结

  1. 架构上把 Document(数据与 IO)从 MainWindow(视图)中剥离,是本项目最重要的设计决策,也让逻辑可被单独测试。
  2. 编码处理顺序:先查 BOM(UTF-8/UTF-16),再用严格 UTF-8 解码失败与否回退到本地编码(GBK)。
  3. QAction 一处定义多处复用,用 &Document::modificationChanged 直接连到 QAction::setEnabled,免去手写同步。
  4. "全部替换"要用 beginEditBlock/endEditBlock 合并为单个撤销步骤。
  5. 偏好持久化用 QSettings + saveGeometry/saveState,别手存坐标。

#练习

  1. 给编辑器加上行号栏(继承 QWidget 作 gutter,重写 paintEvent,在 EditorView 的 resizeEvent 中同步其宽度)。
  2. 实现最近文件菜单:最多 10 条,去重,文件不存在时自动移除并在菜单项上禁用,提供"清空列表"。
  3. 增加"自动换行"与"显示不可见字符"开关,并把状态写入 QSettings,下次启动恢复。
  4. 挑战:改造成多标签页(用 QTabWidget + QVector<Document*>),关闭单个标签时也要触发未保存提示。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。