class QSettings#

QSettings 类提供持久的平台无关的应用程序设置。更多信息...

Inheritance diagram of PySide6.QtCore.QSettings

概述#

方法#

静态函数#

注意

本文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们一直欢迎对代码片段翻译的贡献。如果您发现翻译有问题，您也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建一个工单来通知我们。

详细描述#

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

用户通常希望应用程序在会话之间记住其设置（窗口大小和位置、选项等）。这些信息通常存储在 Windows 的系统注册表中，macOS 和 iOS 的属性列表文件中。在 Unix 系统上，由于没有标准，许多应用程序（包括 KDE 应用程序）使用 INI 文本文件。

QSettings 是对这些技术的抽象，允许您以可移植的方式保存和恢复应用程序设置。它还支持 自定义存储格式。

QSettings 的 API 基于 QVariant，允许您轻松地保存大多数基于值的类型，如 QString、QRect 和 QImage。

如果您只需要一个非持久性基于内存的结构，请考虑使用 QMap < QString，QVariant >。

基本用法#

创建 QSettings 对象时，您必须传递您的公司或组织的名称以及您的应用程序的名称。例如，如果您的产品名为 Star Runner，而您的公司名为 MySoft，则构建 QSettings 对象如下：

settings = QSettings("MySoft", "Star Runner")

QSettings 对象可以在堆栈上或堆中创建（即使用 new）。构建和销毁一个 QSettings 对象非常快。

如果你的应用程序在多个位置使用QSettings，你可能需要使用setOrganizationName()和setApplicationName()来指定组织名称和应用程序名称，然后使用默认的QSettings构造函数。

QCoreApplication.setOrganizationName("MySoft")
QCoreApplication.setOrganizationDomain("mysoft.com")
QCoreApplication.setApplicationName("Star Runner")            ...

settings = QSettings()

（在此，我们还指定了组织的Internet域名。当设置了Internet域名时，它在macOS和iOS上使用，而不是使用组织名称，因为macOS和iOS应用程序通常使用Internet域名来标识自己。如果没有设置域名，则从组织名称中派生出一个假设的域名。有关详细信息，请参见下面的平台特定说明。）

QSettings存储设置。每个设置由一个指定设置名称（键）的QString和一个与键关联的数据存储的QVariant组成。要写入设置，请使用setValue()。例如

settings.setValue("editor/wrapMargin", 68)

如果已存在具有相同键的设置，则现有值将被新值覆盖。为了效率，更改可能不会立即保存到永久存储。（你可以始终调用sync()来提交你的更改。）

你可以使用value()来获取设置的值。

margin = settings.value("editor/wrapMargin").toInt()

如果不存在具有指定名称的设置，QSettings返回一个null QVariant（可以转换为整数0）。你可以通过传递第二个参数给value()来指定另一个默认值。

margin = settings.value("editor/wrapMargin", 80).toInt()

要测试指定的键是否存在，请调用contains()。要删除与键关联的设置，请调用remove()。要获取所有键的列表，请调用allKeys()。要删除所有键，请调用clear()。

QVariant和GUI类型#

因为 QVariant 是 Qt 核心模块的一部分，它不能提供转换色值、图像和位图的转换函数，如 QColor、QImage 和 QPixmap，这些是 Qt GUI 的一部分。换句话说，在 QVariant 中没有 toColor()，toImage() 或 toPixmap() 函数。

相反，您可以使用 value() 模板函数。例如

settings = QSettings("MySoft", "Star Runner")
color = settings.value("DataPump/bgcolor").value<QColor>()

对于所有由 QVariant 支持的数据类型，包括与 GUI 相关的类型，逆转换（例如，从 QColor 到 QVariant）是自动的。

settings = QSettings("MySoft", "Star Runner")
color = palette().background().color()
settings.setValue("DataPump/bgcolor", color)

使用 qRegisterMetaType() 注册的、具有对 QDataStream 的流式传输运算符的自定义类型可以用 QSettings 进行存储。

分区和键语法#

设置键可以包含任何 Unicode 字符。Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为了避免可移植性问题，请遵循以下简单规则

  1. 始终使用相同的键以相同的格式进行引用。例如，如果在代码中的一个地方将某个键称为“text fonts”，不要在另一个地方将其称为“Text Fonts”。

  2. 避免键名仅在大小写上有所不同。例如，如果有一个键名为“MainWindow”，不要尝试将另一个键保存为“mainwindow”。

  3. 在分区或键名中不要使用斜杠（‘/’ 和 ‘\’）；反斜杠字符用于分隔子键（见下文）。在 Windows 中，反斜杠通过 QSettings 转换为 ‘/’，这使得它们相同。

您可以使用 ‘/’ 字符作为分隔符来形成层次键，类似于 Unix 文件路径。例如

settings.setValue("mainwindow/size", win.size())
settings.setValue("mainwindow/fullScreen", win.isFullScreen())
settings.setValue("outputpanel/visible", panel.isVisible())

