Qt开发：QDir详解

TechNomad

已于 2025-04-16 21:54:41 修改

阅读量574

点赞数 3

分类专栏： Qt初阶教程文章标签： qt

于 2025-04-13 11:23:01 首次发布

本文链接：https://blog.youkuaiyun.com/TechNomad/article/details/147103351

版权

Qt初阶教程专栏收录该内容

45 篇文章

订阅专栏

文章目录

一、基本概念

QDir 提供了一个接口来访问文件系统中的目录。通过它，可以：

获取当前目录路径
设置和改变当前目录
列出目录下的文件和子目录
创建、删除目录
获取标准路径（如主目录、临时目录等）

二、QDir的常用构造函数

2.1 QDir(const QString &path = QString())

说明：
path：目录路径，如果为空（默认），则表示当前工作目录。

示例：

QDir dir1;                        // 当前工作目录
QDir dir2("/home/user");          // 指定目录
qDebug() << dir2.absolutePath();  // 输出：/home/user

2.2 QDir(const QDir &dir)

说明：
拷贝构造函数，创建一个与现有 QDir 对象相同的新对象。通常用于函数传参或局部复制。

示例：

QDir original("/home/user/Documents");
QDir copyDir(original);  // 拷贝构造
qDebug() << copyDir.path();  // 输出：/home/user/Documents

2.3 QDir(const QString &path, const QString &nameFilter, QDir::SortFlags sort = SortFlags(Name | IgnoreCase), QDir::Filters filters = AllEntries)
这个构造函数不仅创建了一个 QDir 对象，还立即设置好目录路径、名称过滤器、排序规则以及过滤条件，适合快速获取文件/目录列表。

参数详解：
const QString &path

含义：要操作的目录路径。
示例：“/home/user/Documents”，或 “C:/MyProject”（Windows）
说明：可以是绝对路径或相对路径。

const QString &nameFilter

含义：名称过滤器，用于筛选哪些文件/目录会被包含。
示例：“.cpp"：匹配所有 .cpp 文件；".jpg;.png"：匹配 .jpg 和 .png 图片；"”：匹配所有文件/目录

注意：多个过滤器使用分号 ; 分隔。

QDir::SortFlags sort

含义：排序方式，默认是 QDir::Name | QDir::IgnoreCase（按名称排序，忽略大小写）。

常用取值：
在这里插入图片描述
示例：

QDir::SortFlags sort = QDir::Time | QDir::Reversed;

QDir::Filters filters

含义：用于筛选返回的项目类型（如文件、目录、隐藏项等）

常用取值：
在这里插入图片描述

使用示例：

QDir dir("/home/user/Documents", "*.txt",
         QDir::Time | QDir::Reversed,
         QDir::Files | QDir::NoDotAndDotDot);

QStringList list = dir.entryList();
for (const QString &file : list) {
    qDebug() << file;
}

三、常用操作目录的函数

3.1 QString absoluteFilePath(const QString &fileName) const
作用：这个函数的是将某个相对路径的文件名，转换为完整的绝对路径，并且基于当前的 QDir 对象路径进行解析。

参数详解：

fileName：相对于当前 QDir 的文件名或子路径，也可以是子目录下的文件名。
返回值：这个文件的完整绝对路径（QString）

示例 1：拼接路径

QDir dir("/home/user/Documents");
QString fullPath = dir.absoluteFilePath("report.txt");
qDebug() << fullPath; // 输出：/home/user/Documents/report.txt

示例 2：子目录文件

QDir dir("/var/log");
QString fullPath = dir.absoluteFilePath("apache2/access.log");
qDebug() << fullPath; // 输出："/var/log/apache2/access.log"

注意事项：

它不会判断这个文件是否存在，它只是做路径拼接和规范化。
路径拼接推荐优先使用 absoluteFilePath() 而不是直接字符串连接，比如 dir.path() + “/” + filename，因为它会自动处理 /、路径规范等问题。

3.2 QString QDir::absolutePath() const
作用：absolutePath() 用于返回当前 QDir 对象所代表目录的绝对路径。它不会解析符号链接（symlink）。路径中可能包含 … 或 .（未规范化）。

示例 1：相对路径转绝对路径

QDir dir("data");  // 相对路径
qDebug() << dir.path();           // "data"
qDebug() << dir.absolutePath();   // "/home/user/project/data"（视运行环境而定）

示例 2：设置路径后获取绝对路径

QDir dir;
dir.setPath("../logs");
qDebug() << dir.absolutePath();  // 可能输出 "/home/user/logs"

示例 3：当前工作目录的绝对路径

QDir currentDir = QDir::current();
qDebug() << currentDir.absolutePath();  // 获取当前工作目录的完整路径

3.3 QString QDir::canonicalPath() const
作用：返回当前目录的规范化绝对路径（canonical path）；也就是解析符号链接（symlinks）、消除 .（当前目录）和 …（上级目录）、返回标准路径字符串。如果路径不存在，则返回的是空字符串。

示例 1：标准化路径

QDir dir("/home/user/../user/docs");
qDebug() << dir.absolutePath();    // 输出：/home/user/../user/docs
qDebug() << dir.canonicalPath();   // 输出：/home/user/docs

示例 2：解析符号链接
假设 /home/user/logs 是 /var/log 的符号链接：

QDir dir("/home/user/logs");
qDebug() << dir.canonicalPath();  // 输出：/var/log

示例 3：路径不存在时返回空

QDir dir("some/nonexistent/path");
qDebug() << dir.canonicalPath();  // 输出："" （空字符串）

3.4 bool QDir::cd(const QString &dirName)
作用：改变当前 QDir 对象所表示的目录，进入一个子目录。如果进入成功，则返回 true，否则返回 false（比如目标目录不存在）。

示例 1：进入子目录

QDir dir("/home/user");

if (dir.cd("Documents")) {
    qDebug() << "Current path:" << dir.absolutePath(); // 输出：/home/user/Documents
} else {
    qDebug() << "Failed to enter Documents";
}

示例 2：进入多级目录

QDir dir("/home/user");

if (dir.cd("Documents/Projects/Qt")) {
    qDebug() << "Now in:" << dir.path(); // 输出：/home/user/Documents/Projects/Qt
} else {
    qDebug() << "Failed to enter path";
}

示例 3：配合 entryList() 动态进入目录

QDir dir("/home/user");

