PySide6.QtCore.QStandardPaths¶

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上创建工单来告知我们。

详细描述¶

此类包含用于查询本地文件系统上标准位置的函数，用于常见任务，如用户特定目录或系统范围的配置目录。

class 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
桌面位置	“~/Desktop”	“C:/Users//Desktop”
文档位置	“~/Documents”	“C:/Users//Documents”
字体位置	“/System/Library/Fonts” (不可写)	“C:/Windows/Fonts” (不可写)
应用程序位置	“/Applications”（不可写）	“C:/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs”
音乐位置	“~/Music”	“C:/Users//Music”
电影位置	“~/Movies”	“C:/Users//Videos”
图片位置	“~/Pictures”	“C:/Users//Pictures”
TempLocation	由操作系统随机生成	“C:/Users//AppData/Local/Temp”
主目录位置	“~”	“C:/Users/”
AppLocalDataLocation	“~/Library/Application Support/”, “/Library/Application Support/”. “/../Resources”	“C:/Users//AppData/Local/”, “C:/ProgramData/”, “”, “/data”, “/data/”
缓存位置	“~/Library/Caches/”, “/Library/Caches/”	“C:/Users//AppData/Local//cache”
状态位置	“~/Library/Preferences//State”	“C:/Users//AppData/Local//State”, “C:/ProgramData//State”
通用数据位置	“~/Library/Application Support”, “/Library/Application Support”	“C:/Users//AppData/Local”, “C:/ProgramData”, “”, “/data”
运行时位置	“~/Library/Application Support”	“C:/Users/”
配置位置	“~/Library/Preferences”	“C:/Users//AppData/Local/”, “C:/ProgramData/”
通用配置位置	“~/Library/Preferences”	“C:/Users//AppData/Local”, “C:/ProgramData”
下载位置	“~/Downloads”	“C:/Users//Downloads”
通用缓存位置	“~/Library/Caches”, “/Library/Caches”	“C:/Users//AppData/Local/cache”
通用状态位置	“~/Library/Preferences/State”	“C:/Users//AppData/Local/State”, “C:/ProgramData/State”
AppDataLocation	“~/Library/Application Support/”, “/Library/Application Support/”. “/../Resources”	“C:/Users//AppData/Roaming/”, “C:/ProgramData/”, “”, “/data”, “/data/”
AppConfigLocation	“~/Library/Preferences/”	“C:/Users//AppData/Local/”, “C:/ProgramData/”
公共共享位置	“~/Public”	“C:/Users/Public”
模板位置	“~/Templates”	“C:/Users//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”
音乐位置	“~/Music”
电影位置	“~/Videos”
图片位置	“~/Pictures”
临时位置	“/tmp”
主目录位置	“~”
AppLocalDataLocation	“~/.local/share/”, “/usr/local/share/”, “/usr/share/”
缓存位置	“~/.cache/”
状态位置	“~/.local/state/”
通用数据位置	“~/.local/share”, “/usr/local/share”, “/usr/share”
运行时位置	“/run/user/”
配置位置	“~/.config”, “/etc/xdg”
通用配置位置	“~/.config”, “/etc/xdg”
下载位置	“~/Downloads”
通用缓存位置	“~/.cache”
通用状态位置	“~/.local/state”
AppDataLocation	“~/.local/share/”, “/usr/local/share/”, “/usr/share/”
AppConfigLocation	“~/.config/”, “/etc/xdg/”
公共共享位置	“~/Public”
模板位置	“~/Templates”

路径类型	安卓	iOS
桌面位置	“/files”	“/Documents/Desktop”
文档位置	“/Documents” [*], “//Documents”	“/Documents”
字体位置	“/system/fonts” (不可写)	“/Library/Fonts”
应用程序位置	不支持（目录不可读）	不支持
音乐位置	“/Music” [*], “//Music”	“/Documents/Music”
电影位置	“/Movies” [*], “//Movies”	“/Documents/Movies”
图片位置	“/Pictures” [*], “//Pictures”	“/Documents/Pictures”, “assets-library://”
临时位置	“/cache”	“/tmp”
主目录位置	“/files”	系统定义
AppLocalDataLocation	“/files”, “//files”	“/Library/Application Support”
缓存位置	“/cache”, “//cache”	“/Library/Caches”
			状态位置	“/files/state”
			通用状态位置（存在共享状态）	“/files/state”
