class QStandardPaths

类QStandardPaths提供访问标准路径的方法。更多信息…

概要

静态函数

• def displayName()

• def findExecutable()

• def isTestModeEnabled()

• def locate()

• def locateAll()

• def setTestModeEnabled()

• def standardLocations()

• def writableLocation()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译有误，也可以通过在"https:/bugreports.qt.io/projects/PYSIDE"创建工单的方式来告诉我们。

详细描述

该类包含查询本地文件系统中标准位置的功能，用于常见任务，如特定用户的目录或系统范围内的配置目录。

类 StandardLocation

此枚举描述了可以使用例如writableLocation、standardLocations 和 displayName 方法查询的不同位置。

此枚举中的一些值代表用户配置。这些枚举值将在不同的应用程序中返回相同的路径，因此可以用来与其他应用程序共享数据。其他的值是针对特定应用程序的。下表中的每个枚举值都描述它是否是特定于应用程序的或通用的。

假设特定于应用程序的目录对其他应用程序来说是不可访问的。因此，即使由同一用户运行，放置在那里的文件也可能无法被其他应用程序读取。另一方面，通用目录应假设被此用户运行的所有应用程序所访问，但仍应假设不会被其他用户的程序访问。

与其他用户的数据交换不属于 QStandardPaths 的范围。

常量	描述
QStandardPaths.DesktopLocation	返回用户的桌面目录。这是一个通用值。在没有桌面概念的系统中，它与 QStandardPaths::HomeLocation 相同。
QStandardPaths.DocumentsLocation	返回包含用户文档文件的目录。这是一个通用值。返回的路径永远不会为空。
QStandardPaths.FontsLocation	返回包含用户字体的目录。这是一个通用值。请注意，安装字体可能需要额外的、特定于平台的操作。
QStandardPaths.ApplicationsLocation	返回包含用户应用程序（可执行文件、应用程序包或它们的快捷方式）的目录。这是一个通用值。请注意，安装应用程序可能需要额外的、特定于平台的操作。此目录中的文件、文件夹或快捷方式是特定于平台的。
QStandardPaths.MusicLocation	返回包含用户音乐或其他音频文件的目录。这是一个通用值。如果不存在特定的音乐文件目录，将返回一个合理的回退，用于存储用户文档。
QStandardPaths.MoviesLocation	返回包含用户电影和视频的目录。这是一个通用值。如果不存在特定的电影文件目录，将返回一个合理的回退，用于存储用户文档。
QStandardPaths.PicturesLocation	返回包含用户图片或照片的目录。这是一个通用值。如果不存在特定的图片文件目录，将返回一个合理的回退，用于存储用户文档。
QStandardPaths.TempLocation	返回一个可以存储临时文件的目录。返回的值可能是特定于应用程序的、与其他应用程序共享的，或者甚至是系统范围内的。返回的路径永远不会为空。
QStandardPaths.HomeLocation	返回用户的家目录（与homePath()相同）。在Unix系统中，这等于HOME环境变量。此值可能是通用的或与应用程序相关的，但返回的路径永远不会为空。
QStandardPaths.AppLocalDataLocation	返回Windows操作系统的本地设置路径。在其他所有平台上，返回的值与AppDataLocation相同。此枚举值是在Qt 5.4中添加的。
QStandardPaths.CacheLocation	返回用户特定（缓存）数据应写入的目录位置。这是一个应用程序特定的目录。返回的路径永远不会为空。
QStandardPaths.GenericCacheLocation	返回用户特定非必要（缓存）数据，跨应用程序共享时应写入的目录位置。这是一个通用值。请注意，如果系统没有共享缓存的概念，返回的路径可能为空。
QStandardPaths.GenericDataLocation	返回应用程序间共享的持久数据可以存储的目录位置。这是一个通用值。返回的路径永远不会为空。
QStandardPaths.RuntimeLocation	返回应写入运行时通信文件（如Unix本地套接字）的目录位置。这是一个通用值。在某些系统上，返回的路径可能为空。
QStandardPaths.ConfigLocation	返回应写入用户特定配置文件的目录位置。这可能是一个通用值或应用程序特定的，返回的路径永远不会为空。
QStandardPaths.DownloadLocation	返回用户下载文件的目录。这是一个通用值。如果没有特定的下载目录存在，则返回存储用户文档的合理回退位置。
QStandardPaths.GenericConfigLocation	返回应在多个应用程序间共享的用户特定配置文件应写入的目录位置。这是一个通用值，返回的路径永远不会为空。
QStandardPaths.AppDataLocation	返回持久应用程序数据可以存储的目录位置。这是一个应用程序特定的目录。要获取存储与其他应用程序共享的数据的路径，请使用QStandardPaths::GenericDataLocation。返回的路径永远不会为空。在Windows操作系统中，这返回漫游路径。此枚举值是在Qt 5.4中添加的。
QStandardPaths.AppConfigLocation	返回用户特定配置文件应写入的目录位置。这是一个应用程序特定的目录，返回的路径永远不为空。此枚举值是在Qt 5.5中添加的。
QStandardPaths.PublicShareLocation	返回用户特定公开共享的文件和目录可以存储的目录位置。这是一个通用值。请注意，如果系统没有公开共享位置的概念，返回的路径可能为空。此枚举值是在Qt 6.4中添加的。
QStandardPaths.TemplatesLocation	返回用户特定模板文件可以存储的目录位置。这是一个通用值。请注意，如果系统没有模板位置的概念，返回的路径可能为空。此枚举值是在Qt 6.4中添加的。
QStandardPaths.StateLocation	返回用户特定应用程序状态数据文件应写入的目录位置。这是一个应用程序特定的目录，返回的路径永远不会为空。
QStandardPaths.GenericStateLocation	返回跨应用程序共享的状态数据文件应写入的目录位置。此值可以是通用或应用程序特定的，但返回的路径永远不会为空。