QStringList subDirs = dir.entryList(QDir::Dirs | QDir::NoDotAndDotDot);
for (const QString &sub : subDirs) {
    if (dir.cd(sub)) {
        qDebug() << "Now in:" << dir.absolutePath();
        dir.cdUp();  // 回到上级目录
    }
}

注意事项：

cd() 不会创建目录，只尝试切换到已有目录。
它改变的是 QDir 对象的内部状态（当前路径），不是系统的工作目录。
如果需要知道是否成功进入，可以立刻用 absolutePath() 打印验证。

3.5 bool QDir::cdUp()
作用：将当前的 QDir 路径切换到上一级目录（即“返回父目录”）。
返回值：true：成功返回上级目录；false：失败（比如当前目录已经是根目录 /，就无法再往上了）。

示例 1：从子目录返回上层

QDir dir("/home/user/Documents/Projects");

qDebug() << "当前目录：" << dir.absolutePath();  // 输出：/home/user/Documents/Projects

if (dir.cdUp()) {
    qDebug() << "上级目录：" << dir.absolutePath();  // 输出：/home/user/Documents
}

示例 2：连续返回多层

QDir dir("/home/user/Documents/Projects");

while (dir.cdUp()) {
    qDebug() << "回退到：" << dir.absolutePath();
}

示例 3：配合递归遍历使用
当你用 cd() 进入一个子目录后，可以用 cdUp() 回到上层继续处理其他子目录：

QDir dir("/start/path");

QStringList subDirs = dir.entryList(QDir::Dirs | QDir::NoDotAndDotDot);
for (const QString &subDir : subDirs) {
    if (dir.cd(subDir)) {
        qDebug() << "进入：" << dir.absolutePath();
        // 处理子目录中的内容...

        dir.cdUp();  // 回到原来的路径
    }
}

注意事项：

cdUp() 改变的是 QDir 对象内部的路径，不影响系统的“工作目录”。
如果你在 /（根目录），cdUp() 会返回 false，因为没有上层了。
一般用于目录遍历或“导航式路径操作”。

3.6 bool QDir::exists() const
作用：函数用来判断当前 QDir 对象所表示的目录是否存在。这个函数不关心是目录还是文件，它只判断路径是否有效。
返回值：true：当前目录（QDir 对象表示的目录）存在；false：当前目录不存在。

示例 1：判断目录是否存在

QDir dir("/home/user/Documents");

if (dir.exists()) {
    qDebug() << "目录存在！";
} else {
    qDebug() << "目录不存在！";
}

示例 2：判断文件夹路径是否存在

QDir dir("/home/user/NonExistentFolder");

if (dir.exists()) {
    qDebug() << "目录存在！";
} else {
    qDebug() << "目录不存在！";
}

示例 3：在创建目录之前检查是否存在

QDir dir("/home/user/NewDirectory");

if (!dir.exists()) {
    if (dir.mkpath(".")) {
        qDebug() << "目录创建成功！";
    } else {
        qDebug() << "目录创建失败！";
    }
} else {
    qDebug() << "目录已存在！";
}

注意事项：

exists() 只会检查路径是否存在，不关心路径是否是文件或目录。
它不会递归检查多级路径（即路径中的每一部分是否存在），它只检查最后一部分。

3.7 QString QDir::path() const
作用：返回 QDir 对象所表示的目录的路径，返回的是一个相对路径（相对于构造时给定的路径）。如果构造 QDir 时提供了路径，那么返回的是该路径。它不会返回绝对路径，而是返回当前 QDir 的原始路径。

示例 1：获取当前 QDir 对象的路径

QDir dir("/home/user/Documents");
qDebug() << "当前路径：" << dir.path(); // 输出：/home/user/Documents

示例 2：相对路径

QDir dir("data");  // 假设 "data" 是相对路径
qDebug() << "当前路径：" << dir.path(); // 输出：data

示例 3：检查当前路径和绝对路径的区别

QDir dir("/home/user");
qDebug() << "路径：" << dir.path();  // "/home/user"
qDebug() << "绝对路径：" << dir.absolutePath();  // "/home/user"

注意事项：

path() 返回的是你给 QDir 构造函数时的路径（无论是否是相对路径）。
如果你想获取目录的绝对路径，可以使用 absolutePath()。
path() 只是路径本身，不会涉及路径是否存在或文件是否有效。

3.8 void QDir::setPath(const QString &path)
作用：用于设置 QDir 对象的路径。该方法将 QDir 对象的路径更新为提供的路径。通过调用此方法，可以修改 QDir 对象所表示的目录。如果路径有效，QDir 对象会被更新为新的路径。如果路径无效，它不会产生错误，但 QDir 对象的路径会保持为未更新的路径。

示例 1：设置新的路径

QDir dir("/home/user");
qDebug() << "当前路径：" << dir.absolutePath();  // /home/user
// 设置新路径
dir.setPath("/home/user/Documents");
qDebug() << "新路径：" << dir.absolutePath();  // /home/user/Documents

示例 2：设置相对路径

QDir dir("data");
qDebug() << "当前路径：" << dir.path();  // data
// 设置相对路径
dir.setPath("newFolder");
qDebug() << "新路径：" << dir.path();  // newFolder

示例 3：在路径设置后检查有效性

QDir dir("/home/user");
qDebug() << "当前路径：" << dir.absolutePath();  // /home/user
// 设置路径
dir.setPath("/home/user/NonExistentDirectory"); // 路径不存在！
if (dir.exists()) {
    qDebug() << "路径存在！";
} else {
    qDebug() << "路径不存在！";
}

注意事项：

setPath() 不会自动检查路径的有效性，它只会设置路径为给定值。
设置路径后，可以通过 exists() 方法验证该路径是否有效。
setPath() 并不会改变文件系统中的实际目录，它只是改变 QDir 对象的路径。

3.9 bool QDir::isReadable() const
作用：用于检查当前 QDir 对象所表示的目录是否具有读取权限。
返回值：true：当前目录可以读取。false：当前目录不可读取，可能是因为没有权限或目录不存在。

示例 1：检查目录是否可读

QDir dir("/home/user/Documents");

if (dir.isReadable()) {
    qDebug() << "目录可读取";
} else {
    qDebug() << "目录不可读取";
}

示例 2：检查不可读目录

QDir dir("/home/user/RestrictedFolder");

