Qt 文件操作

Qt 文件操作

Qt 提供了一套强大的文件操作API，使得在各种应用场景下进行文件管理变得高效而简单。无论是在桌面应用程序、嵌入式系统还是移动应用中，浏览、读取、写入和管理文件及目录都是基本而重要的任务。

以下是一些常用的 Qt 文件操作，涵盖了文件读写、配置管理以及目录和路径操作。

1. I/O设备

Qt 中的 I/O 操作通过统一的接口简化了文件与外部设备的操作方式。文件被视为一种特殊的外部设备，因此文件操作与其他外部设备操作是相似的。I/O 操作的本质是对连续存储空间的数据进行读写。

QIODevice 为支持读写数据块（如 QFile、QBuffer 和 QTcpSocket）的设备提供了通用实现和抽象接口。QIODevice 是一个抽象类，无法直接实例化，但通常使用它定义的接口来提供与设备无关的 I/O 特性。

1.1 I/O设备的类型

• 顺序存取设备：只能从头开始顺序读写数据，不能指定数据的读写位置。
• 随机存取设备：可以定位到任意位置进行数据的读写。

1.2 打开模式

文件打开时需要指定模式，模式是一个枚举类型 QIODeviceBase::OpenModeFlag，与 QIODevice::open() 一起使用，描述设备的打开模式。可以通过 QIODevice::openMode() 方法获取当前打开模式。

2. 文件读写

2.1 QFile

QFile 是一个用于读写文本、二进制文件和资源的 I/O 设备。它可以单独使用，或者与 QTextStream 或 QDataStream 一起使用，以提供更方便的操作。

文件名通常在构造函数中传递，但也可以通过 setFileName() 方法在任何时候设置。无论操作系统是什么，QFile 都希望文件分隔符是 '/'，不支持使用其他分隔符（例如 '\\'）。

可以使用 exists() 方法检查文件是否存在，并使用 remove() 方法删除文件。更高级的文件系统相关操作由 QFileInfo 和 QDir 提供。

文件通过 open() 打开，使用 close() 关闭，使用 flush() 刷新。数据通常通过 QDataStream 或 QTextStream 读取和写入，但也可以调用 QIODevice 的继承函数如 read()、readLine()、readAll() 和 write()。QFile 还继承了 getChar()、putChar() 和 ungetChar()，它们每次只操作一个字符。

文件的大小可以通过 size() 方法获取。您可以使用 pos() 获取当前文件位置，或使用 seek() 移动到新的文件位置。如果已到达文件末尾，atEnd() 将返回 true。

打开文件

创建 QFile 对象，通过构造函数或 setFileName() 设置文件名，然后使用 open() 函数以指定的打开模式打开文件。

如果打开失败，可以通过 errorString() 获取失败原因。

void testOpen()
{
    QFile file("./Maye.txt"); // 只读模式打开
    if (!file.open(QIODevice::ReadOnly /*| QIODevice::WriteOnly */))
    {
        qWarning() << file.fileName() << "open failed：" << file.errorString();
        return;
    }
    
    file.close(); // 关闭文件
}

写文件

文件打开成功后，使用 write() 来写入数据。

void write()
{
    QFile file("./Maye.txt");
    if (!file.open(QIODevice::WriteOnly)) // 只写模式打开
    {
        qWarning() << file.fileName() << "open failed：" << file.errorString();
        return;
    }

    // 写入数据
    qInfo() << "write size" << file.write("hello Mayejun\n");
    qInfo() << "write size" << file.write(QByteArray("123\n"));
    
    file.close(); // 关闭文件
}

读文件

文件打开成功后，使用 read() 读取指定长度的数据，使用 readLine() 读取一行，使用 readAll() 读取所有数据。

void open()
{
    QFile file("./Maye.txt");
    if (!file.open(QIODevice::ReadOnly)) // 只读模式打开
    {
        qWarning() << file.fileName() << "open failed：" << file.errorString();
        return;
    }

    // 获取文件位置指针的位置
    qInfo() << "pos" << file.pos();
    file.seek(0);  // 设置文件位置指针为0
    qInfo() << "size" << file.size();  // 获取文件大小
    
    // 读取一些数据
    qInfo() << file.read(5);

    QByteArray arr(10, '\0');
    qint64 len = file.read(arr.data(), 10);
    qInfo() << "len" << len << arr;

    file.close(); // 关闭文件
}

