QStandardPaths 类
QStandardPaths 类提供了访问标准路径的方法。 更多...
| 头文件 | #include <QStandardPaths> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake | QT += core |
公共类型
| 枚举 | LocateOption { LocateFile, LocateDirectory } |
| 标志 | LocateOptions |
| 枚举 | 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
标志 QStandardPaths::LocateOptions
此枚举描述了可用于控制 QStandardPaths::locate 和 QStandardPaths::locateAll 行为的不同标志。
| 常量 | 值 | 描述 |
|---|---|---|
QStandardPaths::LocateFile | 0x0 | 只返回文件 |
QStandardPaths::LocateDirectory | 0x1 | 只返回目录 |
LocateOptions 类型是 QFlags<LocateOption> 的同义词。它存储 LocateOption 值的 OR 组合。
枚举 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 (自 Qt 6.7 起使用) | 21 | 返回一个目录位置，应在其中编写用户特定应用程序状态数据文件。这是一个应用程序特定的目录，且返回的路径永远不会为空。 |
QStandardPaths::GenericStateLocation (自 Qt 6.7 起使用) | 22 | 返回一个目录位置，应在其中编写跨多个应用程序共享的状态数据文件。此值可能为通用或应用程序特定，但返回的路径永远不会为空。 |
以下表格提供了不同操作系统上的路径示例。第一个路径是可写路径（除非另有说明）。如果有其他路径，则代表不可写位置。
| 路径类型 | macOS | Windows |
|---|---|---|
| DesktopLocation | "~/Desktop" | "C:/Users/<USER>/Desktop" |
| DocumentsLocation | "~/Documents" | "C:/Users/<USER>/Documents" |
| FontsLocation | "/System/Library/Fonts" (不可写) | "C:/Windows/Fonts" (不可写) |
| ApplicationsLocation | "/Applications" (不可写) | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs" |
| MusicLocation | "~/Music" | "C:/Users/<USER>/Music" |
| MoviesLocation | "~/Movies" | "C:/Users/<USER>/Videos" |
| PicturesLocation | "~/Pictures" | "C:/Users/<USER>/Pictures" |
| TempLocation | 由操作系统随机生成 | "C:/Users/<USER>/AppData/Local/Temp" |
| HomeLocation | "~" | "C:/Users/<USER>" |
| AppLocalDataLocation | "~/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>" |
| CacheLocation | "~/Library/Caches/<APPNAME>", "/Library/Caches/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>/cache" |
| StateLocation | "~/Library/Preferences/<APPNAME>/State" | "C:/Users/<USER>/AppData/Local/<APPNAME>/State", "C:/ProgramData/<APPNAME>/State" |
| GenericDataLocation | "~/Library/Application Support", "/Library/Application Support" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data" |
| RuntimeLocation | "~/Library/Application Support" | "C:/Users/<USER>" |
| ConfigLocation | "~/Library/Preferences" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| GenericConfigLocation | "~/Library/Preferences" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData" |
| DownloadLocation | "~/Downloads" | "C:/Users/<USER>/Downloads" |
| GenericCacheLocation | "~/Library/Caches", "/Library/Caches" | "C:/Users/<USER>/AppData/Local/cache" |
| GenericStateLocation | “~/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>” |
| AppConfigLocation | “~/Library/Preferences/<APPNAME>” | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| PublicShareLocation | “~/Public” | “C:/Users/Public” |
| TemplatesLocation | “~/Templates” | “C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates” |
| 路径类型 | Linux和其他UNIX操作系统 |
|---|---|
| DesktopLocation | "~/Desktop" |
| DocumentsLocation | "~/Documents" |
| FontsLocation | “~/.fonts”， “~/.local/share/fonts”， “/usr/local/share/fonts”， “/usr/share/fonts” |
| ApplicationsLocation | “~/.local/share/applications”， “/usr/local/share/applications”， “/usr/share/applications” |
| MusicLocation | "~/Music" |
| MoviesLocation | “~/Videos” |
| PicturesLocation | "~/Pictures" |
| TempLocation | “/tmp” |
| HomeLocation | "~" |
| AppLocalDataLocation | “~/.local/share/<APPNAME>”， “/usr/local/share/<APPNAME>”， “/usr/share/<APPNAME>” |
| CacheLocation | “~/.cache/<APPNAME>” |
| StateLocation | “~/.local/state/<APPNAME>” |
| GenericDataLocation | “~/.local/share”， “/usr/local/share”， “/usr/share” |
| RuntimeLocation | “/run/user/<USER>” |
| ConfigLocation | “~/.config”， “/etc/xdg” |
| GenericConfigLocation | “~/.config”， “/etc/xdg” |
| DownloadLocation | "~/Downloads" |
| GenericCacheLocation | “~/.cache” |
| GenericStateLocation | “~/.local/state” |
| AppDataLocation | “~/.local/share/<APPNAME>”， “/usr/local/share/<APPNAME>”， “/usr/share/<APPNAME>” |
| AppConfigLocation | “~/.config/<APPNAME>”， “/etc/xdg/<APPNAME>” |
| PublicShareLocation | “~/Public” |
| TemplatesLocation | “~/Templates” |
| 路径类型 | Android | iOS |
|---|---|---|
| DesktopLocation | “<APPROOT>/files” | “<APPROOT>/Documents/Desktop” |
| DocumentsLocation | “<USER>/Documents” [*]， “<USER>/<APPNAME>/Documents” | “<APPROOT>/Documents” |
| FontsLocation | “/system/fonts” (不可写) | “<APPROOT>/Library/Fonts” |
| ApplicationsLocation | 不受支持（目录不可读） | 不受支持 |
| MusicLocation | “<USER>/Music” [*]， “<USER>/<APPNAME>/Music” | “<APPROOT>/Documents/Music” |
| MoviesLocation | “<USER>/Movies” [*]， “<USER>/<APPNAME>/Movies” | “<APPROOT>/Documents/Movies” |
| PicturesLocation | “<USER>/Pictures” [*]， “<USER>/<APPNAME>/Pictures” | “<APPROOT>/Documents/Pictures”， “assets-library://” |
| TempLocation | “<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” |
| StateLocation | “<APPROOT>/files/state” | |
| 通用状态位置（有共享状态） | “<APPROOT>/files/state” | |
| GenericDataLocation | “<USER>” [*] 或 “<USER>/<APPNAME>/files” | “<APPROOT>/Library/Application Support” |
| RuntimeLocation | “<APPROOT>/cache” | 不受支持 |
| ConfigLocation | “<APPROOT>/files/settings” | “<APPROOT>/Library/Preferences” |
| GenericConfigLocation | “<APPROOT>/files/settings” (没有共享设置) | “<APPROOT>/Library/Preferences” |
| DownloadLocation | “<USER>/Downloads” [*]， “<USER>/<APPNAME>/Downloads” | “<APPROOT>/Documents/Downloads” |
| GenericCacheLocation | “<APPROOT>/cache” (没有共享缓存) | “<APPROOT>/Library/Caches” |
| AppDataLocation | “<APPROOT>/files”， “<USER>/<APPNAME>/files” | “<APPROOT>/Library/Application Support” |
| AppConfigLocation | “<APPROOT>/files/settings” | “<APPROOT>/Library/Preferences/<APPNAME>” |
| PublicShareLocation | 不受支持 | 不受支持 |
| 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()。
成员函数文档
[静态] QString QStandardPaths::displayName(QStandardPaths::StandardLocation 类型)
返回给定位置类型的本地化显示名称，或者在没有找到相关位置的情况下返回一个空的QString。
[静态] QString QStandardPaths::findExecutable(const QString &可执行名称, const QStringList &路径 = QStringList())
在指定的路径中查找名为可执行名称的可执行文件，或者当路径为空时在系统路径中查找。
在大多数操作系统中，系统路径由PATH环境变量确定。可在路径参数中设置搜索可执行文件所在的目录。为了同时搜索自己的路径和系统路径，需要调用两次findExecutable函数，一次设置路径，一次不设置路径。链接不会解析，以保留对那些执行行为依赖于它们被调用名称的可执行文件的行为。
注意：在Windows上，通常的可执行文件扩展名（由PATHEXT环境变量提供）会自动追加。例如，findExecutable("foo")调用如果在系统中存在，会找到foo.exe或foo.bat。
返回可执行文件的绝对文件路径，或者在未找到时返回一个空字符串。
如果给定的可执行名称是一个指向可执行文件的绝对路径，则返回其干净路径。
[静态] QString QStandardPaths::locate(QStandardPaths::StandardLocation 类型, const QString &文件名, QStandardPaths::LocateOptions 选项 = LocateFile)
在类型的标准位置中查找名为文件名的文件或目录。
选项标志允许您指定是否查找文件或目录。默认情况下，此标志设置为LocateFile。
返回找到的第一个文件或目录的绝对路径，否则返回一个空字符串。
[静态] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation 类型, const QString &文件名, QStandardPaths::LocateOptions 选项 = LocateFile)
在类型的标准位置中查找所有名为文件名的文件或目录。
选项标志允许您指定是否查找文件或目录。默认情况下，此标志设置为LocateFile。
返回找到的所有文件的列表。
[静态] 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 类型的文件的目录，如果无法确定位置，则返回空字符串。
注意：返回的存储位置可能不存在；也就是说，可能需要由系统或用户创建。
© 2024 The Qt Company Ltd. 包含在其中的文档贡献是各自所有者的版权。本文件提供的文档是在GNU自由文档许可版本1.3的条款下许可的，由自由软件基金会发布。Qt及其 respective 商标在芬兰和/或其他国家/地区是世界商标，属于 The Qt Company Ltd。所有其它商标均为其各自所有者的财产。