以下表格给出了不同操作系统上路径的示例。第一个路径是可写路径（除非说明）。如果有其他路径，则表示不可写位置。

路径类型	macOS	Windows
DesktopLocation	“~/Desktop”	“C:/Users/<USER>/Desktop”
DocumentsLocation	“~/Documents”	“C:/Users/<USER>/Documents”
字体位置	“/System/Library/Fonts”（不可写）	“C:/Windows/Fonts”（不可写）
应用程序位置	“/Applications”（不可写）	“C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs”
音乐位置	“~/Music”	“C:/Users/<USER>/Music”
电影位置	“~/Movies”	“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”	“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/Local”, “C:/ProgramData”
下载位置	“~/Downloads”	“C:/Users/<USER>/Downloads”
通用缓存位置	“~/Library/Caches”, “/Library/Caches”	“C:/Users/<USER>/AppData/Local/cache”
通用状态位置	“~/Library/Preferences/State”	“C:/Users/<USER>/AppData/Local/State”, “C:/ProgramData/State”
应用程序数据位置	“~/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/<USER>/AppData/Local/<APPNAME>”, “C:/ProgramData/<APPNAME>”
公共共享位置	“~/Public”	“C:/Users/Public”
模板位置	“~/Templates”	“C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates”

路径类型	Linux和其他UNIX操作系统
DesktopLocation	“~/Desktop”
DocumentsLocation	“~/Documents”
字体位置	“~/.fonts”, “~/.local/share/fonts”, “/usr/local/share/fonts”, “/usr/share/fonts”
应用程序位置	“~/.local/share/applications”, “/usr/local/share/applications”, “/usr/share/applications”
音乐位置	“~/Music”
电影位置	“~/Videos”
图片位置	“~/Pictures”
临时位置	“/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”
应用程序数据位置	“~/.local/share/<APPNAME>”, “/usr/local/share/<APPNAME>”, “/usr/share/<APPNAME>”
应用程序配置位置	“~/.config/<APPNAME>”, “/etc/xdg/<APPNAME>”
公共共享位置	“~/Public”
模板位置	“~/Templates”