如果要保存或恢复许多具有相同前缀的设置，可以使用 beginGroup() 指定前缀，并在结束时调用 endGroup()。以下是一个相同的示例，但这次使用了组机制

settings.beginGroup("mainwindow")
settings.setValue("size", win.size())
settings.setValue("fullScreen", win.isFullScreen())
settings.endGroup()

settings.beginGroup("outputpanel")
settings.setValue("visible", panel.isVisible())
settings.endGroup()

如果使用 beginGroup() 设置了组，大多数函数的行为会相应地改变。组可以被递归设置。

除了组之外，QSettings 还支持“数组”概念。请参阅 beginReadArray() 和 beginWriteArray() 以获取更多详细信息。

回退机制#

假设您已经创建了一个带有组织名称MySoft和应用程序名称Star Runner的QSettings对象。当您查找值时，将按以下顺序在该对象对应的位置查找，最多四个位置：

  1. Star Runner应用程序的用户特定位置

  2. MySoft所有应用程序的用户特定位置

  3. Star Runner应用程序的系统范围位置

  4. MySoft所有应用程序的系统范围位置

（有关不同平台上的这些位置的信息，请参见下面的平台特定 说明。）

如果第一个位置中找不到密钥，搜索将转换到第二个位置，依此类推。这使您能够存储系统范围或组织范围的设置，并通过按用户或按应用程序覆盖它们。要关闭此机制，请调用setFallbacksEnabled（false）。

尽管可读取所有四个位置的键，但只能将第一个文件（当前处理的应用程序的用户特定位置）用于写入。要写入任何其他文件，请省略应用程序名称并/或将SystemScope（与默认值UserScope 相比）指定。

让我们看看一个示例。

obj1 = QSettings("MySoft", "Star Runner")
obj2 = QSettings("MySoft")
obj3 = QSettings(QSettings.SystemScope, "MySoft", "Star Runner")
obj4 = QSettings(QSettings.SystemScope, "MySoft")

下表总结了哪些QSettings对象访问哪个位置。“X"表示该位置是与QSettings对象关联的主要位置，既用于读取也用于写入；“o”表示该位置在读取时用作回退。

位置

obj1

obj2

obj3

obj4

  1. 用户、应用程序

X

  1. 用户、组织

o

X

  1. 系统、应用程序

o

X

  1. 系统、组织

o

o

o

X

此机制的好处是它在Qt支持的所有平台上都起作用，并且仍然提供了大量灵活性，而无需您指定任何文件名或注册表路径。

如果您想在不使用原生的API而是在所有平台上使用INI文件，请将IniFormat作为第一个参数传递给QSettings构造函数，后面跟作用域、组织名称和应用程序名称。

QSettings settings(QSettings.IniFormat, QSettings.UserScope,
                   "MySoft", "Star Runner")

请注意，INI文件会丢失数值数据和用于编码它们的字符串之间的区别，因此数字形式的值将被读取回QString。可以使用toInt()、toDouble()和相关函数恢复数值。

恢复GUI应用程序的状态#

QSettings 通常用于存储GUI应用程序的状态。以下示例说明了如何使用 QSettings 保存和恢复应用程序主窗口的几何形状。

def writeSettings(self):

    settings = QSettings("Moose Soft", "Clipper")
    settings.beginGroup("MainWindow")
    settings.setValue("geometry", saveGeometry())
    settings.endGroup()

def readSettings(self):

    settings = QSettings("Moose Soft", "Clipper")
    settings.beginGroup("MainWindow")
    geometry = settings.value("geometry", QByteArray()).toByteArray()
    if geometry.isEmpty():
        setGeometry(200, 200, 400, 400)
else:
        restoreGeometry(geometry)
    settings.endGroup()

请参考“窗口几何形状”部分，讨论为何在恢复窗口的几何形状时，调用 QWidget::resize() 和 QWidget::move() 而不是 QWidget::setGeometry() 更好。

必须从主窗口的构造函数和关闭事件处理程序中调用 readSettings() 和 writeSettings() 函数，如下所示

def __init__(self):            ...

readSettings()

def closeEvent(self, event):

    if userReallyWantsToQuit():
        writeSettings()
        event.accept()
    else:
        event.ignore()

同时从多个线程或进程访问设置#

QSettings 是可重入的。这意味着您可以在不同的线程中同时使用不同的 QSettings 对象。即使在 QSettings 对象引用磁盘上的相同文件（或系统注册表中的相同条目）时，该保证仍然有效。如果通过一个 QSettings 对象修改了设置，那么更改将立即在其他任何在相同位置操作且位于同一进程中的 QSettings 对象中可见。

如果满足某些条件，则可以从不同的进程（可以是同一时间内运行的应用程序的不同实例或完全不同的应用程序）安全地使用 QSettings 来读取和写入相同的系统位置。对于 IniFormat ，它使用建议性的文件锁定和一个智能合并算法来确保数据完整性。要使此操作生效，可写配置文件必须是一个常规文件，并且必须位于当前用户可以在此处创建新临时文件的目录中。如果不是这种情况，则必须使用 setAtomicSyncRequired() 来关闭安全性。