if (dir.isReadable()) {
    qDebug() << "目录可读取";
} else {
    qDebug() << "目录不可读取";
}

示例 3：判断一个不存在的目录

QDir dir("/home/user/NonExistentDirectory");

if (dir.isReadable()) {
    qDebug() << "目录可读取";
} else {
    qDebug() << "目录不可读取";
}

注意事项：

isReadable() 只检查目录是否可读，并不关心该目录是否为空或包含文件。
如果目录没有读取权限或无法访问（例如没有适当的权限），该方法将返回 false。
此函数不区分目录是否存在，只有当目录存在且可访问时才返回 true。

4.0 QString QDir::dirName() const
作用：返回当前 QDir 对象路径中最末尾的目录名（也就是“当前目录的名称”）。它不会返回整个路径，只会返回最后一级的目录名（basename），非常类似于文件路径中的 basename() 操作。

示例 1：标准路径

QDir dir("/home/user/Documents");
qDebug() << "目录名：" << dir.dirName();  // 输出: "Documents"

示例 2：根目录

QDir dir("/");
qDebug() << "目录名：" << dir.dirName();  // 输出: ""

在根目录 / 情况下，dirName() 返回空字符串 “”，因为根目录没有上级名称。

示例 3：相对路径

QDir dir("myFolder/subFolder");
qDebug() << "目录名：" << dir.dirName();  // 输出: "subFolder"

示例 4：动态路径处理示例

QString path = "/home/user/Projects/Qt";
QDir dir(path);

qDebug() << "当前目录：" << dir.path();
qDebug() << "最后一级目录名：" << dir.dirName();  // 输出: "Qt"

注意事项：

dirName() 仅返回路径最后部分，不含 /。
如果路径以 / 结尾（如 /home/user/），它依然会正确返回最后一级目录名。
对于根目录 /，dirName() 会返回空字符串。

四、常用操作文件的函数

4.1 QString QDir::filePath(const QString &fileName) const
作用：用来将给定的文件名（或子目录名）拼接到当前目录路径后，返回一个完整路径字符串。也就是说，它将 QDir 当前的路径和传入的 fileName 合成一个完整的文件路径。
返回值：返回的是一个 QString 类型的路径字符串，表示：当前 QDir 路径 + “/” + fileName。

示例 1：拼接文件路径

QDir dir("/home/user/Documents");
QString file = dir.filePath("report.txt");
qDebug() << file;
// 输出: "/home/user/Documents/report.txt"

示例 2：拼接子目录路径

QDir dir("/home/user");
QString subFolder = dir.filePath("Downloads");
qDebug() << subFolder;
// 输出: "/home/user/Downloads"

示例 3：处理相对路径

QDir dir("data");
QString path = dir.filePath("images/pic.png");
qDebug() << path;
// 输出: "data/images/pic.png"

示例 4：和 QFile 配合使用打开文件

QDir dir("/etc");

QFile file(dir.filePath("hosts"));
if (file.open(QIODevice::ReadOnly)) {
    QTextStream in(&file);
    qDebug() << in.readLine();
    file.close();
}

注意事项：

filePath() 不会检查这个文件是否真的存在，它只是路径拼接。
如果 fileName 本身是绝对路径，那它就不会拼接，而直接返回这个绝对路径。
拼接时会自动处理 /，你不需要担心重复或缺失斜杠。

4.2 bool QDir::exists(const QString &name) const
作用：用于判断当前目录下是否存在一个指定名称的文件或子目录。与不带参数的 exists() 不同，它不是判断整个 QDir 所表示的路径是否存在，而是判断你传入的名字（可以是文件名或子目录名）是否存在于该目录下。
返回值：true：表示在当前 QDir 路径下，存在该名称的文件或目录。false：不存在该文件或目录。

示例 1：检查文件是否存在

QDir dir("/home/user/Documents");
if (dir.exists("report.txt")) {
    qDebug() << "文件存在！";
} else {
    qDebug() << "文件不存在！";
}

示例 2：检查子目录是否存在

QDir dir("/home/user");
if (dir.exists("Downloads")) {
    qDebug() << "子目录存在";
} else {
    qDebug() << "子目录不存在";
}

示例 3：结合 QDir::filePath() 使用

QDir dir("/var/log");

QString fileName = "syslog";
if (QFile::exists(dir.filePath(fileName))) {
    qDebug() << "日志文件存在";
}

注意事项：

这个函数是针对当前 QDir 所表示的目录下的文件或目录名。
不支持通配符，想做过滤请结合 entryList() 使用。
如果你传入的是相对路径（如 “images/photo.jpg”），它会照样查找，但更适合用 absoluteFilePath() 先构造完整路径再检查。

五、用于过滤目录或文件的处理函数

5.1 QFileInfoList QDir::entryInfoList(const QStringList &nameFilters,QDir::Filters filters = NoFilter,QDir::SortFlags sort = NoSort) const
作用：该函数用于获取目录中符合特定名称模式、过滤条件和排序规则的文件或子目录信息列表。返回一个 QFileInfoList（也就是 QFileInfo 对象的列表），每个对象包含一个文件/目录的详细信息。
返回值：返回 QFileInfoList：包含所有符合条件的 QFileInfo 对象，可用于获取文件名、路径、大小、修改时间等详细信息。

参数说明
在这里插入图片描述

常见过滤器（QDir::Filters）
在这里插入图片描述
常见排序方式（QDir::SortFlags）

示例 1：获取当前目录下的所有 .txt 文件

QDir dir("/home/user/Documents");

QFileInfoList fileList = dir.entryInfoList({"*.txt"}, QDir::Files);

for (const QFileInfo &fileInfo : fileList) {
    qDebug() << "文件名:" << fileInfo.fileName();
    qDebug() << "绝对路径:" << fileInfo.absoluteFilePath();
}

示例 2：获取所有子目录（排除 “.” 和 “…”）

QDir dir("/home/user");

QFileInfoList subDirs = dir.entryInfoList({}, QDir::Dirs | QDir::NoDotAndDotDot);

for (const QFileInfo &info : subDirs) {
    qDebug() << "子目录：" << info.fileName();
}

示例 3：获取文件并按修改时间排序（最新的排前面）

QDir dir("/var/log");

QFileInfoList logs = dir.entryInfoList({"*.log"}, QDir::Files, QDir::Time);

