PySide6.QtCore.QSettings

class QSettings

QSettings 类提供了持久的、平台无关的应用程序设置。更多…

PySide6.QtCore.QSettings 的继承图

概要

方法

静态函数

注意

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

详细描述

警告

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

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

QSettings 是对这些技术的抽象，使您能够以可移植的方式保存和恢复应用程序设置。它还支持 custom storage formats 。

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()

（在这里，我们还指定了组织的互联网域名。当设置了互联网域名时，它将在macOS和iOS上使用，而不是组织名称，因为macOS和iOS应用程序通常使用互联网域名来标识自己。如果没有设置域名，则会从组织名称中派生一个假域名。详情请参阅下面的平台特定 说明。）

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

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

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

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

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

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

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

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

QVariant 和 GUI 类型

因为 QVariant 是 Qt Core 模块的一部分，它无法提供到诸如 QColor、QImage 和 QPixmap 等数据类型的转换函数，这些数据类型属于 Qt GUI。换句话说，QVariant 中没有 toColor()、toImage() 或 toPixmap() 函数。

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

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

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

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()。

回退机制

假设你已经创建了一个QSettings对象，组织名称为MySoft，应用程序名称为Star Runner。当你查找一个值时，最多会按顺序搜索四个位置：

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

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

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

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

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

如果在第一个位置找不到键，搜索将继续在第二个位置进行，依此类推。这使您能够存储系统范围或组织范围的设置，并在每个用户或每个应用程序的基础上覆盖它们。要关闭此机制，请调用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支持的所有平台，并且仍然为您提供了很大的灵活性，而无需您指定任何文件名或注册表路径。

如果你想在所有平台上使用INI文件而不是原生API，你可以将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 的更改之外）。

平台特定说明

应用程序设置存储的位置

正如Fallback Mechanism部分所述，QSettings根据设置是用户特定还是系统范围以及设置是应用程序特定还是组织范围，将应用程序的设置存储在最多四个位置。为了简单起见，我们假设组织名为MySoft，应用程序名为Star Runner。

在Unix系统上，如果文件格式是NativeFormat，默认情况下会使用以下文件：

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

  2. $HOME/.config/MySoft.conf

  3. 对于每个目录

    在 $XDG_CONFIG_DIRS 中：/MySoft/Star Runner.conf

  4. 对于每个目录

    在 $XDG_CONFIG_DIRS 中：/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”。

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

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

  2. $HOME/.config/MySoft.ini

  3. 对于每个目录

    在 $XDG_CONFIG_DIRS 中：/MySoft/Star Runner.ini

  4. 对于每个目录

    在 $XDG_CONFIG_DIRS 中：/MySoft.ini

注意

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

在Windows上，使用以下文件：

  1. FOLDERID_RoamingAppData\MySoft\Star Runner.ini

  2. FOLDERID_RoamingAppData\MySoft.ini

  3. FOLDERID_ProgramData\MySoft\Star Runner.ini

  4. FOLDERID_ProgramData\MySoft.ini

以FOLDERID_为前缀的标识符是特殊的项目ID列表，需要传递给Win32 API函数SHGetKnownFolderPath()以获取相应的路径。

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

FOLDERID_ProgramData 通常指向 C:\ProgramData。

如果文件格式是IniFormat，则在应用程序的主目录中为“Settings/MySoft/Star Runner.ini”。

.ini 和 .conf 文件的路径可以通过 setPath() 进行更改。在 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上，一个键可以同时具有值和子键。通过使用“Default”或“.”代替子键来访问其默认值：

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平台上，“Default”和“.”将被视为常规子键。

平台限制

虽然QSettings试图平滑处理不同支持平台之间的差异，但在移植应用程序时，您仍应注意一些差异：

  • Windows系统注册表有以下限制：子键不能超过255个字符，条目的值不能超过16,383个字符，键的所有值不能超过65,535个字符。解决这些限制的一种方法是使用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（Lion）版本中发生了变化。在该版本之前，拥有管理员权限的用户可以访问这些设置。对于10.7和10.8（Mountain Lion），只有root用户可以访问。然而，10.9（Mavericks）再次改变了这一规则，但仅适用于原生格式（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中，适用于当前源。如果不允许使用cookies，则回退到INI格式。这为每个源提供最多5MiB的存储空间，但访问是同步的，且不需要JSPI。

QSettings.WebIndexedDBFormat

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

QSettings.InvalidFormat

registerFormat() 返回的特殊值。

在Unix上，NativeFormat和IniFormat表示相同的意思，只是文件扩展名不同（.conf 用于NativeFormat，.ini 用于IniFormat）。

INI文件格式是Qt在所有平台上支持的Windows文件格式。在没有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 文件中的 值 是 utf-8 编码的。这意味着 值 将被解码为 utf-8 编码的条目，并以 utf-8 编码写回。为了保持与旧版 Qt 的向后兼容性，INI 文件中的 键 以 %-编码格式写入，但可以以 %-编码和 utf-8 格式读取。

与旧版Qt版本的兼容性

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

另请参阅

registerFormat() setPath()

class Scope

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

常量

描述

QSettings.UserScope

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

QSettings.SystemScope

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

另请参阅

setPath()

__init__([parent=None])
Parameters:

父对象 – QObject

警告

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