路径类型	Android	iOS
DesktopLocation	“<APPROOT>/files”	“<APPROOT>/Documents/Desktop”
DocumentsLocation	“<USER>/Documents” [*], “<USER>/<APPNAME>/Documents”	“<APPROOT>/Documents”
字体位置	“/system/fonts” (不可写)	“<APPROOT>/Library/Fonts”
应用程序位置	不受支持（目录不可读）	不受支持
音乐位置	“<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”
主目录位置	“<APPROOT>/files”	系统定义
应用程序本地数据位置	“<APPROOT>/files”, “<USER>/<APPNAME>/files”	“<APPROOT>/Library/Application Support”
缓存位置	“<APPROOT>/cache”, “<USER>/<APPNAME>/cache”	“<APPROOT>/Library/Caches”
状态位置	“<APPROOT>/files/state”
通用状态位置（存在共享状态）	“<APPROOT>/files/state”
通用数据位置	“<USER>” [*] 或 “<USER>/<APPNAME>/files”	“<APPROOT>/Library/Application Support”
运行时位置	“<APPROOT>/cache”	不受支持
配置位置	“<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”
应用程序数据位置	“<APPROOT>/files”, “<USER>/<APPNAME>/files”	“<APPROOT>/Library/Application Support”
应用程序配置位置	“<APPROOT>/files/settings”	“<APPROOT>/Library/Preferences/<APPNAME>”
公共共享位置	不受支持	不受支持
模板位置	不受支持	不受支持

在上面的表格中，<APPNAME>通常是指组织名称、应用程序名称，或者是两者组合，或者是在打包时生成的唯一名称。同样，<APPROOT>是指该应用程序的安装位置（常常是沙盒）。<APPDIR>是包含应用程序可执行文件的目录。

上述路径不能依赖，因为它们可能会根据操作系统配置、区域设置而改变，或者在未来Qt版本中可能会改变。

注意

在Android上，如果外部存储（<USER>位置）上有打开的文件，那么在卸载外部存储时，这些应用程序将被终止。

注意

在Android 6.0（API 23）或更高版本上，当使用writableLocation或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()

class LocateOption

( inherits enum.Flag) 此枚举描述了可以用于控制locate和locateAll行为的不同标志。

常量	描述
QStandardPaths.LocateFile	仅返回文件
QStandardPaths.LocateDirectory	仅返回目录

static displayName(type)

参数：

类型 – StandardLocation

返回类型：

str

为给定的位置类型 type 返回本地化的显示名称，如果找不到相关位置则返回空的 QString。

静态findExecutable(executableName[, paths=list()])

参数：

• executableName – str

• paths – 字符串列表

返回类型：

str

在指定的 paths 中查找名为 executableName 的可执行文件，或者在 paths 为空时在系统路径中查找。

在大多数操作系统中，系统路径由 PATH 环境变量确定。可在 paths 参数中设置要搜索可执行文件的目录。为了同时搜索自己的路径和系统路径，请调用 findExecutable 两次，一次设置 paths，一次清除 paths。为了保持那些依赖其调用的名称的行为的可执行文件的行为，不解析符号链接。

注意

在 Windows 上，会自动添加通常的可执行文件扩展名（来自 PATHEXT 环境变量）。例如，findExecutable(“foo”) 调用会查找存在的 foo.exe 或 foo.bat。

返回可执行文件的绝对文件路径，如果未找到则返回空字符串。

如果给定的 executableName 是指向可执行文件的绝对路径，则返回其干净的路径。

静态isTestModeEnabled()

返回类型：

bool

静态locate(type, fileName[, options=QStandardPaths.LocateOption.LocateFile])

参数：

• 类型 – StandardLocation

• fileName – str

• options – LocateOption 的组合

返回类型：

str

在 type 的标准位置中查找名为 fileName 的文件或目录。

options 标志让你指定是否查找文件或目录。默认情况下，此标志设置为 LocateFile。

返回找到的第一个文件或目录的绝对路径，否则返回空字符串。

静态locateAll(type, fileName[, options=QStandardPaths.LocateOption.LocateFile])

参数：

• 类型 – StandardLocation

• fileName – str

• options – LocateOption 的组合

返回类型：

字符串列表

根据类型 type 的名称 fileName 在标准位置查找所有文件或目录。

options 标志让你指定是否查找文件或目录。默认情况下，此标志设置为 LocateFile。

返回找到的所有文件列表。

static setTestModeEnabled(testMode)

参数：

testMode – bool

如果 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 standardLocations(type)

参数：

类型 – StandardLocation

返回类型：

字符串列表

返回属于 type 文件的目录列表。

目录列表按照优先级从高到低排序，如果可以确定，则开始于 writableLocation()。如果没有为 type 定义位置，则此列表为空。

另请参阅

writableLocation()

static writableLocation(type)

参数：

类型 – StandardLocation

返回类型：

str

返回应将 type 文件写入的目录，如果无法确定位置，则返回空字符串。

注意

返回的存储位置可能不存在；也就是说，可能需要由系统或用户创建。