for (const QFileInfo &file : logs) {
    qDebug() << file.fileName() << "修改时间：" << file.lastModified();
}

5.2 QFileInfoList QDir::entryInfoList(QDir::Filters filters = QDir::NoFilter,QDir::SortFlags sort = QDir::NoSort) const
作用：这个版本的 entryInfoList() 用于列出当前目录中所有符合过滤条件的文件和目录项，并按指定方式排序。与另一个重载版本不同，它不使用文件名过滤器（即不按 *.txt 或 *.cpp 这种通配符筛选），而是列出符合指定类型和权限的所有项。
返回值：返回一个 QFileInfoList，每个 QFileInfo 对象表示一个文件或目录的信息，包括名称、路径、大小、权限、修改时间等。

参数说明
filters（类型：QDir::Filters）
在这里插入图片描述
sort（类型：QDir::SortFlags）

示例 1：列出当前目录中的所有文件

QDir dir("/home/user/Documents");

QFileInfoList files = dir.entryInfoList(QDir::Files);

for (const QFileInfo &info : files) {
    qDebug() << "文件：" << info.fileName();
}

示例 2：列出所有子目录（不包括 . 和 …）

QDir dir("/home/user");

QFileInfoList dirs = dir.entryInfoList(QDir::Dirs | QDir::NoDotAndDotDot);

for (const QFileInfo &info : dirs) {
    qDebug() << "子目录：" << info.fileName();
}

示例 3：按时间排序显示所有文件

QDir dir("/var/log");

QFileInfoList logs = dir.entryInfoList(QDir::Files, QDir::Time);

for (const QFileInfo &info : logs) {
    qDebug() << info.fileName() << "最后修改：" << info.lastModified();
}

示例 4：列出所有内容（文件+目录）

QDir dir("/my/project");

QFileInfoList entries = dir.entryInfoList(QDir::AllEntries | QDir::NoDotAndDotDot);

for (const QFileInfo &info : entries) {
    qDebug() << (info.isDir() ? "[目录]" : "[文件]") << info.fileName();
}

5.3 QStringList QDir::entryList(const QStringList &nameFilters,QDir::Filters filters = QDir::NoFilter,QDir::SortFlags sort = QDir::NoSort) const
作用：用于列出当前目录下，符合指定名称过滤器、过滤条件、排序规则的文件或子目录的名字列表（不含路径），返回的是一个 QStringList。相比 entryInfoList()，它只返回文件名/目录名的字符串，而不包含详细的文件信息（如大小、修改时间等）。
返回值：返回一个 QStringList，列表中是符合条件的文件名或目录名（不含完整路径）。不返回 “.” 和 “…”，除非未指定 QDir::NoDotAndDotDot。

参数说明
在这里插入图片描述

示例 1：获取当前目录下的 .cpp 和 .h 文件名

QDir dir("/home/user/project");

QStringList list = dir.entryList({"*.cpp", "*.h"}, QDir::Files);

for (const QString &name : list) {
    qDebug() << "文件：" << name;
}

示例 2：列出所有子目录

QDir dir("/home/user");

QStringList subDirs = dir.entryList({}, QDir::Dirs | QDir::NoDotAndDotDot);

for (const QString &name : subDirs) {
    qDebug() << "子目录：" << name;
}

示例 3：列出所有隐藏文件并按名称排序

QDir dir("/home/user");

QStringList hiddenFiles = dir.entryList({"*"}, QDir::Hidden | QDir::Files, QDir::Name);

for (const QString &name : hiddenFiles) {
    qDebug() << "隐藏文件：" << name;
}

常用的过滤器（QDir::Filters）
在这里插入图片描述

常用的排序方式（QDir::SortFlags）
在这里插入图片描述
5.4 QStringList QDir::entryList(QDir::Filters filters = QDir::NoFilter,QDir::SortFlags sort = QDir::NoSort) const
作用：用于列出当前目录中，满足过滤条件并按排序规则排列的文件/目录名称列表（不含路径）。它是 entryList() 的简化重载版本：不使用文件名过滤器（不限定 *.txt 或 *.cpp），而是返回当前目录中所有符合指定过滤器的文件或目录的名称（QStringList）。
返回值：返回 QStringList：包含符合条件的文件名或目录名（不含路径）。

示例 1：列出当前目录中所有文件名

QDir dir("/home/user/Documents");

QStringList files = dir.entryList(QDir::Files);

for (const QString &name : files) {
    qDebug() << "文件：" << name;
}

示例 2：列出所有子目录（不含 “.” 和 “…”）

QDir dir("/home/user");

QStringList subdirs = dir.entryList(QDir::Dirs | QDir::NoDotAndDotDot);

for (const QString &dirName : subdirs) {
    qDebug() << "子目录：" << dirName;
}

示例 3：列出所有隐藏文件并按名称排序

QDir dir("/home/user");

QStringList hiddenFiles = dir.entryList(QDir::Hidden | QDir::Files, QDir::Name);

for (const QString &file : hiddenFiles) {
    qDebug() << "隐藏文件：" << file;
}

六、常用的静态函数

6.1 static void QDir::addSearchPath(const QString &prefix,const QString &path)
作用：用于注册一个“搜索路径别名”，也叫虚拟路径前缀（prefix）。注册之后，在使用类似 “prefix:filename” 的路径时，Qt 会自动在你设置的真实路径中查找对应的文件。

参数说明
在这里插入图片描述
使用流程
注册前缀和实际路径：

QDir::addSearchPath("images", "/home/user/resources/images");

使用路径前缀访问资源：

QPixmap pixmap("images:logo.png");

Qt 会自动在 /home/user/resources/images/ 中查找 logo.png

示例 1：注册图片路径别名

QDir::addSearchPath("icons", "/usr/share/app/icons");
QIcon icon("icons:app.png");  // 自动转换为 /usr/share/app/icons/app.png

示例 2：配合 QPixmap 或 QImage 加载图片

QDir::addSearchPath("img", ":/assets/images");

QPixmap logo("img:logo.png");  // 实际是加载 ":/assets/images/logo.png"

示例 3：配合 QFile, QTextStream 读取文本

QDir::addSearchPath("config", "/etc/myapp/configs");

QFile file("config:default.ini");

if (file.open(QIODevice::ReadOnly | QIODevice::Text)) {
    QTextStream in(&file);
    qDebug() << "配置内容：" << in.readAll();
}