静态函数

QFile 提供了一些静态方法来执行常见的文件操作，如复制、删除、重命名等。

void staticFun()
{
    // 把 Maye.txt 拷贝到上级目录中的 hello.txt 中 (hello.txt 必须不存在)
    if (!QFile::copy("Maye.txt", "../hello.txt"))
    {
        qWarning() << "copy failed!";
    }

    // 判断某个文件是否存在
    if (!QFile::exists("Maye.txt"))
    {
        qWarning() << "file not exists!";
    }

    // 创建符号链接 (快捷方式)，后缀必须是 .lnk
    if (!QFile::link("Maye.txt", "../马也.lnk"))
    {
        qWarning() << "create link failed!";
    }

    // 将指定的文件移动到垃圾桶
    QString trashPath;
    if (!QFile::moveToTrash("Maye.txt", &trashPath))
    {
        qWarning() << "moveToTrash failed!";
    }
    else
    {
        qInfo() << "moveToTrash successful, path is" << trashPath;
    }

    // 删除文件
    bool ok = QFile::remove("Maye.txt");
    qInfo() << ok;
    if (!ok)
    {
        qWarning() << "remove failed";
    }

    // 重命名文件
    if (!QFile::rename("Maye1.txt", "Maye2.txt"))
    {
        qWarning() << "rename failed!";
    }

    // 设置文件大小
    if (!QFile::resize("Maye2.txt", 512))
    {
        qWarning() << "resize failed!";
    }

    // 返回符号链接引用的文件或目录的绝对路径
    auto targetStr = QFile::symLinkTarget("../马也.lnk");
    if (targetStr.isEmpty())
    {
        qWarning() << "不是符号链接";
    }
    qInfo() << targetStr;
}

2.2 Stream

为了简化文本文件和数据文件的读写操作，Qt 提供了 QTextStream 和 QDataStream 辅助类。QTextStream 可将写入的数据全部转换为可读文本，QDataStream 可将写入的数据根据类型转换为二进制数据。

QTextStream

QTextStream 可以在 QIODevice、QByteArray 或 QString 上操作。使用 QTextStream 的流操作符，可以方便地读和写单词、行和数字。对于生成文本，QTextStream 支持字段填充和对齐的格式化选项，以及数字的格式化。

class Student
{
public:
    qint64 number;
    QString name;
    QString grade;
    qreal math;
    qreal chinese;
    qreal english;
    friend QDebug& operator<<(QDebug& out, const Student& other)
    {
        out.noquote() << other.number << other.name << other.grade << other.math << other.chinese << other.english;
        return out;
    }
};

void readStudentInfo()
{
    QFile file("./student.txt");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) // 以文本模式打开文件
    {
        return; // 返回-1不适合在void函数中使用
    }

    Student stu;
    QTextStream stream(&file);
    qDebug().noquote() << stream.readLine();
    while (!stream.atEnd())
    {
        stream >> stu.number >> stu.name >> stu.grade >> stu.math >> stu.chinese >> stu.english;
        qDebug() << stu;
    }
}

void test()
{
    QString res;
    QTextStream textstream(&res);
    textstream << "maye" << QString("冷寂") << "young";  // 注意：中文要用 QString 包起来，否则会乱码
    qDebug() << res;
}

QDataStream

QDataStream 用于处理二进制数据流，通过它可以方便地序列化和反序列化数据。

QByteArray data;
QDataStream stream(&data, QIODevice::ReadWrite);
stream << "image" << 1024 << "ABC"; // 写入数据
// 输出示例： ["\x00\x00\x00\x06image\x00"] [\x00\x00\x04\x00] [\x00\x00\x00\x04" "ABC\x00"]
qDebug() << data << data.size(); // 输出二进制数据

使用 QDataStream 串行化数据。如果数据是字符串，则会在前面用4个字节表示字符串长度；如果是整数，则直接存储。

2.3 QFileInfo

