QStandardPaths Class
QStandardPaths 类提供了访问标准路径的方法。更多
| 头文件： | #include <QStandardPaths> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
公共类型
| enum | LocateOption { LocateFile, LocateDirectory } |
| flags | LocateOptions |
| enum | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, MusicLocation, …, GenericStateLocation } |
静态公共成员
| QString | displayName(QStandardPaths::StandardLocation type) |
| QString | findExecutable(const QString &executableName, const QStringList &paths = QStringList()) |
| QString | locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| QStringList | locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| void | setTestModeEnabled(bool testMode) |
| QStringList | standardLocations(QStandardPaths::StandardLocation type) |
| QString | writableLocation(QStandardPaths::StandardLocation type) |
成员类型文档
枚举 QStandardPaths::LocateOption
flags QStandardPaths::LocateOptions
该枚举描述了可用于控制QStandardPaths::locate 和QStandardPaths::locateAll 行为的不同标志。
| 常量 | 值 | 说明 |
|---|---|---|
QStandardPaths::LocateFile | 0x0 | 仅返回文件 |
QStandardPaths::LocateDirectory | 0x1 | 仅返回目录 |
LocateOptions 类型是QFlags<LocateOption> 的类型定义。它存储 LocateOption 值的 OR 组合。
enum QStandardPaths::StandardLocation
该枚举描述了可使用QStandardPaths::writableLocation 、QStandardPaths::standardLocations 和QStandardPaths::displayName 等方法查询的不同位置。
该枚举中的某些值代表用户配置。这些枚举值将在不同的应用程序中返回相同的路径，因此可用于与其他应用程序共享数据。其他值则是本应用程序的特定值。下表中的每个枚举值都说明了是应用程序特定的还是通用的。
特定于应用程序的目录应假定其他应用程序无法访问。因此，即使由同一用户运行，放在那里的文件也可能无法被其他应用程序读取。另一方面，通用目录应假定该用户运行的所有应用程序都能访问，但仍应假定其他用户的应用程序无法访问。
与其他用户的数据交换不属于QStandardPaths 的范围。
| 常数 | 值 | 说明 |
|---|---|---|
QStandardPaths::DesktopLocation | 0 | 返回用户的桌面目录。这是一个通用值。在没有桌面概念的系统中，该值与 QStandardPaths::HomeLocation 相同。 |
QStandardPaths::DocumentsLocation | 1 | 返回包含用户文件的目录。这是一个通用值。返回的路径永远不会为空。 |
QStandardPaths::FontsLocation | 2 | 返回包含用户字体的目录。这是一个通用值。请注意，安装字体可能需要额外的特定平台操作。 |
QStandardPaths::ApplicationsLocation | 3 | 返回包含用户应用程序（可执行文件、应用程序捆绑包或其快捷方式）的目录。这是一个通用值。请注意，安装应用程序可能需要额外的特定平台操作。此目录中的文件、文件夹或快捷方式是特定于平台的。 |
QStandardPaths::MusicLocation | 4 | 返回包含用户音乐或其他音频文件的目录。这是一个通用值。如果不存在专门用于音乐文件的目录，则会返回用于存储用户文件的合理后备目录。 |
QStandardPaths::MoviesLocation | 5 | 返回包含用户电影和视频的目录。这是一个通用值。如果没有专门的电影文件目录，则会返回用于存储用户文件的合理后备目录。 |
QStandardPaths::PicturesLocation | 6 | 返回包含用户图片或照片的目录。这是一个通用值。如果不存在专门用于图片文件的目录，则返回用于存储用户文件的合理后备目录。 |
QStandardPaths::TempLocation | 7 | 返回可存储临时文件的目录。返回值可能是特定于应用程序的，也可能是该用户的其他应用程序共享的，甚至可能是全系统的。返回的路径永远不会为空。 |
QStandardPaths::HomeLocation | 8 | 返回用户的主目录（与QDir::homePath() 相同）。在 Unix 系统中，它等于 HOME 环境变量。该值可能是通用的，也可能是应用程序特定的，但返回的路径绝不会为空。 |
QStandardPaths::AppLocalDataLocation | 9 | 返回 Windows 操作系统上的本地设置路径。在所有其他平台上，返回值与 AppDataLocation 相同。此枚举值在 Qt 5.4 中添加。 |
QStandardPaths::CacheLocation | 10 | 返回应写入用户特定非必要（缓存）数据的目录位置。这是一个特定于应用程序的目录。返回的路径永远不会为空。 |
QStandardPaths::GenericCacheLocation | 15 | 返回应写入跨应用程序共享的用户特定非必要（缓存）数据的目录位置。这是一个通用值。请注意，如果系统没有共享缓存的概念，返回的路径可能为空。 |
QStandardPaths::GenericDataLocation | 11 | 返回可存储跨应用程序共享的持久性数据的目录位置。这是一个通用值。返回的路径永远不会为空。 |
QStandardPaths::RuntimeLocation | 12 | 返回写入运行时通信文件（如 Unix 本地套接字）的目录位置。这是一个通用值。在某些系统中，返回的路径可能为空。 |
QStandardPaths::ConfigLocation | 13 | 返回写入用户特定配置文件的目录位置。这可能是一个通用值，也可能是特定于应用程序的值，返回的路径永远不会为空。 |
QStandardPaths::DownloadLocation | 14 | 返回用户下载文件的目录。这是一个通用值。如果没有专门用于下载的目录，则会返回一个用于存储用户文件的合理后备目录。 |
QStandardPaths::GenericConfigLocation | 16 | 返回写入多个应用程序共享的用户特定配置文件的目录位置。这是一个通用值，返回的路径永远不会为空。 |
QStandardPaths::AppDataLocation | 17 | 返回可存储持久应用程序数据的目录位置。这是一个特定于应用程序的目录。要获取与其他应用程序共享的数据存储路径，请使用 QStandardPaths::GenericDataLocation。返回的路径永远不会为空。在 Windows 操作系统中，此值返回漫游路径。此枚举值在 Qt 5.4 中添加。 |
QStandardPaths::AppConfigLocation | 18 | 返回应写入用户特定配置文件的目录位置。这是一个特定于应用程序的目录，返回的路径永远不会为空。此枚举值在 Qt 5.5 中添加。 |
QStandardPaths::PublicShareLocation | 19 | 返回可存储用户特定的公开共享文件和目录的目录位置。这是一个通用值。请注意，如果系统没有公开共享位置的概念，返回的路径可能为空。此枚举值在 Qt 6.4 中添加。 |
QStandardPaths::TemplatesLocation | 20 | 返回可存储用户特定模板文件的目录位置。这是一个通用值。请注意，如果系统没有模板位置的概念，返回的路径可能为空。此枚举值在 Qt 6.4 中添加。 |
QStandardPaths::StateLocation (since Qt 6.7) | 21 | 返回应写入用户特定应用程序状态数据文件的目录位置。这是一个特定于应用程序的目录，返回的路径永远不会为空。 |
QStandardPaths::GenericStateLocation (since Qt 6.7) | 22 | 返回应写入跨应用程序共享状态数据文件的目录位置。该值可能是通用的，也可能是特定于应用程序的，但返回的路径绝不会为空。 |
下表列出了不同操作系统上的路径示例。第一个路径是可写路径（除非注明）。其他附加路径（如果有）代表不可写位置。
| 路径类型 | MacOS | Windows |
|---|---|---|
| 桌面位置 | "~/Desktop | "C:/Users/<USER>/Desktop |
| 文档位置 | 文档 | "C:/Users/<USER>/Documents |
| 字体位置 | "/System/Library/Fonts"（不可写） | "C:/Windows/Fonts" （不可写） |
| 应用程序位置 | "/应用程序"（不可写） | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs |
| 音乐位置 | "音乐位置 | "C:/Users/<USER>/Music |
| 电影位置 | "~/电影" "C:/Users/<USER>/Music | "C:/Users/<USER>/Videos |
| 图片位置 | "~/Pictures | "C:/Users/<USER>/Pictures |
| 临时位置 | 由操作系统随机生成 | "C:/Users/<USER>/AppData/Local/Temp |
| 主页位置 | "~" | "C:/Users/<USER>"。 |
| 应用程序本地数据位置 | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>"."<APPDIR>/.../Resources"。 | "C:/Users/<USER>/AppData/Local/<APPNAME>"、"C:/ProgramData/<APPNAME>"、"<APPDIR>"、"<APPDIR>/data"、"<APPDIR>/data/<APPNAME>"。 |
| 缓存位置 | "~/Library/Caches/<APPNAME>"、"/Library/Caches/<APPNAME>" 缓存位置 | "C:/Users/<USER>/AppData/Local/<APPNAME>/cache |
| 状态位置 | "~/Library/Preferences/<APPNAME>/State | "C:/Users/<USER>/AppData/Local/<APPNAME>/State"、"C:/ProgramData/<APPNAME>/State"。 |
| 通用数据位置 | "~/Library/Application Support"、"/Library/Application Support" (~Library/Application Support) | "C:/Users/<USER>/AppData/Local"、"C:/ProgramData"、"<APPDIR>"、"<APPDIR>/data" |
| 运行时位置 | "~/Library/Application Support | "C:/Users/<USER>" 配置位置 |
| 配置位置 | "~/Library/Preferences | "C:/Users/<USER>/AppData/Local/<APPNAME>"、"C:/ProgramData/<APPNAME>" |
| 通用配置位置 | "~/Library/Preferences | "C:/Users/<USER>/AppData/本地"、"C:/ProgramData |
| 下载位置 | "~/Downloads | "C:/Users/<USER>/Downloads |
| 通用缓存位置 | "~/Library/缓存"、"/Library/缓存 | "C:/Users/<USER>/AppData/Local/cache |
| 通用状态位置 | "~/Library/Preferences/State | "C:/Users/<USER>/AppData/Local/State"、"C:/ProgramData/State" AppDataLocation |
| 应用程序数据位置 | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>"."<APPDIR>/.../Resources | "C:/Users/<USER>/AppData/Roaming/<APPNAME>"、"C:/ProgramData/<APPNAME>"、"<APPDIR>"、"<APPDIR>/data"、"<APPDIR>/data/<APPNAME>"。 |
| 应用程序配置位置 | ~/Library/Preferences/<APPNAME>" "C:/Users/<APPNAME | "C:/Users/<USER>/AppData/Local/<APPNAME>"、"C:/ProgramData/<APPNAME>" |
| 公共共享位置 | "~/Public | "C:/Users/Public |
| 模板位置 | "模板位置 | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates |
| 路径类型 | Linux 和其他 UNIX 操作系统 |
|---|---|
| 桌面位置 | "~/Desktop |
| 文档位置 | "~/Documents |
| 字体位置 | "~/.fonts"、"~/.local/share/fonts"、"/usr/local/share/fonts"、"/usr/share/fonts" 应用程序位置 |
| 应用程序位置 | "~/.local/share/applications"、"/usr/local/share/applications"、"/usr/share/applications" 音乐位置 |
| 音乐位置 | "音乐位置 |
| 电影位置 | "~/Videos |
| 图片位置 | "~/图片 |
| 临时文件位置 | "/tmp |
| 主页位置 | "~" |
| 应用程序本地数据位置 | "~/.local/share/<APPNAME>"、"/usr/local/share/<APPNAME>"、"/usr/share/<APPNAME>" |
| 缓存位置 | "~/.cache/<APPNAME>" 缓存位置 |
| 状态位置 | "~/.local/state/<APPNAME>" 状态位置 |
| 通用数据位置 | "~/.local/share"、"/usr/local/share"、"/usr/share"。 |
| 运行时位置 | "/run/user/<USER>" 运行时位置 |
| 配置位置 | "/etc/xdg"、"~/.config |
| 通用配置位置 | "/etc/xdg"、"~/.config |
| 下载位置 | "~/Downloads |
| 通用缓存位置 | "~/.cache |
| 通用状态位置 | "~/.local/state |
| 应用程序数据位置 | "~/.local/share/<APPNAME>"、"/usr/local/share/<APPNAME>"、"/usr/share/<APPNAME>"。 |
| 应用程序配置位置 | "~/.config/<APPNAME>"、"/etc/xdg/<APPNAME>" 应用程序配置位置 |
| 公共共享位置 | "/etc/xdg/<APPNAME>"， "~/Public |
| 模板位置 | "模板位置 |
| 路径类型 | 安卓 | iOS |
|---|---|---|
| 桌面位置 | "<APPROOT>/files | "<APPROOT>/Documents/Desktop |
| 文档位置 | "<用户名>/<APPNAME>/文档" [*], "<USER>/<APPNAME>/Documents | "<APPROOT>/文档" [*], "<USER>/<APPNAME>/Documents |
| 字体位置 | "/system/fonts"（不可写） | "<APPROOT>/Library/Fonts |
| 应用程序位置 | 不支持（目录不可读） | 不支持 |
| 音乐位置 | "<用户>/<APPNAME>/音乐" [*], "<USER>/<APPNAME>/Music | "<APPROOT>/Documents/Music |
| 电影位置 | "<用户>/<APPNAME>/电影" [*]、"<用户>/<APPNAME>/电影 | "<APPROOT>/文件/电影" |
| 图片位置 | "<USER>/Pictures" [*]、"<USER>/<APPNAME>/Pictures" (*) | "<APPROOT>/文档/图片"，"assets-library://" |
| 临时位置 | "<APPROOT>/cache | "<APPROOT>/tmp |
| 主页位置 | "<APPROOT>/files | 系统定义 |
| 应用程序本地数据位置 | "<APPROOT>/files"、"<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support |
| 缓存位置 | "<APPROOT>/缓存"、"<用户名>/<APPNAME>/缓存 | "<APPROOT>/Library/Caches |
| 状态位置 | "<APPROOT>/files/state | |
| GenericStateLocation（存在共享状态） | "<APPROOT>/files/state | |
| 通用数据位置 | "<USER>" [*] 或 "<USER>/<APPNAME>/files" (有共享状态) | "<APPROOT>/Library/Application Support |
| 运行时位置 | "<APPROOT>/cache | 不支持 |
| 配置位置 | "<APPROOT>/files/settings | "<APPROOT>/Library/Preferences |
| 通用配置位置 | "<APPPROOT>/files/settings"（没有共享设置） | "<APPROOT>/Library/Preferences |
| 下载位置 | "<USER>/Downloads" [*], "<USER>/<APPNAME>/Downloads" (没有共享设置) | "<APPROOT>/Documents/Downloads |
| 通用缓存位置 | "<APPROOT>/缓存"（没有共享缓存） | "<APPROOT>/Library/Caches |
| 应用程序数据位置 | "<APPROOT>/files", "<USER>/<APPNAME>/files" (没有共享缓存) | "<APPROOT>/Library/Application Support |
| 应用程序配置位置 | "<APPROOT>/files/settings | "<APPPROOT>/Library/Preferences/<APPNAME>"。 |
| 公共共享位置 | 不支持 | 不支持 |
| 模板位置 | 不支持 | 不支持 |
在上表中，<APPNAME> 通常是组织名称、应用程序名称或两者，或者是打包时生成的唯一名称。<APPDIR> 是包含应用程序可执行文件的目录。
不应依赖上述路径，因为它们可能会根据操作系统配置、地域或未来的 Qt 版本而改变。
注意： 在 Android 系统上，如果外部存储器被卸载，外部存储器（<USER> 位置）上打开文件的应用程序将被杀死。
注意： 在 Android 6.0（API 23）或更高版本中，使用QStandardPaths::writableLocation 或QStandardPaths::standardLocations 时必须在运行时请求 "WRITE_EXTERNAL_STORAGE "权限。
注： 在 Android 系统上，读/写 GenericDataLocation 需要获得 READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE 权限。
注： [*] 在 Android 11 及以上版本中，公共目录在作用域存储模式下不再可直接访问。因此，不会返回"<USER>/DirName" 形式的路径。取而代之的是使用存储访问框架（SAF）访问此类目录的QFileDialog 。
注： 在 iOS 系统中，如果将QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() 作为参数传递给QFileDialog::setDirectory() ，将使用本地图片拾取器对话框访问用户的相册。返回的文件名可使用QFile 和相关 API 加载。此功能在 Qt 5.5 中添加。
另请参阅 writableLocation(),standardLocations(),displayName(),locate() 和locateAll().
成员函数文档
[static] QString QStandardPaths::displayName(QStandardPaths::StandardLocation type)
返回给定位置的本地化显示名称type ，如果找不到相关位置，则返回空的QString 。
[static] QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths = QStringList())
在指定的paths 中查找名为executableName 的可执行文件，如果paths 为空，则查找系统路径。
在大多数操作系统中，系统路径由PATH 环境变量决定。搜索可执行文件的目录可以在 paths 参数中设置。要同时在自己的路径和系统路径中搜索，可调用两次 findExecutable，一次在路径已设置的情况下，另一次在路径为空的情况下。如果可执行文件的行为取决于其调用的名称，则不会解析系统链接，以保护其行为。
注意： 在 Windows 系统中，通常的可执行文件扩展名（来自 PATHEXT 环境变量）会被自动添加。例如，findExecutable("foo") 调用会查找foo.exe 或foo.bat （如果存在）。
返回可执行文件的绝对路径，如果未找到，则返回空字符串。
如果给定的executableName 是指向可执行文件的绝对路径，则返回其干净路径。
[static] QString QStandardPaths::locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
在type 的标准位置查找名为fileName 的文件或目录。
options 标志允许您指定查找文件还是目录。默认情况下，该标记设置为LocateFile 。
返回找到的第一个文件或目录的绝对路径，否则返回空字符串。
[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
在type 的标准位置查找名称为fileName 的所有文件或目录。
options 标志允许您指定是查找文件还是目录。默认情况下，该标记设置为LocateFile 。
返回找到的所有文件的列表。
[static] void QStandardPaths::setTestModeEnabled(bool testMode)
如果testMode 是true ，则会启用QStandardPaths 中的特殊 "测试模式"，将可写位置改为指向测试目录。这将防止自动测试读取或写入当前用户的配置。
它会影响测试程序可能写入文件的位置：GenericDataLocation,AppDataLocation,ConfigLocation,GenericConfigLocation,AppConfigLocation,StateLocation,GenericStateLocation,GenericCacheLocation, 和CacheLocation 。其他位置不受影响。
在 Unix 上，XDG_DATA_HOME 设置为~/.qttest/share ，XDG_CONFIG_HOME 设置为~/.qttest/config ，XDG_STATE_HOME 设置为~/.qttest/state ，XDG_CACHE_HOME 设置为~/.qttest/cache 。
在 macOS 上，数据到~/.qttest/Application Support ，缓存到~/.qttest/Cache ，配置到~/.qttest/Preferences 。
在 Windows 系统中，所有内容都进入%APPDATA% 下的 "qttest "目录。
[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)
返回type 文件所属的所有目录。
目录列表按优先级从高到低排序，如果可以确定，则从writableLocation() 开始。如果没有定义类型的位置，则该列表为空。
另请参见 writableLocation()。
[static] QString QStandardPaths::writableLocation(QStandardPaths::StandardLocation type)
返回type 文件应写入的目录，如果无法确定位置，则返回空字符串。
注意： 返回的存储位置可能不存在；也就是说，它可能需要由系统或用户创建。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