注意事项：

路径不会自动递归子目录，需要你自己管理。
如果注册了多个路径，可用 QDir::setSearchPaths(prefix, QStringList{…}) 注册多个备选路径。
addSearchPath 是静态函数，对整个程序全局生效。

6.2 static QString QDir::cleanPath(const QString &path)
QDir::cleanPath() 用于规范化路径字符串，会执行以下处理：

移除多余的 /（或 Windows 下的 \）
移除当前目录符号 “.”
简化父目录符号 “…”（如果可以的话）
保留绝对路径或相对路径的形式

这个函数不会验证路径是否真实存在，它只是对路径格式做“清洗”。

示例效果
在这里插入图片描述
示例 1：清理 UNIX 路径

QString rawPath = "/home/user/../docs/./myfile.txt";
QString clean = QDir::cleanPath(rawPath);

qDebug() << "清理后路径：" << clean;
// 输出: /home/docs/myfile.txt

示例 2：清理 Windows 风格路径（Qt 自动处理 \）

QString winPath = "C:\\Users\\Admin\\..\\Public\\./doc.txt";
QString clean = QDir::cleanPath(winPath);

qDebug() << "清理后路径：" << clean;
// 输出: C:/Users/Public/doc.txt

示例 3：结合 QDir 使用路径拼接和清理

QDir dir("/home/user");
QString fullPath = dir.filePath("../docs/./notes.txt");

QString clean = QDir::cleanPath(fullPath);

qDebug() << "最终路径：" << clean;
// 输出: /home/docs/notes.txt

6.3 static QDir QDir::current()
作用：返回当前工作目录（current working directory）对应的 QDir 对象。当前工作目录是指程序运行时，操作系统认为你“当前所在的目录”。它通常与程序启动的位置有关，但也可以通过 QDir::setCurrent() 修改。
返回值：返回一个 QDir 对象，表示当前工作目录。

示例 1：获取当前工作目录路径

QDir dir = QDir::current();
qDebug() << "当前工作目录：" << dir.absolutePath();

示例 2：列出当前目录下所有文件

QDir dir = QDir::current();

QStringList files = dir.entryList(QDir::Files);

for (const QString &file : files) {
    qDebug() << "文件：" << file;
}

示例 3：改变当前工作目录再获取

QDir::setCurrent("/home/user/projects");

QDir dir = QDir::current();
qDebug() << "现在的工作目录：" << dir.path();
// 输出: /home/user/projects

6.4 QString QDir::currentPath()
作用：返回程序当前的工作目录路径，即当前进程的工作目录的绝对路径。
返回值：返回一个 QString 类型的路径，表示程序的当前工作目录。这个路径是从程序启动时起就被设定的，除非通过 QDir::setCurrent() 修改。

示例 1：获取当前工作目录的路径

QString currentDir = QDir::currentPath();
qDebug() << "当前工作目录：" << currentDir;

示例 2：改变当前工作目录并获取新的路径

QDir::setCurrent("/home/user/projects");

QString newDir = QDir::currentPath();
qDebug() << "新的工作目录：" << newDir;
// 输出: /home/user/projects

6.5 static QFileInfoList QDir::drives()
作用：返回系统中所有可用的驱动器的列表，具体表现为 QFileInfoList，每个元素是一个 QFileInfo 对象，包含驱动器的相关信息。这个函数可以用于列出操作系统上的所有驱动器，帮助你检测系统中所有可用的磁盘设备或网络共享。

示例 1：列出所有驱动器的路径

QFileInfoList drivesList = QDir::drives();

for (const QFileInfo &drive : drivesList) {
    qDebug() << "驱动器路径：" << drive.absoluteFilePath();
}

这个代码会列出操作系统中所有的驱动器路径，例如 C:/, D:/，或者在 Linux 系统中可能是 /mnt 或其他挂载点。

示例 2：检查每个驱动器的类型和可用性

QFileInfoList drivesList = QDir::drives();

for (const QFileInfo &drive : drivesList) {
    qDebug() << "驱动器：" << drive.absoluteFilePath();
    qDebug() << "是否为目录：" << drive.isDir();
}

这个示例会输出每个驱动器的路径，并检查它是否是目录或设备。对于 Windows 系统，可能会标记如 C:/ 是设备，而其他挂载点如 D:/ 可能是设备。

示例 3：列出可用的驱动器并进一步处理

QFileInfoList drivesList = QDir::drives();

for (const QFileInfo &drive : drivesList) {
    // 输出驱动器的路径
    qDebug() << "驱动器路径：" << drive.absoluteFilePath();

    // 检查是否是可读的
    if (drive.isReadable()) {
        qDebug() << drive.absoluteFilePath() << "是可读的";
    }
}

6.6 static QString QDir::fromNativeSeparators(const QString &pathName)
作用：fromNativeSeparators() 的主要作用是将操作系统特有的路径分隔符（Windows 下是 \，Unix 系统下是 /）统一为 /（正斜杠）。
这在跨平台开发中非常有用，特别是当你需要在不同操作系统间共享或传输文件路径时，确保路径格式一致。

示例 1：转换 Windows 路径分隔符
在 Windows 上，路径通常使用反斜杠 \，使用 fromNativeSeparators() 可以将它们转换为正斜杠 /：

QString windowsPath = "C:\\Users\\User\\Documents\\file.txt";
QString normalizedPath = QDir::fromNativeSeparators(windowsPath);

qDebug() << "标准路径：" << normalizedPath;
// 输出: C:/Users/User/Documents/file.txt

示例 2：转换 Linux 路径分隔符
虽然 Linux 路径默认使用正斜杠 /，但你仍然可以使用该函数来处理已经使用反斜杠 \ 的路径（例如通过某些应用程序处理过的路径）：

QString linuxPath = "/home/user\\documents\\file.txt";  // 假设这个路径中有 Windows 风格的反斜杠
QString normalizedPath = QDir::fromNativeSeparators(linuxPath);

qDebug() << "标准路径：" << normalizedPath;
// 输出: /home/user/documents/file.txt

示例 3：在跨平台项目中使用
当你开发跨平台应用程序时，可能会使用操作系统相关的路径字符串。使用 fromNativeSeparators() 可以确保路径在不同平台上的一致性：

QString path = "C:\\Program Files\\MyApp";  // Windows 路径
QString unifiedPath = QDir::fromNativeSeparators(path);