QFileInfo 类提供与系统无关的文件信息，允许用户获取文件的各种属性。

QFileInfo info(file);
QFileInfo info("../QFile-test/what.txt");
qDebug() << info.size();                // 文件大小
qDebug() << info.absoluteFilePath();    // 文件绝对路径（包括文件名）
qDebug() << info.absolutePath();        // 绝对路径（不包括文件名）
qDebug() << info.absoluteDir();         // 绝对路径，返回 QDir
qDebug() << info.path();                // 文件路径
qDebug() << info.filePath();            // 返回文件名，包括路径（可以是绝对路径也可以是相对路径）

if (info.isFile())  // 如果是文件
{
    qDebug() << info.fileName();            // 带后缀的文件名
    qDebug() << info.baseName();            // 不带后缀的文件名
    qDebug() << info.suffix();              // 获取文件后缀
}

3. 配置文件

3.1 QSettings

在应用程序中，用户通常希望记录设置（如窗口大小、位置、选项等），以便在下次启动时恢复这些状态。这些设置通常存储在不同的平台上有不同的方式：

• Windows：系统注册表（如 HKEY_CURRENT_USER\Software\MySoft）。
• macOS 和 iOS：属性列表文件。
• Unix 系统：常见地使用 INI 格式的文本文件。

QSettings 提供了对这些存储技术的抽象，使您能够以可移植的方式保存和恢复应用程序设置。它支持多种数据类型，基于 QVariant，例如 QString、QRect 和 QImage。

如果只需要一个非持久的基于内存的结构，可以考虑使用 QMap<QString, QVariant>。

基本用法

创建 QSettings 对象时，必须提供 公司或组织的名称 以及 应用程序的名称。例如，如果您的公司名为 “NiuBi”，应用程序名为 “QQ”，可以这样构造 QSettings 对象：

QSettings settings("NiuBi", "QQ");

QSettings 对象可以在栈上或堆上创建（使用 new）。构造和销毁对象的速度非常快。

如果在多个地方使用 QSettings，可以通过 QCoreApplication::setOrganizationName() 和 QCoreApplication::setApplicationName() 来指定组织名称和应用程序名称，然后使用无参数的默认构造函数：

QCoreApplication::setOrganizationName("NiuBi");
QCoreApplication::setApplicationDomain("NiuBi.com");
QCoreApplication::setApplicationName("QQ");

QSettings settings;  // 使用默认构造函数

设置和获取值

QSettings 存储的每个设置都是一对键值（key 为 QString 类型，value 为 QVariant 类型）。使用 setValue() 方法写入设置，例如：

settings.setValue("size", QSize(640, 480));
qDebug() << "Configuration file path:" << settings.fileName();  // 获取配置文件保存位置

如果已有相同键的设置，则新值将覆盖原值。更改可能不会立即保存到永久存储中，可以调用 sync() 方法立即提交更改。

要获取设置的值，可以使用 value() 方法：

QSize size = settings.value("size", QSize(250, 250)).value<QSize>();

如果指定的设置不存在，QSettings 将返回一个空的 QVariant。可以通过传递第二个参数指定默认值。

配置文件格式

在 Windows 上，默认为写入注册表。如果想将设置保存到 .ini 文件中并保存在执行文件所在目录，可以这样设置：

QApplication::setOrganizationName("NiuBi");
QApplication::setApplicationName("QQ");

QSettings settings(QApplication::applicationDirPath() + "/qfile.ini", QSettings::Format::IniFormat);

常用函数

• 设置值

void setValue(const QString &key, const QVariant &value);

设置指定键的值，如果键已存在，则覆盖。

• 获取值

QVariant value(const QString &key, const QVariant &defaultValue = QVariant()) const;

返回指定键的值。如果该设置不存在，则返回 defaultValue。

• 同步更改

void sync();

将所有未保存的更改写入永久存储，并更新被其他应用程序更改的任何设置。

• 获取状态

QSettings::Status status() const;

返回 QSettings 遇到的第一个错误状态码，如果没有错误则返回 QSettings::NoError。

• 删除设置

void remove(const QString &key);

删除指定键及其任何子设置。

• 获取文件路径

QString fileName() const;