请注意，sync() 不仅导入其他进程产生的更改（除了写入此 QSettings 的更改）。

与平台相关的内容#

应用程序设置存储的位置#

如《回退机制》章节所述，QSettings 根据设置是否为用户特定或系统范围，以及是否为应用特定或组织范围，在最多四个位置存储应用设置。为了简单起见，我们假设组织名称为 MySoft，应用名称为 Star Runner。

在 Unix 系统上，如果文件格式为 NativeFormat，则默认使用以下文件：

  1. $HOME/.config/MySoft/Star Runner.conf

  2. $HOME/.config/MySoft.conf

  3. 对于每个 $XDG_CONFIG_DIRS 中的目录 <dir>，<dir>/MySoft/Star Runner.conf

  4. 对于每个 $XDG_CONFIG_DIRS 中的目录 <dir>，<dir>/MySoft.conf

注意

如果未设置 XDG_CONFIG_DIRS，则使用默认值 /etc/xdg。

在 macOS 和 iOS 上，如果文件格式为 NativeFormat，则默认使用以下文件：

  1. $HOME/Library/Preferences/com.MySoft.Star Runner.plist

  2. $HOME/Library/Preferences/com.MySoft.plist

  3. /Library/Preferences/com.MySoft.Star Runner.plist

  4. /Library/Preferences/com.MySoft.plist

在 Windows 上，NativeFormat 设置存储在以下注册表中：

  1. HKEY_CURRENT_USER\Software\MySoft\Star Runner

  2. HKEY_CURRENT_USER\Software\MySoft\OrganizationDefaults

  3. HKEY_LOCAL_MACHINE\Software\MySoft\Star Runner

  4. HKEY_LOCAL_MACHINE\Software\MySoft\OrganizationDefaults

注意

在 Windows 上，对于在 WOW64 模式下运行的 32 位程序，设置存储在以下注册表路径：

HKEY_LOCAL_MACHINE\Software\WOW6432node

如果文件格式为 NativeFormat，则这是应用主目录中的“Settings/MySoft/Star Runner.conf”。

  1. 如果文件格式为 IniFormat，则 Unix、macOS 和 iOS 上使用以下文件：

  2. $HOME/.config/MySoft/Star Runner.ini

  3. $HOME/.config/MySoft.ini

  4. 对于每个 $XDG_CONFIG_DIRS 中的目录 <dir>，<dir>/MySoft/Star Runner.ini

注意

如果未设置 XDG_CONFIG_DIRS，则使用默认值 /etc/xdg。

对于每个 $XDG_CONFIG_DIRS 中的目录 <dir>，<dir>/MySoft.ini

  1. 在 Windows 上，使用以下文件：

  2. FOLDERID_RoamingAppData\MySoft\Star Runner.ini

  3. FOLDERID_RoamingAppData\MySoft.ini

  4. FOLDERID_ProgramData\MySoft\Star Runner.ini

FOLDERID_ProgramData\MySoft.ini

以 FOLDERID_ 开头的标识符是特殊的项目 ID 列表，用于传递给 Win32 API 函数 SHGetKnownFolderPath() 以获取对应的路径。

FOLDERID_RoamingAppData 通常指向 C:\Users\User Name\AppData\Roaming，也由环境变量 %APPDATA% 显示。

如果文件格式是 IniFormat，那么它将在应用程序的本地目录中是“Settings/MySoft/Star Runner.ini”。

可以使用 setPath() 方法更改 .ini 和 .conf 文件的路径。在 Unix、macOS 和 iOS 上，用户可以通过设置 XDG_CONFIG_HOME 环境变量来覆盖它们；有关详细信息，请参见 setPath()。

直接访问 INI 和 .plist 文件#

有时您确实需要访问存储在特定文件或注册表路径中的设置。在所有平台上，如果直接读取 INI 文件，可以使用以文件名作为第一个参数的 QSettings 构造函数，并使用 IniFormat 作为第二个参数。例如

QSettings settings("/home/petra/misc/myapp.ini",
                   QSettings.IniFormat)

然后您可以使用 QSettings 对象来读取和写入文件中的设置。

在 macOS 和 iOS 上，通过将 NativeFormat 作为第二个参数，您可以访问属性列表 .plist 文件。例如

QSettings settings("/Users/petra/misc/myapp.plist",
                   QSettings.NativeFormat)

直接访问 Windows 注册表#

在 Windows 上，QSettings 允许您访问使用 QSettings （或支持的格式，例如字符串数据）编写的系统注册表中的设置。这可以通过以注册表路径和 NativeFormat 构造 QSettings 对象来完成。

例如

QSettings settings("HKEY_CURRENT_USER\\Software\\Microsoft\\Office",
                   QSettings.NativeFormat)