qDebug() << "跨平台统一路径：" << unifiedPath;
// 输出: C:/Program Files/MyApp

6.7 static QDir QDir::home()
作用：
返回一个 QDir 对象，代表当前用户的主目录。这个目录根据不同操作系统，路径也不同。

Windows：C:\Users<用户名>
Linux/macOS：/home/<用户名> 或 /Users/<用户名>

示例 1：列出主目录下的所有文件和文件夹

QDir homeDir = QDir::home();
QStringList entries = homeDir.entryList(QDir::AllEntries | QDir::NoDotAndDotDot);

for (const QString &entry : entries) {
    qDebug() << entry;
}

示例 2：判断主目录下是否存在某个文件夹

QDir homeDir = QDir::home();

if (homeDir.exists("Documents")) {
    qDebug() << "用户的主目录中存在 Documents 文件夹";
}

示例 3：在主目录中创建子文件夹

QDir homeDir = QDir::home();

if (!homeDir.exists("MyAppData")) {
    homeDir.mkdir("MyAppData");
    qDebug() << "主目录中已创建文件夹 MyAppData";
}

注意事项：

和 QDir::homePath() 的区别：homePath() 返回的是字符串路径，home() 返回的是 QDir 类型，更适合做目录操作。
返回的是用户级目录，而不是程序运行目录（运行目录是 QDir::current()）

6.8 static QString QDir::homePath()
作用：用于返回当前用户的主目录路径（Home Directory）。

示例 1：打印主目录路径

QString homeDir = QDir::homePath();
qDebug() << "主目录路径：" << homeDir; // Windows: "C:/Users/Alice"，Linux: "/home/alice"

示例 2：访问主目录下的文件

QString filePath = QDir::homePath() + "/myfile.txt";
QFile file(filePath);

if (file.open(QIODevice::ReadOnly)) {
    qDebug() << "成功打开主目录中的文件：" << filePath;
}

示例 3：创建主目录中的文件夹

QDir dir(QDir::homePath());

if (!dir.exists("MyFolder")) {
    dir.mkdir("MyFolder");
    qDebug() << "主目录中新建了文件夹 MyFolder";
}

注意事项：

返回的路径不带结尾的 /，拼接时记得加 / 或使用 QDir::filePath()。
不等于程序的工作目录（那是 QDir::currentPath()）。
和 QStandardPaths::writableLocation(QStandardPaths::HomeLocation) 类似，但后者是更通用的方式。

6.9 static bool QDir::isAbsolutePath(const QString &path)
作用：用于判断给定的路径字符串是否是绝对路径。
返回值：若 path 是绝对路径，返回 true，否则返回 false。

绝对路径：从根目录开始的完整路径，能唯一确定一个文件或目录的位置。

Windows 示例：C:/Users/yourname/file.txt
Linux/macOS 示例：/home/yourname/file.txt

相对路径：相对于当前目录的路径。

示例：./data/test.txt 或 …/logs/

示例 1：判断路径是否为绝对路径

QString path1 = "/home/user/docs";
QString path2 = "data/output.txt";

qDebug() << QDir::isAbsolutePath(path1); // Linux/macOS 上返回 true
qDebug() << QDir::isAbsolutePath(path2); // 返回 false

示例 2：在 Windows 系统中判断

QString winPath = "C:\\Users\\Alice\\Desktop\\file.txt";
QString relPath = "files\\data.txt";

qDebug() << QDir::isAbsolutePath(winPath); // 返回 true
qDebug() << QDir::isAbsolutePath(relPath); // 返回 false

示例 3：配合 QDir::absoluteFilePath()

QString rel = "images/logo.png";

if (!QDir::isAbsolutePath(rel)) {
    QString absPath = QDir::current().absoluteFilePath(rel);
    qDebug() << "转换后的绝对路径：" << absPath;
}

6.10.1 static bool QDir::isRelativePath(const QString &path)
作用：用来判断给定路径字符串是否是相对路径。

如果路径是相对于当前目录的（没有根目录或盘符等信息），那么就是相对路径，返回 true。
如果路径是以根目录、盘符等开头的完整路径，就是绝对路径，返回 false。

示例 1：基本判断

QString path1 = "images/pic.png";          // 相对路径
QString path2 = "/home/user/pic.png";      // Linux/macOS 绝对路径
QString path3 = "C:/Users/Alice/pic.png";  // Windows 绝对路径

qDebug() << QDir::isRelativePath(path1); // true
qDebug() << QDir::isRelativePath(path2); // false
qDebug() << QDir::isRelativePath(path3); // false

示例 2：配合 QDir::absoluteFilePath()

QString inputPath = "docs/report.pdf";

if (QDir::isRelativePath(inputPath)) {
    QString fullPath = QDir::current().absoluteFilePath(inputPath);
    qDebug() << "转换后的绝对路径：" << fullPath;
}

注意事项：

路径中的 . 或 … 不影响函数判断，它只看路径是不是从根开始。“…/folder” 是相对路径，返回 true。
如果从 QFileDialog 中获取路径，它通常是绝对路径。

6.10.2 static QChar QDir::listSeparator()
作用：返回操作系统中用于分隔多个路径字符串的字符（QChar 类型）。
返回值：系统路径字符串中使用的分隔符字符。

这个分隔符通常在多个路径拼接成一个字符串时使用，比如环境变量中的 PATH：
在这里插入图片描述
典型用途：

用于分隔多个路径，例如：设置搜索路径、构建环境变量中的路径字符串。
保证跨平台兼容性，不用手动写死 ; 或 :。

示例 1：获取系统路径分隔符

QChar sep = QDir::listSeparator();
qDebug() << "系统路径分隔符是：" << sep; // Windows: ';'，Linux: ':'

示例 2：拼接多个路径字符串

QStringList paths = {
    "/usr/bin",
    "/usr/local/bin",
    QDir::homePath() + "/.myapp/bin"
};

QString fullPath = paths.join(QDir::listSeparator());
qDebug() << "拼接后的路径字符串：" << fullPath; // 在 Linux 输出示例："/usr/bin:/usr/local/bin:/home/user/.myapp/bin"

注意事项：