GenericDataLocation	“” [*] 或 “//files”	“/Library/Application Support”
运行时位置	“/cache”	不支持
配置位置	“/files/settings”	“/Library/Preferences”
GenericConfigLocation	“/files/settings” (没有共享设置)	“/Library/Preferences”
下载位置	“/Downloads” [*], “//Downloads”	“/Documents/Downloads”
GenericCacheLocation	“/cache”（没有共享缓存）	“/Library/Caches”
AppDataLocation	“/files”, “//files”	“/Library/Application Support”
应用配置位置	“/files/settings”	“/Library/Preferences/”
公共分享位置	不支持	不支持
模板位置	不支持	不支持

在上表中， 通常是组织名称、应用程序名称或两者兼有，或者是打包时生成的唯一名称。同样， 是此应用程序安装的位置（通常是一个沙盒）。 是包含应用程序可执行文件的目录。

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

注意

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

注意

在Android 6.0（API 23）或更高版本上，使用writableLocation或standardLocations时，必须在运行时请求“WRITE_EXTERNAL_STORAGE”权限。

注意

在Android上，读取/写入GenericDataLocation需要授予READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE权限。

注意

[*] 在 Android 11 及以上版本中，公共目录在作用域存储模式下不再直接可访问。因此，形式为 "/DirName" 的路径不再返回。相反，您可以使用 QFileDialog，它使用存储访问框架（SAF）来访问这些目录。

注意

在iOS上，如果你将QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last()作为参数传递给QFileDialog::setDirectory()，将会使用一个原生的图片选择对话框来访问用户的相册。返回的文件名可以使用QFile和相关API加载。此功能在Qt 5.5中添加。

另请参阅

writableLocation() standardLocations() displayName() locate() locateAll()

class LocateOption¶

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

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

static displayName(type)¶

Parameters:

类型 – StandardLocation

Return type:

字符串

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

static findExecutable(executableName[, paths=list()])¶

Parameters:

• executableName – str

• paths – 字符串列表

Return type:

字符串

在指定的paths中查找名为executableName的可执行文件，如果paths为空，则在系统路径中查找。

在大多数操作系统中，系统路径由PATH环境变量决定。可以在paths参数中设置搜索可执行文件的目录。要同时搜索自己的路径和系统路径，可以调用findExecutable两次，一次设置paths，一次不设置paths。为了保留可执行文件的行为（这些行为取决于它们被调用时的名称），符号链接不会被解析。

注意

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

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

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

static isTestModeEnabled()¶

Return type:

布尔

static locate(type, fileName[, options=QStandardPaths.LocateOption.LocateFile])¶

Parameters:

• type – StandardLocation

• fileName – str

• options – LocateOption 的组合

Return type:

字符串

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

options 标志允许您指定是查找文件还是目录。默认情况下，此标志设置为 LocateFile。

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

static locateAll(type, fileName[, options=QStandardPaths.LocateOption.LocateFile])¶

Parameters:

• 类型 – StandardLocation

• fileName – str

• options – LocateOption 的组合

Return type:

字符串列表

在type的标准位置中，按名称fileName查找所有文件或目录。

options 标志允许您指定是查找文件还是目录。默认情况下，此标志设置为 LocateFile。

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

static setTestModeEnabled(testMode)¶

Parameters:

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

Parameters:

类型 – StandardLocation

Return type:

字符串列表

返回所有属于type类型的文件的目录。

目录列表按优先级从高到低排序，如果可以确定，则从writableLocation()开始。如果未定义类型的任何位置，则此列表为空。

另请参阅

writableLocation()

static writableLocation(type)¶

Parameters:

类型 – StandardLocation

Return type:

字符串

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

注意

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