可以通过 QSettings 对象读写（使用正斜杠而不是反斜杠）来读取或写入指定路径下出现的所有注册表条目，就像通常使用一样。

settings.setValue("11.0/Outlook/Security/DontTrustInstalledFiles", 0)

请注意，正如之前提到的，反斜杠字符被 QSettings 用来分隔子键。因此，您不能读取或写入包含斜杠或反斜杠的 Windows 注册表条目；如果您需要这样做，应使用原生 Windows API。

访问 Windows 中的常见注册表设置#

在Windows平台上，一个键可以同时具有值和子键。其默认值可以通过用“默认”或“.”代替子键来访问。

settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy", "Milkyway")
settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Sun", "OurStar")
settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default") # returns "Milkyway"

在其他非Windows平台上，“默认”和“.”将被视为常规子键。

平台限制#

虽然QSettings试图抹平不同支持平台间的差异，但在移植您的应用程序时，您仍应了解一些明显的差异。

  • Windows系统注册表有以下限制：子键名称不能超过255个字符，条目的值不能超过16383个字符，一个键的所有值加起来不能超过65535个字符。绕过这些限制的一种方法是使用IniFormat而不是NativeFormat格式来存储设置。

  • 在Windows上，当使用Windows系统注册表时，QSettings不保留值的原始类型。因此，设置新的值时，值的类型可能会变化。例如，类型为REG_EXPAND_SZ的值将更改为REG_SZ。

  • 在macOS和iOS上，allKeys()将返回一些针对所有应用程序全局应用设置额外的键。这些键可以通过value()读取，但不能更改，只能被覆盖。调用setFallbacksEnabled（false）将隐藏这些全局设置。

  • 在 macOS 和 iOS 上，QSettings 库使用的 CFPreferences API 期望使用互联网域名而不是组织名称。为了提供一个统一的 API，QSettings 会从组织名称派生一个假域名（除非组织名称已经是一个域名，例如 OpenOffice.org）。该算法将在公司名称后追加 “.com”，并将空格和其他非法字符替换为连字符。如果您想指定不同的域名，可以在您的 main() 函数中调用 setOrganizationDomain()、setOrganizationName() 和 setApplicationName()，然后使用默认的 QSettings 构造函数。另一种解决方案是使用预处理器指令，例如

    #ifdef Q_OS_DARWIN
    settings = QSettings("grenoullelogique.fr", "Squash")
#else
    settings = QSettings("Grenoulle Logique", "Squash")
#endif

  • 在 macOS 上，访问不属于当前用户设置（即 SystemScope）的权限在 10.7（狮子）版本中发生了变化。在此版本之前，具有管理员权限的用户可以访问这些设置。对于 10.7 和 10.8（山狮），只有 root 可以访问。然而，10.9（山达基）再次改变了这一规则，但仅针对本地格式（即 plist 文件）。

另请参阅

QVariant QSessionManager

class Status#

可能的状态值如下：

常量

描述

QSettings.NoError

未发生错误。

QSettings.AccessError

发生了访问错误（例如尝试写入只读文件）。

QSettings.FormatError

发生了格式错误（例如加载格式不正确的 INI 文件）。

另请参阅

status()

class Format#

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

此枚举类型指定了 QSettings 使用的存储格式。

常量

描述

QSettings.NativeFormat

使用平台最合适的存储格式来存储设置。在 Windows 上，这意味着系统注册表；在 macOS 和 iOS 上，这意味着 CFPreferences API；在 Unix 上，这意味着 INI 格式的文本配置文件。

QSettings.Registry32Format

Windows 仅：从在 64 位 Windows 上运行的 64 位应用程序显式访问 32 位系统注册表。在 32 位 Windows 或从 64 位 Windows 上 32 位应用程序，这和指定 NativeFormat 同样工作。此枚举值是在 Qt 5.7 中添加的。

QSettings.Registry64Format

仅限Windows：显式访问64位Windows上运行的32位应用程序的64位系统注册表。在32位Windows或64位Windows上的64位应用程序中，这与指定NativeFormat相同。此枚举值是在Qt 5.7中添加的。

QSettings.IniFormat

将设置存储在INI文件中。请注意，INI文件会丢失数值数据和用于编码它们的字符串之间的区别，因此应将数值写入的数据读回时作为QString处理。

QSettings.WebLocalStorageFormat

仅WASM：将设置存储在当前源的window.localStorage中。如果不允许使用Cookie，则将回退到INI格式。这为每个源提供最多5MiB的存储空间，但访问它是同步的，并且不需要JSPI。

QSettings.WebIndexedDBFormat

仅WASM：将设置存储在当前源的Indexed DB中。如果不允许使用Cookie，则将回退到INI格式。这需要JSPI，但提供的存储空间比WebLocalStorageFormat多。

QSettings.InvalidFormat

由registerFormat()返回的特殊值。

在Unix上，NativeFormat和IniFormat的含义相同，只是文件扩展名不同（NativeFormat为.conf，IniFormat为.ini）。