返回存储设置的路径。在 Windows 上，如果格式为 QSettings::NativeFormat，则返回系统注册表路径而非文件路径。

分组操作

• 开始分组

void beginGroup(const QString &prefix);

向当前组添加前缀。

• 结束分组

void endGroup();

重置组为之前的状态。

• 获取当前组

QString group() const;

返回当前组名。

• 开始读取数组

int beginReadArray(const QString &prefix);

向当前组添加前缀并开始从数组读取，返回数组的大小。

• 开始写入数组

void beginWriteArray(const QString &prefix, int size = -1);

向当前组添加前缀并开始写入大小为 size 的数组。若 size 为 -1，则根据写入条目的索引自动确定。

• 结束数组

void endArray();

结束数组操作。

• 设置数组索引

void setArrayIndex(int i);

将当前数组索引设置为 i，后续对 setValue()、value()、remove() 和 contains() 等函数的调用将针对该索引处的数组项进行操作。

3.2 QJsonDocument

QJsonDocument 是一个用于封装完整 JSON 文档的类，它可以从基于 UTF-8 编码的文本表示中读取和写入该文档。通过 QJsonDocument::fromJson()，可以将 JSON 文档转换为 QJsonDocument。使用 toJson() 方法可以将其转换回文本格式。解析器能够非常快速且有效地将 JSON 转换为 Qt 使用的二进制表示形式。

主要功能

• 有效性检查：使用 isNull() 方法可以查询已解析文档的有效性。
• 类型查询：通过 isArray() 和 isObject() 来判断文档是否包含数组或对象。
• 访问数据：使用 array() 或 object() 方法来检索文档中包含的数组或对象，并进行读取或操作。

解析 JSON

下面的示例展示了如何从文件中读取 JSON 数据并解析为 QJsonDocument：

QJsonDocument parseJson(const QString& filePath)
{
    QFile file(filePath);
    if (!file.open(QIODevice::ReadOnly)) {
        return QJsonDocument();  // 返回一个空的 QJsonDocument
    }

    QJsonParseError jpe;
    QJsonDocument jdoc = QJsonDocument::fromJson(file.readAll(), &jpe);
    if (jdoc.isNull()) {
        qDebug() << "解析 JSON 失败：" << jpe.errorString();
    }
    return jdoc;
}

简单的对象

假设有如下 JSON 对象：

{
  "name": "顽石老师",
  "course_name": "Qt入门到入土",
  "version": "qt6.5.2",
  "age": 18
}

要获取对象中每个键对应的值，可以使用 QJsonDocument 提供的 operator[] 函数：

void testJsonDoc()
{
    QJsonDocument jdoc = parseJson("../../../test.json");

    qDebug() << "版本:" << jdoc["version"].toString();
    qDebug() << "姓名:" << jdoc["name"].toString();
    qDebug() << "课程名称:" << jdoc["course_name"].toString();
    qDebug() << "年龄:" << jdoc["age"].toInt();
}

复杂对象

对于复杂的对象，需要使用 object() 和 array() 方法获取具体对象，然后再进行解析。以下是一个包含多个对象的 JSON 数据示例 (person.json)：

{
  "maye": {
    "age": 18,
    "name": "maye",
    "tel": "123456"
  },
  "yue": {
    "age": 26,
    "name": "顽石",
    "tel": "987654321"
  }
}

读取“maye”对象的所有信息：

void readComplexJson()
{
    QJsonDocument jdoc = parseJson("../../../person.json");

    auto obj = jdoc["maye"].toObject();
    qDebug() << "姓名:" << obj.value("name").toString();
    qDebug() << "年龄:" << obj["age"].toInt();
    qDebug() << "电话:" << obj["tel"].toString();
}

如果想要读取所有对象的信息，可以遍历所有键：

void readAllPersons()
{
    QJsonDocument jdoc = parseJson("../../../person.json");
    auto rootObj = jdoc.object();  // 获取根对象
    auto keys = rootObj.keys();     // 获取所有键

    for (const auto& key : keys) {
        auto obj = rootObj[key].toObject();
        qDebug() << "姓名:" << obj.value("name").toString()
                 << "年龄:" << obj["age"].toInt()
                 << "电话:" << obj["tel"].toString();
    }
}