不是文件夹路径中的目录分隔符（目录分隔符是 / 或 \，用 QDir::separator() 处理）。
这个分隔符用于多个路径之间（list 中），比如环境变量中，两个目录之间的“分隔字符”。
QDir::listSeparator() 提供了操作系统路径列表的标准分隔符，确保路径拼接在 Windows、Linux、macOS 上都能正确解析，是构建多路径字符串的利器。

6.10.3 static bool QDir::match(const QStringList &filters, const QString &fileName)
作用：用于判断某个文件名是否匹配某个通配符过滤规则（filter）。用来做类似 *.txt、image_??.png 这种简单的文件名匹配。

支持标准的通配符匹配方式：*：匹配任意个字符。
?：匹配一个字符

返回值：返回 true：表示文件名匹配过滤规则。返回 false：表示不匹配。

参数说明：
在这里插入图片描述

示例 1：匹配 .txt 文件

QString filter = "*.txt";
QString file1 = "readme.txt";
QString file2 = "image.png";

qDebug() << QDir::match(filter, file1); // true
qDebug() << QDir::match(filter, file2); // false

示例 2：匹配指定格式的文件名

QString filter = "image_??.jpg";  // 匹配像 image_01.jpg、image_ab.jpg
QString file1 = "image_01.jpg";
QString file2 = "image_123.jpg";

qDebug() << QDir::match(filter, file1); // true
qDebug() << QDir::match(filter, file2); // false

注意事项：
区分大小写（默认情况下）。如果你希望不区分，可以先转换大小写再比较：

QDir::match("*.TXT", file.toUpper())

如果你要用多个通配符匹配，可以用 QStringList 版本的重载。

6.10.4 static bool QDir::match(const QStringList &filters, const QString &fileName)
作用：用于判断一个文件名 fileName 是否匹配多个通配符规则中的任意一个。
返回值：true：表示 fileName 匹配了 filters 中的任意一个通配符；false：表示没有匹配任何一个通配符。

参数说明：
在这里插入图片描述
示例 1：匹配多个扩展名的文件

QStringList filters = {"*.cpp", "*.h", "*.txt"};

qDebug() << QDir::match(filters, "main.cpp");   // true
qDebug() << QDir::match(filters, "header.h");   // true
qDebug() << QDir::match(filters, "readme.txt"); // true
qDebug() << QDir::match(filters, "image.png");  // false

示例 2：与用户自定义过滤器配合使用

QStringList userFilters = {"log_*.txt", "error_??.log"};
QString fileName = "error_01.log";

if (QDir::match(userFilters, fileName)) {
    qDebug() << "匹配成功：" << fileName;
} else {
    qDebug() << "不匹配";
}

常用通配符语法：
在这里插入图片描述
6.10.4 static QDir QDir::root()
作用：返回的是表示系统根目录的 QDir 对象。

在 Windows 上：返回的是 C:/（或系统的主分区）。
在 Linux / macOS 上：返回的是 /。

这个函数通常用来在你需要从文件系统的最顶层开始查找、遍历或操作文件时使用。

示例代码：

QDir rootDir = QDir::root();

qDebug() << "根目录路径：" << rootDir.absolutePath();

// 遍历根目录下的文件/文件夹
QStringList list = rootDir.entryList(QDir::AllEntries | QDir::NoDotAndDotDot);
for (const QString &entry : list) {
    qDebug() << entry;
}

6.10.5 static QString QDir::rootPath()
作用：返回操作系统的根目录路径，即文件系统的顶层路径。

在 Windows 系统：通常是 “C:/”（或当前系统所在的分区）。
在 Linux/macOS 系统：是 “/”。

与 QDir::root() 返回一个 QDir 对象不同，rootPath() 返回的是一个 QString 类型的路径字符串。

示例代码：

QString rootPath = QDir::rootPath();
qDebug() << "根目录路径是：" << rootPath;

输出（Windows）：

根目录路径是："C:/"

输出（Linux/macOS）：

根目录路径是："/"

6.10.6 static QStringList QDir::searchPaths(const QString &prefix)
作用：返回通过 QDir::addSearchPath() 为某个路径前缀 prefix 设置的搜索路径列表。
返回值：返回一个 QStringList，其中包含与该前缀关联的所有路径，如果前缀不存在，返回空列表。

为什么有用？
例如你可以定义一个叫 “icons” 的路径前缀：

QDir::addSearchPath("icons", "/usr/share/app/icons");

之后你就可以通过以下方式加载图像或文件：

QPixmap pixmap("icons:save.png");

Qt 会自动查找 /usr/share/app/icons/save.png。可以通过 searchPaths(“icons”) 查看这个前缀实际指向的路径。

示例 1：添加前缀并查询

QDir::addSearchPath("icons", "/usr/share/icons");
QDir::addSearchPath("icons", "/home/user/myicons");

QStringList paths = QDir::searchPaths("icons");

qDebug() << "icons 路径前缀包含：";
for (const QString &path : paths) {
    qDebug() << path;
}

输出：
在这里插入图片描述
示例 2：动态绑定资源路径

QDir::addSearchPath("resources", ":/resources");
QFile file("resources:config.json");

if (file.exists()) {
    qDebug() << "找到了资源配置文件";
}

6.10.7 static QChar QDir::separator()
作用：用来获取当前操作系统的目录分隔符字符。它常用于手动拼接路径，确保跨平台兼容，避免写死 / 或 \。

示例 1：打印当前系统的目录分隔符

QChar sep = QDir::separator();
qDebug() << "当前平台目录分隔符为：" << sep;

输出（Windows）：

当前平台目录分隔符为："\"

输出（Linux/macOS）：

当前平台目录分隔符为："/"

示例 2：构建路径（推荐用 QDir::filePath()，但也可以手动）

 QString basePath = "C:" + QString(QDir::separator()) + "Users" + QString(QDir::separator()) + "admin";
 qDebug() << "拼接后的路径：" << basePath;

输出：
在这里插入图片描述
6.10.8 static bool QDir::setCurrent(const QString &path)
作用：用于更改程序的当前工作目录。一旦设置成功，程序中使用的相对路径，都会基于这个目录进行解析。
返回值：true：设置成功（路径存在且可访问）；false：设置失败（路径无效或不存在）。

使用示例：

QString newPath = "C:/Users/Public";

if (QDir::setCurrent(newPath)) {
    qDebug() << "工作目录已设置为：" << QDir::currentPath();
} else {
    qDebug() << "设置失败，路径不存在：" << newPath;
}

示例：结合 QFile