INI文件格式是一种Windows文件格式，Qt在所有平台上都支持。在没有INI标准的情况下，我们尽量遵循微软的做法，但有以下例外：

  • 如果您存储了QVariant无法转换为QString的类型（例如，QPoint、QRect、QSize等），Qt将使用基于@的语法进行编码。例如：

    pos = @Point(100 100)

    为了最小化兼容性问题，任何不位于值的第一位置或不是Qt类型（如Point、Rect、Size等）后跟的@被视为普通字符。

  • 虽然反斜杠是INI文件中的一个特殊字符，但大多数Windows应用程序不会在文件路径中对反斜杠（\）进行转义

    windir = C:\Windows

    QSettings始终将反斜杠视为特殊字符，并且没有提供用于读取或写入此类条目的API。

  • INI文件格式对键的语法有很大的限制。Qt通过使用%作为键中的转义字符来解决这个问题。此外，如果您将顶级设置（没有斜杠的键，例如，“someKey”）保存到文件中，它将出现在INI文件的“General”部分中。为了避免覆盖其他键，如果您使用“General/someKey”等键保存内容，则该键将位于“%General”部分，而不是“General”部分。

  • 与现在的许多实现一致，QSettings 会假设 INI 文件中的 values 使用 utf-8 编码。这意味着 values 将被解码为 utf-8 编码的条目并以 utf-8 编写回。为了与旧版本的 Qt 保持向后兼容，INI 文件中的 keys 以 %-编码的格式写入，但可以以 %-编码和 utf-8 格式读取。

与旧版本 Qt 的兼容性#

请注意，这种行为与 Qt 6 之前的 Qt 版本的 QSettings 的行为不同。然而，使用 Qt 5 或更早版本编写的 INI 文件仍可以被基于 Qt 6 的应用程序完全读取（除非已设置不同于 utf8 的 ini 编解码器）。但使用 Qt 6 编写的 INI 文件只有在将“iniCodec”设置为 utf-8 文本编解码器的情况下，才能由旧的 Qt 版本读取。

另请参阅

registerFormat() setPath()

class Scope#

此枚举指定设置是属于特定用户还是由同一系统的所有用户共享。

常量

描述

QSettings.UserScope

将设置存储在特定于当前用户的位置（例如，在用户的主目录中）。

QSettings.SystemScope

将设置存储在全局位置，以便同一台机器上的所有用户都可以访问相同的设置集。

另请参阅

setPath()

__init__(format, scope, organization[, application=""[, parent=None]])#
参数:

  • format – Format

  • scope – Scope

  • organization – str

  • application – str

  • parent – QObject

构造一个 QSettings 对象，该对象用于从名为 application 的应用程序从名为 organization 的组织中访问设置，并且具有父级 parent。

如果 scope 为 UserScope ，则 QSettings 对象首先搜索用户特定设置，然后再回退搜索系统范围设置。如果 scope 为 SystemScope ，则 QSettings 对象会忽略用户特定设置，提供对系统范围设置的访问。

如果 format 是 NativeFormat ，则使用本地 API 存储设置。如果 format 是 IniFormat ，则使用 INI 格式。

如果没有提供应用程序名称，则 QSettings 对象将仅访问组织范围内的 locations 。

__init__([parent=None])
参数:

parent – QObject

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

使用 setOrganizationName() ， setOrganizationDomain() ，和 setApplicationName() 调用预先设置的应用程序和组织设置来构建 QSettings 对象。

作用域为 UserScope ，格式为 defaultFormat() （默认为 NativeFormat）。在调用此构造函数之前使用 setDefaultFormat() 更改此构造函数使用的默认格式。

以下代码

settings = QSettings("Moose Soft", "Facturo-Pro")

等同于

QCoreApplication.setOrganizationName("Moose Soft")
QCoreApplication.setApplicationName("Facturo-Pro")
settings = QSettings()

如果之前未调用过setOrganizationName() 和 setApplicationName()，则 QSettings 对象将无法读取或写入任何设置，且 status() 将返回 AccessError。

您应该同时提供域名（默认用于 macOS 和 iOS）和名称（默认用于其他地方），尽管如果您只提供了一个，它也将在所有平台上使用，但这将与该文件常规命名方式不符合。

__init__(organization[, application=""[, parent=None]])
参数:

  • organization – str

  • application – str

  • parent – QObject

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

构造一个 QSettings 对象，该对象用于从名为 application 的应用程序从名为 organization 的组织中访问设置，并且具有父级 parent。

示例

settings = QSettings("Moose Tech", "Facturo-Pro")

作用域设置为 UserScope，格式设置为NativeFormat（即调用此构造函数之前先调用 setDefaultFormat() 无效）。

另请参阅

setDefaultFormat() Fallback Mechanism

__init__(fileName, format[, parent=None])
参数:

构建一个用于访问存储在名为 fileName 的文件中的设置的 QSettings 对象，其父对象为 parent。如果该文件不存在，则将其创建。

