Qt零基础文件操作全攻略

前言

本系列从 Qt 开发环境搭建起步，一路讲解窗口控件、信号槽、界面布局、事件处理，到本篇迎来入门阶段核心模块 ------ 文件操作，也是第 10 篇收官基础 IO 章节。掌握文件读写是桌面软件必备能力：记事本工具、本地缓存、软件配置、数据导出都离不开文件类，本篇一次性讲透 Qt 文件体系，零基础也能直接抄代码运行。

一、Qt 文件核心两大基础类

QFile：底层文件操作类，负责打开、关闭、删除、重命名文件，可读写文本 / 二进制文件，兼容 Windows、Linux、macOS 跨平台路径。
QTextStream：文本流，专门处理纯文本，自动解决中文乱码、换行符跨平台兼容。
QDataStream：二进制流，存储结构体、数字、图片等非文本数据，读写格式统一。

补充辅助工具类

QFileInfo：获取文件大小、创建时间、后缀、是否文件夹等属性；
QDir：文件夹遍历、创建目录、筛选指定格式文件；
QTemporaryFile：临时文件，程序退出自动销毁。

二、基础文本文件读写实战（完整可运行代码）

1. 写入文本文件

复制代码

#include <QFile>
#include <QTextStream>
#include <QMessageBox>

void writeTxtFile()
{
    // 创建文件对象，相对路径/绝对路径均可
    QFile file("test.txt");
    // 读写模式，不存在则创建，存在则清空原有内容
    if(!file.open(QIODevice::WriteOnly | QIODevice::Text))
    {
        QMessageBox::warning(nullptr, "错误", "文件打开失败：" + file.errorString());
        return;
    }
    QTextStream stream(&file);
    // 设置编码，解决中文乱码
    stream.setEncoding(QStringConverter::Utf8);
    stream << "Qt零基础文件操作\n";
    stream << "第十篇博客示例代码\n";
    stream << "中文测试内容";
    file.close();
}

2. 读取全部文本

复制代码

void readTxtFile()
{
    QFile file("test.txt");
    if(!file.open(QIODevice::ReadOnly | QIODevice::Text))
    {
        QMessageBox::warning(nullptr, "错误", "读取失败：" + file.errorString());
        return;
    }
    QTextStream stream(&file);
    stream.setEncoding(QStringConverter::Utf8);
    // 读取全部内容
    QString content = stream.readAll();
    file.close();
}

三、二进制文件读写（存储数字、自定义数据）

文本仅适合字符串，存储数值、图片、自定义结构体必须用 QDataStream，读写顺序严格对应。

复制代码

// 写入二进制
void writeBinFile()
{
    QFile file("data.bin");
    file.open(QIODevice::WriteOnly);
    QDataStream ds(&file);
    ds << 10086 << 3.1415 << QString("二进制存储测试");
    file.close();
}

// 读取二进制
void readBinFile()
{
    QFile file("data.bin");
    file.open(QIODevice::ReadOnly);
    QDataStream ds(&file);
    int num;
    double pi;
    QString str;
    ds >> num >> pi >> str;
    file.close();
}

四、软件配置文件 QSettings（高频开发场景）

做桌面软件几乎都会保存窗口大小、登录账号、主题设置，Qt 内置 QSettings 无需手动解析 ini，极简操作：

复制代码

// 保存配置
void saveConfig()
{
    // 组织名+程序名，自动生成ini配置文件
    QSettings setting("QtStudy", "QtDemo");
    setting.setValue("window/w", 800);
    setting.setValue("window/h", 600);
    setting.setValue("user/name", "测试用户");
}

// 读取配置，第二个参数为默认值（配置不存在时返回）
void loadConfig()
{
    QSettings setting("QtStudy", "QtDemo");
    int w = setting.value("window/w", 600).toInt();
    QString name = setting.value("user/name", "游客").toString();
}

五、文件夹操作：遍历文件、创建目录

1. 创建文件夹

复制代码

QDir dir("./log");
if(!dir.exists())
    dir.mkdir("./log");

2. 遍历目录下所有 txt 文件

cpp

运行

复制代码

QDir dir("./");
// 筛选后缀
dir.setNameFilters(QStringList() << "*.txt");
// 遍历文件列表
QFileInfoList list = dir.entryInfoList();
for(auto info : list)
{
    QString fileName = info.fileName();
    qDebug() << "文件名称：" << fileName;
}

六、常见踩坑总结（零基础必看）

中文乱码：读写文本必须给 QTextStream 设置 Utf8 编码；
文件忘记 close：作用域结束 QFile 自动析构关闭，但复杂逻辑建议手动 close；
路径分隔符：Qt 统一用/，不用 Windows 的\，跨平台兼容；
只读模式无法写入、文件被占用会打开失败；
QDataStream 读写顺序必须完全一致，否则数据错乱。

七、本系列阶段性总结

至此 Qt 零基础 1-10 篇基础模块全部完结：

开发环境搭建（Windows Qt Creator）
基础窗口 QWidget、MainWindow
常用控件：按钮、输入框、标签、下拉框
信号与槽核心机制
界面布局：水平 / 垂直 / 网格布局
鼠标、键盘事件处理
对话框：消息框、文件选择框
菜单栏、工具栏、状态栏
弹窗与父子窗口生命周期
完整文件 IO 操作（本文）

从界面绘制到本地文件存储，已经具备独立开发简易桌面工具的能力。

下一篇预告

基础 IO 结束，正式进入 Qt 数据持久化进阶：Qt 数据库编程，讲解 SQLite 本地轻量数据库，实现增删改查、表单数据存储，适合做带本地数据管理的桌面程序，敬请期待！