数组

对于 JSON 数组的处理也相对简单。假设有如下 JSON 数组：

[
  "Apple",
  "Banana",
  "Cherry",
  42
]

可以通过以下方式解析和输出数组中的元素：

void testJsonArray()
{
    QJsonDocument jdoc = parseJson("../../../test.json");

    if (jdoc.isArray()) {
        QJsonArray array = jdoc.array();
        for (size_t i = 0; i < array.size(); ++i) {
            QJsonValue v = array[i];
            if (v.isString()) {
                qDebug() << "字符串:" << v.toString();
            } else if (v.isDouble()) {
                qDebug() << "数字:" << v.toDouble();
            } else {
                qDebug() << "其他类型:" << v;
            }
        }
    }
}

4. 目录/路径

4.1 QDir

QDir 类提供对目录结构及其内容的访问。它的功能包括：

目录操作

• 创建目录：

  bool mkdir(const QString &dirName) const;
  bool mkpath(const QString &dirPath) const;  // 创建多级目录
  

• 删除目录：

  bool rmdir(const QString &dirName) const;   // 删除子目录（必须为空）
  bool rmpath(const QString &dirPath) const;   // 删除路径（必须为空）
  bool remove(const QString &fileName);         // 删除指定文件
  bool removeRecursively();                      // 删除目录及其所有内容
  

• 重命名目录：

  bool rename(const QString &oldName, const QString &newName);
  

目录条目获取

• 获取指定目录中的所有条目（文件和文件夹）：

  QFileInfoList entryInfoList(const QStringList &nameFilters, QDir::Filters filters = NoFilter, QDir::SortFlags sort = NoSort) const;
  QFileInfoList entryInfoList(QDir::Filters filters = NoFilter, QDir::SortFlags sort = NoSort) const;
  QStringList entryList(const QStringList &nameFilters, QDir::Filters filters = NoFilter, QDir::SortFlags sort = NoSort) const;
  QStringList entryList(QDir::Filters filters = NoFilter, QDir::SortFlags sort = NoSort) const;
  

常用路径获取

• 获取当前路径：

  QDir current();        // 返回应用程序当前目录的绝对路径
  QString currentPath();
  

• 获取用户主目录：

  QDir home();           // 例如 C:/Users/Maye
  QString homePath();
  

• 获取系统临时目录：

  QDir temp();
  QString tempPath();
  

• 获取根目录列表：

  QFileInfoList drives();  // 返回 C:/ D:/ 等根目录
  

计算目录大小

使用以下函数可以计算指定目录的大小：

quint32 dirSize(const QString& dirName)
{
    QDir dir(dirName);
    if (!dir.exists())
        return ~0;
    
    quint32 size = 0;
    for (const QFileInfo& info : dir.entryInfoList(QDir::Filter::NoDotAndDotDot | QDir::Files | QDir::Dirs))
    {
        if (info.isFile())
        {
            size += info.size();
        }
        else
        {
            size += dirSize(info.filePath());
        }
    }
    return size;
}

4.2 QDirIterator

QDirIterator 允许逐个遍历目录中的条目。它适用于大型目录，因为它一次只列出一个条目，而不是一次列出所有条目。它支持递归列出目录内容，并遵循符号链接。

使用示例

构造 QDirIterator 后，可以依次遍历所有条目：

QDirIterator it("/etc", QDirIterator::Subdirectories);
while (it.hasNext()) {
    QString dir = it.next();
    qDebug() << dir;  // 输出每个条目的路径
}

4.3 QStandardPaths

QStandardPaths 类提供访问标准路径的方法，例如用户特定目录或系统配置目录。它帮助开发者在不同操作系统中获取一致的路径，避免硬编码路径可能带来的问题。

静态公有函数

• 获取本地化显示名称：

  [static] QString displayName(QStandardPaths::StandardLocation type);
  

• 查找可执行文件：

  [static] QString findExecutable(const QString &executableName, const QStringList &paths = QStringList());
  

• 查找文件或目录：

  [static] QString locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile);
  

• 查找所有匹配的文件或目录：

  [static] QStringList locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile);
  

