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) |
成员类型文档
enum QStandardPaths::LocateOption
flags QStandardPaths::LocateOptions
此枚举描述了可用于控制QStandardPaths::locate 和QStandardPaths::locateAll 行为的各种标志。
| 常量 | 常量值 | 描述 |
|---|---|---|
QStandardPaths::LocateFile | 0x0 | 仅返回文件 |
QStandardPaths::LocateDirectory | 0x1 | 仅返回目录 |
LocateOptions 类型是QFlags<LocateOption> 的 typedef。它存储 LocateOption 值的“或”组合。
enum QStandardPaths::StandardLocation
该枚举描述了可通过QStandardPaths::writableLocation 、QStandardPaths::standardLocations 和QStandardPaths::displayName 等方法查询的不同位置。
QStandardPaths 该枚举沿两个独立的维度描述每个位置：应用范围（仅限调用应用内部，或在应用之间共享）和用户范围（以调用用户的目录为根，或覆盖整个系统）。下文中的每个枚举值均表示其应用范围；下文中的平台表格则显示其用户范围。
与其他用户之间的数据交换超出了QStandardPaths 的范围。
应用范围
一个位置要么是应用程序专属的（仅限调用应用程序访问），要么是通用的（由同一用户运行的应用程序之间共享）。应假定应用程序专属的位置对其他应用程序不可访问，即使这些应用程序由同一用户运行也是如此。
沙盒应用程序
对于 iOS、Android 或 macOS 等平台上的沙盒应用程序，即使是通用位置也可能根植于应用程序的沙盒容器中（下表中的<APPROOT> ）。 实际上，这消除了应用范围的区分，每个位置实际上都变成了应用程序特定，而用户在系统范围内的共享目录只能通过系统提供的选择器访问，例如QFileDialog 。
用户范围
一个位置要么是用户本地的（根目录位于调用用户的主目录或用户专用目录中），要么是全系统的（由操作系统或软件包管理器填充，在用户之间共享，并且通常对应用程序是只读的）。
调用writableLocation() 会返回应写入文件的目录，该目录通常属于用户作用域。对于特定于应用程序的位置，其作用域也限定在调用该应用程序的范围内。
调用standardLocations() 会首先返回可写路径（如果能确定），随后返回零个或多个附加位置，包括用户本地和系统范围的备用位置。这些附加位置将由locate() 和locateAll() 用于查找现有文件。
沙箱应用程序
对于沙盒化应用程序，全局位置通常位于应用程序沙盒容器之外，从应用程序的角度来看，这些位置可能并不存在，更不用说可读或可写了。 为了与非沙盒化情况保持一致，并涵盖那些通过授权或用户驱动的选择器被授予访问权限的应用程序，这些位置仍在下面的平台表中列出。调用方不应假设standardLocations() 返回的每个条目都存在或可访问。
| 常量 | 值 | 描述 |
|---|---|---|
QStandardPaths::DesktopLocation | 0 | 用户的桌面目录。在没有“桌面”概念的系统上，此项与 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 | 应将配置文件写入的目录。返回的路径绝不会为空。可能是通用型或应用程序特定型（有关显式变体，请参见 AppConfigLocation 和 GenericConfigLocation）。因情况而异。 |
QStandardPaths::DownloadLocation | 14 | 下载文件的目录。如果不存在此类目录，则返回一个合理的备用位置用于存储文档。通用。 |
QStandardPaths::GenericConfigLocation | 16 | 用于写入多个应用程序共享的配置文件的目录。返回的路径绝不会为空。通用。 |
QStandardPaths::AppDataLocation | 17 | 用于存储持久化应用程序数据的目录。若要获取用于存储与其他应用程序共享数据的路径，请使用 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" |
| 字体位置 | "~/Library/Fonts", "/Library/Fonts", "/System/Library/Fonts" | "C:/Windows/Fonts"（不可写） |
| 应用程序位置 | "~/Applications", "/Applications" | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs" |
| 音乐位置 | "~/Music" | "C:/Users/<USER>/Music" |
| 电影位置 | "~/Movies" | "C:/Users/<USER>/Videos" |
| 图片位置 | "~/图片" | "C:/Users/<USER>/Pictures" |
| 临时文件位置 | 由操作系统随机生成 | "C:/Users/<USER>/AppData/Local/Temp" |
| HomeLocation | "~" | "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" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data" |
| 运行时位置 | "~/Library/Application Support" | "C:/Users/<USER>" |
| 配置位置 | "~/Library/Preferences", "/Library/Preferences" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| 通用配置位置 | "~/Library/Preferences", "/Library/Preferences" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData" |
| 下载位置 | "~/下载" | "C:/Users/<USER>/Downloads" |
| 通用缓存位置 | "~/Library/Caches", "/Library/Caches", "/System/Library/Caches" | "C:/Users/<USER>/AppData/Local/cache" |
| 通用状态位置 | "~/Library/Preferences/State" | "C:/Users/<USER>/AppData/Local/State", "C:/ProgramData/State" |
| AppData位置 | "~/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>" |
| AppConfigLocation | "~/Library/Preferences/<APPNAME>", "/Library/Preferences/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| 公共共享位置 | "~/Public" | "C:/Users/Public" |
| 模板位置 | 不支持 | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates" |
注意：在 macOS上 ，当应用程序处于沙盒环境时，操作系统会将用户的主目录透明地重定向到位于~/Library/Containers/<BUNDLE-ID>/Data 的应用程序专用容器中。上方的 macOS 对照表仍然适用，其中对于以用户为主目录的条目，~ 实际上会解析为<APPROOT> 。 出于对称性考虑，此处列出了/Library/... 、/System/Library/... 和<APPDIR>/../Resources 等系统级备用路径，但通常在没有明确权限的情况下无法访问这些路径。
| 路径类型 | 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" |
| 音乐位置 | "~/Music" |
| 视频位置 | "~/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>" |
| 配置位置 | "~/.config", "/etc/xdg" |
| 通用配置位置 | "~/.config", "/etc/xdg" |
| 下载位置 | "~/Downloads" |
| 通用缓存位置 | "~/.cache" |
| 通用状态位置 | "~/.local/state" |
| AppDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| 应用配置位置 | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| 公共共享位置 | "~/Public" |
| 模板位置 | "~/Templates" |
| 路径类型 | Android | iOS |
|---|---|---|
| 桌面位置 | "<APPROOT>/files" | "<APPROOT>/Documents/Desktop" |
| 文档位置 | "<USER>/Documents" [*]，"<USER>/<APPNAME>/Documents" | "<APPROOT>/文档" |
| 字体位置 | "/system/fonts"（不可写） | "<APPROOT>/Library/Fonts" |
| ApplicationsLocation | 不支持（目录不可读） | 不支持 |
| 音乐位置 | "<USER>/Music" [*], "<USER>/<APPNAME>/Music" | "<APPROOT>/Documents/Music" |
| 电影位置 | "<USER>/Movies" [*]、"<USER>/<APPNAME>/Movies" | "<APPROOT>/Documents/Movies" |
| 图片位置 | "<USER>/Pictures" [*], "<USER>/<APPNAME>/Pictures" | "<APPROOT>/Documents/Pictures", "assets-library://" |
| 临时文件位置 | "<APPROOT>/cache" | "<APPROOT>/tmp" |
| HomeLocation | "<APPROOT>/files" | 系统定义 |
| AppLocalDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| CacheLocation | "<APPROOT>/cache", "<USER>/<APPNAME>/cache" | "<APPROOT>/Library/Caches" |
| 状态位置 | "<APPROOT>/files/state" | "<APPROOT>/Library/Preferences/<APPNAME>/State" |
| 通用状态位置（存在共享状态） | "<APPROOT>/files/state" | "<APPROOT>/Library/Preferences/State" |
| 通用数据位置 | "<USER>" [*] 或 "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| 运行时位置 | "<APPROOT>/cache" | "<APPROOT>/Library/Application Support" |
| 配置位置 | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences" |
| 通用配置位置 | "<APPROOT>/files/settings"（没有共享设置） | "<APPROOT>/Library/Preferences" |
| 下载位置 | "<USER>/Downloads" [*]，"<USER>/<APPNAME>/Downloads" | "<APPROOT>/Documents/Downloads" |
| 通用缓存位置 | "<APPROOT>/cache"（没有共享缓存） | "<APPROOT>/Library/Caches" |
| AppData 位置 | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| AppConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences/<APPNAME>" |
| PublicShareLocation | 不支持 | "<APPROOT>/Public" |
| TemplatesLocation | 不支持 | 不支持 |
在上表中，<APPNAME> 通常是组织名称、应用程序名称，或两者兼有，也可能是打包时生成的唯一名称。同样，<APPROOT>是该应用程序的安装位置（通常为沙盒）。<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" 形式的路径。取而代之，您可以使用QFileDialog ，该方法通过存储访问框架 (SAF) 访问此类目录。
注意：在 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`：一次设置 `paths` 参数，一次留空。为保持那些行为取决于调用名称的可执行文件的行为一致性，符号链接不会被解析。
注意：在 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 文件应写入的目录，如果无法确定位置，则返回空字符串。
注意： 返回的存储位置可能不存在；也就是说，该位置 可能需要由系统或用户创建。
© 2026 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.