构造一个QSettings对象，用于访问之前通过调用setOrganizationName()、setOrganizationDomain()和setApplicationName()设置的应用程序和组织的设置。

范围是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__(scope[, parent=None])
Parameters:

以与QSettings（QObject *parent）相同的方式构造QSettings对象，但使用给定的scope。

另请参阅

QSettings(QObject *parent)

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

构造一个QSettings对象，用于访问存储在名为fileName的文件中的设置，父对象为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__(organization[, application=""[, parent=None]])
Parameters:

  • organization – str

  • application – str

  • parent – QObject

警告

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

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

示例：

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

范围设置为UserScope，格式设置为NativeFormat（即在调用此构造函数之前调用setDefaultFormat()没有效果）。

另请参阅

setDefaultFormat() 回退 机制

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

  • scope – Scope

  • organization – str

  • application – str

  • parent – QObject

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

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

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

如果没有给出应用程序名称，QSettings 对象将只能访问组织范围内的 locations。

另请参阅

setDefaultFormat()

__init__(format, scope, organization[, application=""[, parent=None]])
Parameters:

  • format – Format

  • scope – Scope

  • organization – str

  • application – str

  • parent – QObject

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

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

如果 format 是 NativeFormat，则使用原生 API 来存储设置。如果 format 是 IniFormat，则使用 INI 格式。

如果没有给出应用程序名称，QSettings 对象将只能访问组织范围内的 locations。

allKeys()
Return type:

字符串列表

警告

本节包含从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()
Return type:

字符串

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

beginGroup(prefix)
Parameters:

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() 调用之前的状态。组可以嵌套。

注意

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

另请参阅

endGroup() group()

beginReadArray(prefix)
Parameters:

prefix – str

Return type:

整数

警告

本节包含从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()来写入数组。

注意

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

另请参阅

beginWriteArray() endArray() setArrayIndex()

beginWriteArray(prefix[, size=-1])
Parameters:

  • 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() 。

注意

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

另请参阅

beginReadArray() endArray() setArrayIndex()

childGroups()
Return type:

字符串列表

警告

本节包含从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()
Return type:

字符串列表

警告

本节包含从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(“”)代替。

contains(key)
Parameters:

key – str

Return type:

布尔

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

如果使用beginGroup()设置了一个组，key将被视为相对于该组。

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

注意

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

另请参阅

value() setValue()

static defaultFormat()
Return type:

格式

返回用于存储QSettings（QObject *）构造函数设置的默认文件格式。如果未设置默认格式，则使用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()
Return type:

布尔

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

默认情况下，回退功能已启用。

另请参阅

setFallbacksEnabled()

fileName()
Return type:

字符串

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

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

另请参阅

isWritable() format()

format()
Return type:

格式

返回用于存储设置的格式。

group()
Return type:

字符串

返回当前组。

另请参阅

beginGroup() endGroup()

isAtomicSyncRequired()
Return type:

布尔

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

默认是 true。

isWritable()
Return type:

布尔

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

isWritable() 可能返回 false 的一个原因是如果 QSettings 操作的是一个只读文件。

警告

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

另请参阅

fileName() status() sync()

organizationName()
Return type:

字符串

返回用于存储设置的组织名称。

remove(key)
Parameters:

key – str

警告

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

移除设置 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 和 Key Syntax规则。

注意

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

另请参阅

setValue() value() contains()

scope()
Return type:

范围

返回用于存储设置的范围。

setArrayIndex(i)
Parameters:

i – 整数

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

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

setAtomicSyncRequired(enable)
Parameters:

enable – 布尔值

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

将此属性设置为false将允许QSettings直接写入配置文件，并忽略尝试锁定以防止其他进程同时写入时的任何错误。由于存在潜在的损坏风险，应谨慎使用此选项，但在某些情况下是必需的，例如存在于其他不可写目录或NTFS备用数据流中的IniFormat配置文件。

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

static setDefaultFormat(format)
Parameters:

format – Format

将默认文件格式设置为给定的format，该格式用于存储QSettings（QObject *）构造函数的设置。

如果没有设置默认格式，将使用NativeFormat。请参阅您正在使用的QSettings构造函数的文档，以查看该构造函数是否会忽略此函数。

另请参阅

defaultFormat() format()

setFallbacksEnabled(b)
Parameters:

b – 布尔值

设置是否启用回退为b。

默认情况下，回退功能已启用。

另请参阅

fallbacksEnabled()

static setPath(format, scope, path)
Parameters:

设置用于存储给定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)
Parameters:

  • key – str

  • value – 对象

警告

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

将设置key的值设置为value。如果key已经存在，则覆盖之前的值。

请注意，Windows注册表和INI文件使用不区分大小写的键，而macOS和iOS上的CFPreferences API使用区分大小写的键。为了避免可移植性问题，请参阅Section 和 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

注意

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

另请参阅

value() remove() contains()

status()
Return type:

状态

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

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

另请参阅

sync()

sync()

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

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

另请参阅

status()

value(key)
Parameters:

key – str

Return type:

对象

另请参阅

setValue()

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

  • arg__1 – str

  • defaultValue – 对象

  • type – 对象

Return type:

对象

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

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

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

ini 文件将会是：

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

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

settings.value(‘var’) # 将获取 “a” settings.value(‘var’, type=list) # 将获取 [“a”]