Qt 文件与路径处理笔记
文章目录
- 文件路径是什么？
- 特殊目录符号
- 不同系统的路径分隔符
- Qt 处理路径的四大核心类
- QFileInfo
- 创建 QFileInfo 对象
- 最常用的信息提取方法
- 特别注意：fileName() 对目录的行为
- QUrl — 统一资源定位符
- 创建 QUrl 的两种正确方式
- QUrl 与本地文件路径的相互转换
- 判断 QUrl 是否指向本地文件
- QDir 和 QStandardPaths
- QDir 常用操作
- QStandardPaths 获取系统标准路径
- 常见错误与避坑指南
- 常见错误现象及解决方法
- 处理中文路径
- 跨平台路径处理总结
文件路径是什么？
在电脑里，每个文件都有一个“地址”，叫做路径。
绝对路径：从磁盘的根目录开始写完整的位置。
例（Windows）：C:/Users/小明/图片/猫.jpg
例（Linux/Mac）：/home/小明/图片/猫.jpg
相对路径：相对于当前工作目录（程序正在运行的位置）的路径。
例：图片/猫.jpg（假设当前目录是/home/小明）
特殊目录符号
.→ 当前目录..→ 父目录（上一级）~→ 用户主目录（仅 Unix/Linux/macOS 的 Shell 中有效，Qt 中不自动识别，需用QDir::homePath()）
不同系统的路径分隔符
| 系统 | 分隔符 |
|---|---|
| Windows | \（反斜杠） |
| Linux/macOS | /（正斜杠） |
跨平台开发的黄金法则：在代码中永远使用正斜杠/，Qt 会在需要时自动转换为系统原生分隔符。
Qt 处理路径的四大核心类
| 类名 | 一句话作用 |
|---|---|
QDir | 操作目录：创建、删除、遍历、路径拼接等 |
QFileInfo | 获取文件的元信息（大小、后缀、修改时间等） |
QUrl | 统一处理网络地址（http://）和本地文件（file://） |
QStandardPaths | 获取系统标准文件夹（桌面、文档、App数据目录） |
QFileInfo
QFileInfo不打开文件，只读取文件的属性（元数据）。
使用前需要#include <QFileInfo>。
创建 QFileInfo 对象
QFileInfoinfo("/home/user/document.txt");// 直接给路径字符串最常用的信息提取方法
假设路径为：C:/我的音乐/周杰伦/晴天.mp3
| 方法 | 返回值 | 示例输出 |
|---|---|---|
fileName() | 文件名（含扩展名） | "晴天.mp3" |
baseName() | 文件名（不含扩展名） | "晴天" |
suffix() | 扩展名（不含点） | "mp3" |
completeSuffix() | 完整扩展名（用于 tar.gz 等情况） | 若为"archive.tar.gz"→"tar.gz" |
path() | 文件所在目录（不含文件名） | "C:/我的音乐/周杰伦" |
absoluteFilePath() | 绝对路径 | "C:/我的音乐/周杰伦/晴天.mp3" |
size() | 文件大小（字节） | 3456789 |
lastModified() | 最后修改时间 | QDateTime对象 |
isFile() | 是否是文件 | true/false |
isDir() | 是否是目录 | true/false |
exists() | 文件或目录是否存在 | true/false |
特别注意：fileName() 对目录的行为
QFileInfodirInfo("C:/我的音乐/周杰伦");// 这是一个目录qDebug()<<dirInfo.fileName();// 输出 "" (空字符串！)原因：fileName()取的是“最后一个分隔符之后的内容”。对于目录路径，Qt 会将其末尾的/忽略掉，导致没有内容可返回。
因此，不要用fileName()获取文件夹名称！获取文件夹名称的正确方法：
QDirdir("C:/我的音乐/周杰伦");QString folderName=dir.dirName();// "周杰伦"QUrl — 统一资源定位符
QUrl原本是为网址设计的（如https://qt.io），但它也可以优雅地处理本地文件。
很多 Qt 类（如QImage、QMediaPlayer、QFileDialog）都接受QUrl作为输入，因此学会用它很有必要。
创建 QUrl 的两种正确方式
| 场景 | 正确写法 |
|---|---|
| 网络地址 | QUrl url("https://example.com/pic.jpg"); |
| 本地文件路径 | QUrl url = QUrl::fromLocalFile("C:/Users/小明/照片.jpg"); |
❌错误示范：直接把本地路径字符串传给 QUrl 构造函数
QUrlwrong("C:/Users/小明/照片.jpg");// 缺少 file:// 协议，Qt 可能会误解✅正确示范：
QUrl right=QUrl::fromLocalFile("C:/Users/小明/照片.jpg");// right.toString() 会返回 "file:///C:/Users/小明/照片.jpg"QUrl 与本地文件路径的相互转换
| 转换方向 | 函数 |
|---|---|
| 本地路径 → QUrl | QUrl::fromLocalFile(路径) |
| QUrl → 本地路径 | .toLocalFile() |
QString path="D:/doc/readme.txt";QUrl url=QUrl::fromLocalFile(path);qDebug()<<url.toString();// "file:///D:/doc/readme.txt"QString original=url.toLocalFile();qDebug()<<original;// "D:/doc/readme.txt" （还原成本地路径）判断 QUrl 是否指向本地文件
if(url.isLocalFile()){QString filePath=url.toLocalFile();// 接下来可以用 QFileInfo 分析这个文件}QDir 和 QStandardPaths
QDir 常用操作
#include<QDir>// 1. 路径拼接（自动处理分隔符）QDirdir("C:/Users");QString full=dir.filePath("小明/图片/猫.jpg");// "C:/Users/小明/图片/猫.jpg"// 2. 创建目录dir.mkdir("新文件夹");// 3. 遍历目录下所有 .txt 文件QStringList filters;filters<<"*.txt";QStringList files=dir.entryList(filters);QStandardPaths 获取系统标准路径
#include<QStandardPaths>// 获取用户的“文档”文件夹（跨平台）QString docs=QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation);// Windows: C:/Users/用户名/Documents// Linux: /home/用户名/Documents// 获取应用程序专用的数据存储目录（强烈推荐存配置文件、数据库等）QString appData=QStandardPaths::writableLocation(QStandardPaths::AppLocalDataLocation);// Windows: C:/Users/用户名/AppData/Local/你的程序名// Linux: /home/用户名/.local/share/你的程序名常见错误与避坑指南
常见错误现象及解决方法
| 错误现象 | 可能原因 | 解决办法 |
|---|---|---|
QFileInfo::exists()返回false，但文件确实存在 | 用了相对路径，而当前工作目录不是你想象的那个 | 打印QDir::currentPath()查看工作目录；改用绝对路径或QCoreApplication::applicationDirPath()组合路径 |
想获取文件夹名，用了QFileInfo::fileName()得到空字符串 | fileName()对目录会返回空 | 改用QDir(dirPath).dirName() |
QUrl::toLocalFile()返回空字符串 | 这个QUrl不是本地文件（例如是 http 地址） | 先用isLocalFile()判断 |
直接给QUrl构造函数传本地路径，图片/视频无法打开 | 缺少file://协议头 | 使用QUrl::fromLocalFile() |
在 Windows 下用了反斜杠\，Qt 不识别 | Qt 要求路径中使用正斜杠/ | 使用QDir::fromNativeSeparators()转换，或手写/ |
认为QFileInfo能打开并读写文件 | 错误，QFileInfo只读元数据，不打开文件 | 读写文件用QFile类 |
处理中文路径
Qt 内部使用 UTF-8 编码，通常能正确处理中文路径。但在 Windows 上，如果遇到乱码问题，可以尝试：
QString path=QString::fromLocal8Bit("C:/中文路径/文件.txt");// 或者确保源代码文件保存为 UTF-8 with BOM (Windows)跨平台路径处理总结
- 永远使用正斜杠
/写路径，Qt 会帮你处理平台差异。 - 使用
QStandardPaths获取系统标准目录 - 不要手动拼接路径字符串，使用
QDir（QDir::filePath()）进行目录操作和路径拼接 - 需要文件信息 → 用
QFileInfo；，而不是直接操作字符串 - 需要网络/本地统一地址 → 用
QUrl。