如果 format 为 NativeFormat ，则 fileName 的含义取决于平台。在 Unix 上，fileName 是 INI 文件的名称。在 macOS 和 iOS 上，fileName 是 .plist 文件的名称。在 Windows 上，fileName 是系统注册表中的一个路径。

如果 format 为 IniFormat ，则 fileName 是 INI 文件的名称。

警告

此函数提供方便。对于访问由 Qt 生成的 INI 或 .plist 文件效果很好，但可能在由其他程序生成的此类文件中发现的一些语法上失败。特别是要注意以下限制：

  • QSettings 没有读取 INI “路径”条目的方法，即带转义斜杠字符的条目。（这是因为这些条目模糊不清且无法自动解决。）

  • 在 INI 文件中，QSettings 在某些上下文中使用 @ 字符作为元字符，以编码 Qt 特定的数据类型（例如，@Rect），因此当它出现在纯 INI 文件中时，可能会误解释它。

另请参阅

fileName()

__init__(scope, organization[, application=""[, parent=None]])
参数:

  • scope – Scope

  • organization – str

  • application – str

  • parent – QObject

构造一个 QSettings 对象，该对象用于从名为 application 的应用程序从名为 organization 的组织中访问设置，并且具有父级 parent。

如果 scope 为 UserScope ，则 QSettings 对象首先搜索用户特定设置，然后再回退搜索系统范围设置。如果 scope 为 SystemScope ，则 QSettings 对象会忽略用户特定设置，提供对系统范围设置的访问。

存储格式设置为 NativeFormat（即调用此构造函数之前调用 setDefaultFormat() 无效）。

如果没有提供应用程序名称，则 QSettings 对象将仅访问组织范围内的 locations 。

另请参阅

setDefaultFormat()

__init__(scope[, parent=None])
参数:

以与 QSettings（QObject *parent）中的相同方式构建一个 QSettings 对象，但具有给定的 scope。

另请参阅

QSettings(QObject *parent)

allKeys()#
返回类型：

字符串列表

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

返回所有键（包括子键）的列表，这些键可以使用QSettings对象读取。

示例

settings = QSettings()
settings.setValue("fridge/color", QColor(Qt.white))
settings.setValue("fridge/size", QSize(32, 96))
settings.setValue("sofa", True)
settings.setValue("tv", False)
keys = settings.allKeys()
# keys: ["fridge/color", "fridge/size", "sofa", "tv"]

如果使用beginGroup()设置了组，则只返回该组中的键，不包括组前缀

settings.beginGroup("fridge")
keys = settings.allKeys()
# keys: ["color", "size"]

另请参阅

childGroups() childKeys()

applicationName()#
返回类型：

str

返回用于存储设置的程序名称。

另请参阅

applicationName() format() scope() organizationName()

beginGroup(prefix)#
参数:

prefix - str

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

将prefix附加到当前组。

当前组会自动添加到指定给QSettings的键上。此外，基于组的查询函数，例如childGroups()、childKeys()和allKeys()，都是基于组的。默认情况下，不设置任何组。

组很有用，可以避免反复输入相同的设置路径。例如

settings.beginGroup("mainwindow")
settings.setValue("size", win.size())
settings.setValue("fullScreen", win.isFullScreen())
settings.endGroup()
settings.beginGroup("outputpanel")
settings.setValue("visible", panel.isVisible())
settings.endGroup()

这将为以下三个设置的值赋值

  • mainwindow/size

  • mainwindow/fullScreen

  • outputpanel/visible

调用endGroup()将当前组重置为调用对应的beginGroup()之前的值。组可以是嵌套的。

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

endGroup() group()

beginReadArray(prefix)#
参数:

prefix - str

返回类型：

int

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

将 prefix 添加到当前组，并从数组开始读取。返回数组的尺寸。

示例

class Login():
    userName = QString()
    password = QString()

logins = QList()
...
settings = QSettings()
size = settings.beginReadArray("logins")
for i in range(0, size):
    settings.setArrayIndex(i)
    login = Login()
    login.userName = settings.value("userName").toString()
    login.password = settings.value("password").toString()
    logins.append(login)

settings.endArray()

首先使用 beginWriteArray() 来写入数组。

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

beginWriteArray() endArray() setArrayIndex()

beginWriteArray(prefix[, size=-1])#
参数:

  • prefix - str

  • size – int

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

将 prefix 添加到当前组，并开始写入大小为 size 的数组。如果 size 为 -1（默认值），它将根据已写入条目的索引自动确定。

如果您有很多重复的键集合情况，可以使用数组来简化您的工作。例如，假设您想保存用户名和密码的变量长度列表。然后可以编写

class Login():
    userName = QString()
    password = QString()

logins = QList()
...
settings = QSettings()
settings.beginWriteArray("logins")
for i in range(0, logins.size()):
    settings.setArrayIndex(i)
    settings.setValue("userName", logins.at(i).userName)
    settings.setValue("password", logins.at(i).password)

