实战项目一:多功能文本编辑器(Qt Widgets)
从零搭建一个带文件、查找、偏好设置的桌面编辑器
#需求与功能清单
第一个实战项目选一个纯 Widgets 的桌面文本编辑器。选它的理由是:功能边界清晰、每个需求都对应你在前面几篇学过的某个知识点,而且能把"项目组织"这件事从头走一遍——目录怎么分、类怎么划、UI 与逻辑怎么解耦。做完它,你就具备独立开发中小桌面工具的能力了。
功能清单(对照着做,不要一次全上):
- 文件:新建、打开(支持多选拖拽)、保存、另存为、关闭;修改未保存时退出要提示。
- 编辑:撤销/重做、剪切/复制/粘贴、全选;自动换行开关。
- 查找替换:查找下一个/上一个、区分大小写、全词匹配、替换、全部替换。
- 最近文件:记录最近 10 个,菜单可点击打开,能清空。
- 偏好持久化:窗口大小位置、字体、自动换行、是否显示行号,下次启动自动恢复。
- 编码:UTF-8 优先,能识别并正确打开 GBK 文件,另存时可指定编码。
- 视图:状态栏显示行列号、字符数、当前编码、是否修改。
非功能要求:单个文件不超过 400 行;UI 层不出现业务逻辑;所有字符串用 QStringLiteral。
#目录结构与 CMake 配置
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.qrcDocument 是关键的一层抽象:它不含任何 QWidget,纯粹是"一份文档的数据 + 行为"(load/save/encoding/isModified)。这样测试时不需要创建窗口,将来换成多标签页也只是管理多个 Document 实例。这叫把"数据模型"从"视图"里剥离出来,是本项目最重要的架构决策。
对照着看三层职责:Document 只管"内容是什么、怎么存盘";EditorView 只管"怎么显示、光标在哪、行号怎么画";MainWindow 只管"菜单点了之后调用谁"。判断某段代码该放哪层的简单标准是——把它单独拿出来,能否用一个不创建窗口的单元测试跑通。如果能,它就不属于视图层。很多初学者写出来的 Qt 程序之所以难以维护,就是因为主窗口类里同时塞了文件 IO、字符串处理、控件样式和业务逻辑,一旦要加个"导出 PDF"的功能,就得在一个三千行的文件里翻找。
另外注意 m_modified 这个脏标记:它是 Document 的状态,而不是窗口的状态。所有"要不要提示保存"的判断都应基于它,而不是去比较内存文本与磁盘文本——后者在编码转换、行尾规范化(\n 与 \r\n)的场景下会误判。
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:
// 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;
};// 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 就中止当前操作。
// 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 光标的权力属于主窗口,对话框不应该持有编辑器指针——这样耦合最小,将来换成多文档只需要换一个响应者。
// 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:
// 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 会静默失败,窗口保持默认大小,无需额外判断。
#小结
- 架构上把
Document(数据与 IO)从MainWindow(视图)中剥离,是本项目最重要的设计决策,也让逻辑可被单独测试。 - 编码处理顺序:先查 BOM(UTF-8/UTF-16),再用严格 UTF-8 解码失败与否回退到本地编码(GBK)。
QAction一处定义多处复用,用&Document::modificationChanged直接连到QAction::setEnabled,免去手写同步。- "全部替换"要用
beginEditBlock/endEditBlock合并为单个撤销步骤。 - 偏好持久化用
QSettings+saveGeometry/saveState,别手存坐标。
#练习
- 给编辑器加上行号栏(继承
QWidget作 gutter,重写paintEvent,在EditorView的resizeEvent中同步其宽度)。 - 实现最近文件菜单:最多 10 条,去重,文件不存在时自动移除并在菜单项上禁用,提供"清空列表"。
- 增加"自动换行"与"显示不可见字符"开关,并把状态写入
QSettings,下次启动恢复。 - 挑战:改造成多标签页(用
QTabWidget+QVector<Document*>),关闭单个标签时也要触发未保存提示。