• 启用测试模式：

  [static] void setTestModeEnabled(bool testMode);
  

• 返回该类型文件所属的所有目录：

  [static] QStringList standardLocations(QStandardPaths::StandardLocation type);
  

• 返回可写类型文件的目录：

  [static] QString writableLocation(QStandardPaths::StandardLocation type);
  

枚举：标准位置

QStandardPaths::StandardLocation 描述了各种路径的位置。

• 示例：获取桌面路径的显示名称：

  qDebug() << QStandardPaths::displayName(QStandardPaths::DesktopLocation);  // 输出: "Desktop"
  

• 示例：获取桌面的可写位置：

  qDebug() << QStandardPaths::writableLocation(QStandardPaths::DesktopLocation);  // 输出: "C:/Users/Maye/Desktop"
  

• 示例：获取数据目录的所有位置：

  qDebug() << QStandardPaths::standardLocations(QStandardPaths::DataLocation);
  

查找文件示例

• 查找可执行文件：

  qDebug() << QStandardPaths::findExecutable("calc.exe");  // 查找系统路径下的 calc.exe
  qDebug() << QStandardPaths::findExecutable("7z.exe", QStringList() << "D:\\MySoftWare\\7-Zip");
  

• 查找特定文件：

  qDebug() << QStandardPaths::locate(QStandardPaths::StandardLocation::DownloadLocation, "下拉.png");
  

4.4 QStorageInfo

QStorageInfo 类允许您检索有关磁盘卷的信息，例如可用空间、挂载点、标签和文件系统名称。

创建实例

您可以通过以下两种方式创建 QStorageInfo 实例：

1. 通过路径：将卷的挂载点路径作为构造函数参数传递。
2. 使用 setPath() 方法：在创建实例后设置路径。

静态方法

• 获取所有已挂载的文件系统：

  static QList<QStorageInfo> mountedVolumes();
  

缓存与刷新

QStorageInfo 会缓存检索到的信息。如果需要更新信息，可以调用 refresh() 方法使缓存无效。

示例代码

检索系统根卷信息

以下示例展示了如何检索关于系统根卷的常见信息并打印出来：

QStorageInfo storage = QStorageInfo::root();

qDebug() << "根路径：" << storage.rootPath();
if (storage.isReadOnly())
    qDebug() << "只读状态：" << storage.isReadOnly();

qDebug() << "卷名：" << storage.name();
qDebug() << "文件系统类型：" << storage.fileSystemType();
qDebug() << "总大小：" << storage.bytesTotal() / 1000 / 1000 << "MB";
qDebug() << "可用大小：" << storage.bytesAvailable() / 1000 / 1000 << "MB";

获取所有可用文件系统

以下示例展示了如何检索所有已挂载的文件系统，并跳过只读文件系统：

for (const QStorageInfo &storage : QStorageInfo::mountedVolumes()) {
    if (storage.isValid() && storage.isReady()) {
        if (!storage.isReadOnly()) {
            // 对可写文件系统进行处理
            qDebug() << "可写文件系统：" << storage.name();
        }
    }
}

用 refresh() 方法使缓存无效。

示例代码

检索系统根卷信息

以下示例展示了如何检索关于系统根卷的常见信息并打印出来：

QStorageInfo storage = QStorageInfo::root();

qDebug() << "根路径：" << storage.rootPath();
if (storage.isReadOnly())
    qDebug() << "只读状态：" << storage.isReadOnly();

qDebug() << "卷名：" << storage.name();
qDebug() << "文件系统类型：" << storage.fileSystemType();
qDebug() << "总大小：" << storage.bytesTotal() / 1000 / 1000 << "MB";
qDebug() << "可用大小：" << storage.bytesAvailable() / 1000 / 1000 << "MB";

获取所有可用文件系统

以下示例展示了如何检索所有已挂载的文件系统，并跳过只读文件系统：

for (const QStorageInfo &storage : QStorageInfo::mountedVolumes()) {
    if (storage.isValid() && storage.isReady()) {
        if (!storage.isReadOnly()) {
            // 对可写文件系统进行处理
            qDebug() << "可写文件系统：" << storage.name();
        }
    }
}