settings.endArray()

生成的键将具有以下形式

  • logins/size

  • logins/1/userName

  • logins/1/password

  • logins/2/userName

  • logins/2/password

  • logins/3/userName

  • logins/3/password

  • …

要读取数组，请使用 beginReadArray() 。

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

beginReadArray() endArray() setArrayIndex()

childGroups()#
返回类型：

字符串列表

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

返回一个包含使用 QSettings 对象读取的键的所有顶级组的键列表。

示例

settings = QSettings()
settings.setValue("fridge/color", QColor(Qt.white))
settings.setValue("fridge/size", QSize(32, 96))
settings.setValue("sofa", True)
settings.setValue("tv", False)
groups = settings.childGroups()
# groups: ["fridge"]

如果使用了 beginGroup() 设置组，则返回该组中第一级键，而不包含组前缀。

settings.beginGroup("fridge")
groups = settings.childGroups()
# groups: []

您可以使用 childKeys() 和 childGroups() 递归地遍历整个设置层次结构。

另请参阅

childKeys() allKeys()

childKeys()#
返回类型：

字符串列表

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

返回一个列表，包含可以通过该QSettings对象读取的所有顶级键。

示例

settings = QSettings()
settings.setValue("fridge/color", QColor(Qt.white))
settings.setValue("fridge/size", QSize(32, 96))
settings.setValue("sofa", True)
settings.setValue("tv", False)
keys = settings.childKeys()
# keys: ["sofa", "tv"]

如果使用beginGroup()设置了组，则返回该组中的顶级键，不包括组前缀

settings.beginGroup("fridge")
keys = settings.childKeys()
# keys: ["color", "size"]

您可以通过递归地使用childKeys()和childGroups()来遍历整个设置层次结构。

另请参阅

childGroups() allKeys()

clear()#

删除与该QSettings对象关联的原始位置中所有条目。

不会删除备用位置的条目。

如果您只想删除当前group()中的条目，请使用 remove(“”) 而不是 remove(“”)。

contains(key)#
参数:

key – 字符串

返回类型：

布尔型

如果存在名为 key 的设置，则返回 true；否则返回 false。

如果使用 beginGroup() 设置了组，则认为 key 是相对于该组的。

请注意，Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为了避免兼容性问题，请参阅 Section and Key Syntax 规则。

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

value() setValue()

static defaultFormat()#
返回类型：

格式

返回用于在QSettings构造函数中存储设置的默认文件格式。如果没有设置默认格式，则使用NativeFormat。

endArray()#

通过beginReadArray()或beginWriteArray()开始数组后，关闭数组。

endGroup()#

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

将组重置为对应的beginGroup()调用之前的设置。

示例

settings.beginGroup("alpha")
# settings.group() == "alpha"
settings.beginGroup("beta")
# settings.group() == "alpha/beta"
settings.endGroup()
# settings.group() == "alpha"
settings.endGroup()
# settings.group() == ""

另请参阅

beginGroup() group()

fallbacksEnabled()#
返回类型：

布尔型

如果启用回退，则返回true；否则返回false。

默认情况下，启用回退。

另请参阅

setFallbacksEnabled()

fileName()#
返回类型：

str

返回使用此QSettings对象写入设置的路径。

在Windows中，如果格式为NativeFormat，则返回值是系统注册表路径，而不是文件路径。

另请参阅

isWritable() format()

format()#
返回类型：

格式

返回存储设置的格式。

group()#
返回类型：

str

返回当前组。

另请参阅

beginGroup() endGroup()

isAtomicSyncRequired()#
返回类型：

布尔型

如果允许使用QSettings仅执行原子保存和重新加载（同步）设置，则返回 true。如果允许直接将设置内容保存到配置文件，则返回 false。

默认为 true。

isWritable()
返回类型：

布尔型

如果可以通过此QSettings对象写入设置，则返回 true；否则返回 false。

可能返回 false 的原因之一是 QSettings 操作的是只读文件。

警告

此函数并不完全可靠，因为文件权限可以随时更改。

另请参阅

fileName() status() sync()

organizationName()#
返回类型：

str

返回用于存储设置的机构名称。

remove(key)#
参数:

key – 字符串

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

移除设置 key 和 key 的任何子设置。

示例

settings = QSettings()
settings.setValue("ape")
settings.setValue("monkey", 1)
settings.setValue("monkey/sea", 2)
settings.setValue("monkey/doe", 4)
settings.remove("monkey")
keys = settings.allKeys()
# keys: ["ape"]

请注意，如果其中一个回退位置包含具有相同键的设置，则在调用 remove() 之后，该设置将可见。

如果 key 是空字符串，则将移除当前 group() 中的所有键。例如

settings = QSettings()
settings.setValue("ape")
settings.setValue("monkey", 1)
settings.setValue("monkey/sea", 2)
settings.setValue("monkey/doe", 4)
settings.beginGroup("monkey")
settings.remove("")
settings.endGroup()
keys = settings.allKeys()
# keys: ["ape"]