// 改变当前目录
QDir::setCurrent("/home/user/documents");

// 使用相对路径打开文件
QFile file("data.txt");  // 实际路径为 /home/user/documents/data.txt

if (file.open(QIODevice::ReadOnly)) {
    qDebug() << "文件成功打开";
}

6.10.9 static void QDir::setSearchPaths(const QString &prefix, const QStringList &searchPaths)
作用：允许将一个逻辑路径前缀（prefix）绑定到多个真实路径（searchPaths）上。类似于 addSearchPath()，但这个函数一次性设置多个路径，会替换已有绑定。

参数说明：
在这里插入图片描述

示例 1：绑定前缀到多个目录

QStringList iconPaths;
iconPaths << "/usr/share/icons"
          << "/home/user/custom_icons";

QDir::setSearchPaths("icons", iconPaths);

// 使用前缀访问图标
QPixmap pixmap("icons:save.png");

if (!pixmap.isNull()) {
    qDebug() << "图标加载成功";
} else {
    qDebug() << "未找到图标";
}

示例 2：替换之前的路径绑定

// 初始绑定
QDir::addSearchPath("plugins", "/app/default_plugins");
// 替换绑定
QDir::setSearchPaths("plugins", QStringList() << "/home/user/my_plugins");

与 addSearchPath() 的区别：
在这里插入图片描述
注意事项：

使用该机制的前提是资源路径格式为：prefix:filename.ext。
搜索顺序按 QStringList 中的顺序来。
如果文件找不到，相关类（如 QPixmap, QFile, QImageReader）可能返回空对象或失败状态。

6.11.1 static QDir QDir::temp()
作用：用来获取系统的临时目录路径。

临时目录在各平台的位置：
在这里插入图片描述

示例 1：获取临时目录路径

QDir tempDir = QDir::temp();
qDebug() << "系统临时目录是：" << tempDir.absolutePath();

输出结果：
在这里插入图片描述
示例 2：构建临时文件完整路径

QString tempFilePath = QDir::temp().filePath("my_temp_file.txt");
qDebug() << "完整临时文件路径：" << tempFilePath;

输出:
在这里插入图片描述
6.11.2 static QString QDir::tempPath()
作用：返回当前系统平台上的临时文件目录路径，结果是一个 QString。

示例 1：打印临时目录路

QString tmp = QDir::tempPath();
qDebug() << "系统临时目录：" << tmp;

示例 2：创建一个临时文件

QString tempFilePath = QDir::tempPath() + QDir::separator() + "my_temp.txt";

QFile tempFile(tempFilePath);
if (tempFile.open(QIODevice::WriteOnly)) {
    tempFile.write("这是一个临时文件");
    tempFile.close();
    qDebug() << "写入成功：" << tempFilePath;
}

6.11.3 static QString QDir::toNativeSeparators(const QString &pathName)
作用：是用来将路径字符串中的分隔符转换成当前操作系统使用的“原生分隔符”。
它会将路径中的 / 或 \ 替换为本系统默认的路径分隔符。
在这里插入图片描述
示例 1：路径格式化

QString path = "/home/user/Documents/myfile.txt";
QString native = QDir::toNativeSeparators(path);

qDebug() << "原始路径：" << path;
qDebug() << "本地化路径：" << native;

在 Windows 上输出：

原始路径："/home/user/Documents/myfile.txt"
本地化路径："\\home\\user\\Documents\\myfile.txt"

示例 2：结合 QFile 使用（路径更直观）

QString path = QDir::currentPath() + "/data/log.txt";
qDebug() << "打开文件路径：" << QDir::toNativeSeparators(path);

对比函数：fromNativeSeparators()
在这里插入图片描述

七、完整实例代码

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QWidget>
#include <QListWidget>
#include <QListWidgetItem>
#include <QLineEdit> // 单行输入框/单行编辑框

#include <QDir>
#include <QFileInfoList> // 获取指定目录的基本数据信息

#include <QVBoxLayout>
#include <QStringList>

class MainWindow : public QWidget
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr) : QWidget(parent) {
        this->setWindowTitle("QDir类综合控件应用测试");
        this->setFixedSize(800, 600);

        m_pFileLineEdit = new QLineEdit("/", this);
        m_pFileListWidget = new QListWidget(this);

        m_pLayout = new QVBoxLayout(this);
        m_pLayout->addWidget(m_pFileLineEdit);
        m_pLayout->addWidget(m_pFileListWidget);

        connect(m_pFileListWidget, &QListWidget::itemDoubleClicked, this, &MainWindow::dispDirShow);

        QString root = "/";
        QDir rootDir(root);
        QStringList strList;
        strList << "*";


        QFileInfoList list = rootDir.entryInfoList(strList);

        dispFileInfoList(list);
    }

    // 显示目录和文件所对应的图标
    void dispFileInfoList(QFileInfoList list) {
        m_pFileListWidget->clear();

        for (int i = 0; i < list.count(); i++) {
            QFileInfo tempFileInfo = list.at(i);
            if (tempFileInfo.isDir()) {
                // 判断是否是目录
                QIcon ico("./dir.jpg");
                QString fileName = tempFileInfo.fileName();
                QListWidgetItem *temp = new QListWidgetItem(ico, fileName);
                m_pFileListWidget->addItem(temp);
            } else if (tempFileInfo.isFile()) {
                // 判断是否是文件
                QIcon ico("./file.jpg");
                QString fileName = tempFileInfo.fileName();
                QListWidgetItem *temp = new QListWidgetItem(ico, fileName);
                m_pFileListWidget->addItem(temp);
            }
        }
    }

public slots:
    void dispDir(QDir dir) {
        QStringList strList;
        strList << "*";

        QFileInfoList fileInfoList = dir.entryInfoList(strList, QDir::AllEntries, QDir::DirsFirst);

        dispFileInfoList(fileInfoList);
    }

    void dispDirShow(QListWidgetItem *item) {
        QDir dir;
        QString str = item->text();

        dir.setPath(m_pFileLineEdit->text());
        dir.cd(str);

        m_pFileLineEdit->setText(dir.absolutePath());

        dispDir(dir);
    }

private:
    QLineEdit *m_pFileLineEdit;
    QListWidget *m_pFileListWidget;
    QVBoxLayout *m_pLayout;
};
#endif // MAINWINDOW_H

在这里插入图片描述