请注意，Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为了避免兼容性问题，请参阅 Section and Key Syntax 规则。

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

setValue() value() contains()

scope()#
返回类型：

作用域

返回用于存储设置的并行{}。

setArrayIndex(i)#
参数:

i - 整数

将当前数组索引设置为 i。调用如 setValue()、value()、remove() 和 contains() 等函数将在该索引处的数组条目上操作。

在调用此函数之前，您必须调用 beginReadArray() 或 beginWriteArray()。

setAtomicSyncRequired(enable)#
参数:

enable – 布尔型

配置是否需要使用原子操作来保存和重新加载（同步）设置。如果 enable 参数为 true（默认值），则 sync() 将仅执行原子同步操作。如果无法执行，sync() 将失败，并且 status() 将是错误状态。

将此属性设置为 false 允许 QSettings 直接写入配置文件，并忽略尝试锁定配置文件以防止其他进程同时写入时的任何错误。由于可能导致数据损坏，所以应小心使用此选项，但在某些情况下（如存在于无法写入目录或 NTFS 可选数据流中的配置文件）是必须的。

有关该功能的更多信息，请参阅 QSaveFile。

静态 setDefaultFormat(format)#
参数:

format – Format

设置默认文件格式为指定的 format，用于保存 QSettings 构造函数（ QObject *) 的设置。

如果未设置默认格式，则使用 NativeFormat。请参见您所使用的 QSettings 构造函数的文档，以查看该构造函数是否会忽略此函数。

另请参阅

defaultFormat() format()

setFallbacksEnabled(b)#
参数:

b – bool

设置是否开启回退为 b。

默认情况下，启用回退。

另请参阅

fallbacksEnabled()

static setPath(format, scope, path)#
参数:

设置用于存储指定 format 和 scope 的设置的路径，为 path。其中 format 可以为自定义格式。

下表总结了默认值

平台

格式

作用域

路径

Windows

IniFormat

UserScope

FOLDERID_RoamingAppData

SystemScope

FOLDERID_ProgramData

Unix

NativeFormat , IniFormat

UserScope

$HOME/.config

SystemScope

/etc/xdg

macOS 和 iOS

IniFormat

UserScope

$HOME/.config

SystemScope

/etc/xdg

Unix、macOS 和 iOS 上的默认 UserScope 路径（$HOME/.config 或 $HOME/Settings）可以被用户通过设置 XDG_CONFIG_HOME 环境变量覆盖。Unix、macOS 和 iOS 上的默认 SystemScope 路径（/etc/xdg）在构建 Qt 库时可以通过使用 configure 脚本的 -sysconfdir 标志进行覆盖（有关详细信息，请参阅 QLibraryInfo）。

在 Windows、macOS 和 iOS 上设置 NativeFormat 路径没有任何效果。

警告

此函数不影响现有的 QSettings 对象。

另请参阅

registerFormat()

setValue(key, value)#
参数:

  • key – 字符串

  • value – 对象

警告

本部分包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

将设置 key 的值设置为 value。如果 key 已存在，则重写之前的值。

请注意，Windows 注册表和 INI 文件使用不区分大小写的键，而 macOS 和 iOS 上的 CFPreferences API 使用区分大小写的键。为了避免兼容性问题，请参阅 Section and Key Syntax 规则。

示例

settings = QSettings()
settings.setValue("interval", 30)
settings.value("interval").toInt() # returns 30
settings.setValue("interval", 6.55)
settings.value("interval").toDouble() # returns 6.55

注意

在6.4之前的Qt版本中，此函数接受QString，而不是QAnyStringView。

另请参阅

value() remove() contains()

status()#
返回类型：

状态

返回表示 QSettings 遇到的第一个错误的代码状态，如果没有发生错误，则为 NoError。

请注意，QSettings 会延迟执行某些操作。因此，您可能希望调用 sync() 来确保在调用 status() 之前将存储在 QSettings 中的数据写入磁盘。

另请参阅

sync()

sync()#

将任何未保存的更改写入永久存储，并重新加载在此期间由其他应用程序更改的任何设置。

此函数会自动由 QSettings 的析构函数和事件循环定期调用，因此通常不需要自己调用它。

另请参阅

status()

value(key)#
参数:

key – 字符串

返回类型：

对象

value(arg__1[, defaultValue={}[, type=None]])
参数:

  • arg__1 – 字符串

  • defaultValue – 对象

  • type – 对象

返回类型：

对象

自定义重载，向 value() 函数添加一个可选的命名参数，以自动转换函数返回的类型。

这种情况的一个例子可能是一个包含单元素列表值的 ini 文件

settings.setValue('var', ['a'])

该 ini 文件将是

[General]
var=a  # we cannot know that this is a list!

一旦我们读取它，我们就可以指定我们是否想要默认行为、一个字符串或者将输出转换为列表。

settings.value('var', type=list) # 将获取 ["a"]