Qt开发：QSettings的介绍和使用

一、QSettings的常用构造函数

*1.1 QSettings(QSettings::Scope scope, QObject parent = nullptr)
作用：用于在使用默认组织名和应用名的前提下，指定作用域（Scope），决定设置是保存为“当前用户”级别，还是“系统所有用户”级别。
构造函数定义解析：

• scope：作用域，决定设置保存在哪个层级。 QSettings::UserScope（默认）设置只对当前用户生效。QSettings::SystemScope设置对系统中所有用户生效（在 Windows 上写入注册表的 HKEY_LOCAL_MACHINE；可能需要管理员权限）。
• parent：可选的 QObject 父对象。

**注意：**使用此构造函数时，必须在程序启动前调用以下两个函数之一来设置组织和应用名，否则不会知道保存在哪个路径下：

QCoreApplication::setOrganizationName("MyCompany");
QCoreApplication::setApplicationName("MyApp");

使用场景示例
示例 1：用户级别设置（UserScope）

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>int main(int argc, char *argv[]) {QCoreApplication app(argc, argv);QCoreApplication::setOrganizationName("MyCompany");QCoreApplication::setApplicationName("MyApp");QSettings settings(QSettings::UserScope);  // 只对当前用户生效settings.setValue("language", "zh_CN");QString lang = settings.value("language").toString();qDebug() << "Language:" << lang;return 0;
}

输出：

示例 2：系统级别设置（SystemScope）

QCoreApplication::setOrganizationName("MyCompany");
QCoreApplication::setApplicationName("MyApp");QSettings settings(QSettings::SystemScope);  // 对所有用户生效
settings.setValue("installDir", "C:/Program Files/MyApp");

使用建议：

• 配置保存给个人用户用：推荐使用 UserScope。
• 默认设置、安装路径、日志等级等全局设置：可以用 SystemScope，但需要注意权限问题。
• 一般应用程序在没有管理员权限时默认使用 UserScope，管理员工具或安装器可以使用 SystemScope。

*1.2 QSettings(QObject parent = nullptr)

• 使用平台原生格式保存设置：
  • Windows：写入注册表（默认 UserScope）
  • inux/macOS：写入 ~/.config/组织名/应用名.conf 或 plist
• 使用默认组织名和应用名（必须先用 QCoreApplication::setOrganizationName() 和 setApplicationName() 设置）
• 默认保存为当前用户作用域（UserScope）

使用前提：
必须设置组织名和应用名，否则这个构造函数无法确定设置文件的路径。

QCoreApplication::setOrganizationName("MyCompany");
QCoreApplication::setApplicationName("MyApp");

示例代码：

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>int main(int argc, char *argv[])
{QCoreApplication app(argc, argv);// 设置默认组织和应用名（非常关键）QCoreApplication::setOrganizationName("MyCompany");QCoreApplication::setApplicationName("MyApp");QSettings settings;  // 使用默认路径、作用域和格式// 写入设置settings.setValue("window/width", 800);settings.setValue("window/height", 600);// 读取设置int width = settings.value("window/width", 1024).toInt();int height = settings.value("window/height", 768).toInt();qDebug() << "Window size:" << width << "x" << height;return 0;
}

输出：

设置保存的位置：
Windows 注册表路径：

HKEY_CURRENT_USER\Software\MyCompany\MyApp

Linux 配置文件路径：

~/.config/MyCompany/MyApp.conf

macOS 配置文件路径（Plist）：

~/Library/Preferences/com.MyCompany.MyApp.plist

*1.3 QSettings(const QString &fileName, QSettings::Format format, QObject parent = nullptr)

参数解释：

• fileName：设置文件路径（可以是绝对路径或相对路径）。
• format：文件格式，常用值：
  • QSettings::IniFormat（推荐）：跨平台文本格式，最常见。
• QSettings::NativeFormat：平台原生格式（Windows 为注册表，不推荐与 fileName 搭配使用）。
• parent：父对象，一般可以忽略。

示例：使用 ini 文件保存配置

#include <QSettings>
#include <QDebug>int main()
{QSettings settings("config.ini", QSettings::IniFormat);  // 自动创建 ini 文件// 写入设置settings.setValue("login/username", "admin");settings.setValue("login/remember", true);// 读取设置QString username = settings.value("login/username", "guest").toString();bool remember = settings.value("login/remember", false).toBool();qDebug() << "Username:" << username;qDebug() << "Remember login:" << remember;return 0;
}

config.ini 文件内容会是：

[login]
username=admin
remember=true

示例：带完整路径保存

QString fullPath = QCoreApplication::applicationDirPath() + "/settings/user_config.ini";
QSettings settings(fullPath, QSettings::IniFormat);

这样可以控制配置文件保存位置，比如放在用户目录、程序目录、U盘目录等。

*1.4 QSettings(QSettings::Format format, QSettings::Scope scope,
const QString &organization, const QString &application = QString(),
QObject parent = nullptr)

这是 QSettings 中最灵活、可控性最高的构造函数，允许我们自定义：

• 配置文件的 格式（如 INI、Native）
• 设置的 作用域（用户级 / 系统级）
• 设置的 组织名 / 应用名

参数解析：

使用示例：用户作用域 + INI 格式

QSettings settings(QSettings::IniFormat, QSettings::UserScope,"MyCompany", "MyApp");settings.setValue("theme", "dark");

会在 Linux 上保存到：

~/.config/MyCompany/MyApp.conf

在 Windows 上保存到：

%APPDATA%\MyCompany\MyApp.ini

使用示例：系统作用域 + 原生格式（如注册表）

QSettings settings(QSettings::NativeFormat, QSettings::SystemScope,"MyCompany", "MyApp");settings.setValue("installPath", "C:/Program Files/MyApp");

在 Windows 下会写入：

HKEY_LOCAL_MACHINE\Software\MyCompany\MyApp

注意：系统作用域在 Windows 下可能需要管理员权限！

无应用名（组织级设置）

QSettings settings(QSettings::IniFormat, QSettings::UserScope,"MyCompany");  // 仅组织名，没有应用名settings.setValue("globalLanguage", "zh_CN");

INI 文件将是：

~/.config/MyCompany.ini

结构上不包含 [App] 层级，适用于跨应用共享的设置。

*1.5 QSettings(QSettings::Scope scope, const QString &organization,
const QString &application = QString(), QObject parent = nullptr)

参数说明：

这是 QSettings 的一种构造方式，用于指定作用域（Scope）、组织名 和 应用名，但使用的是 平台原生格式（NativeFormat）。

格式固定为 NativeFormat：

• Windows 上使用注册表；
• macOS 使用 .plist；
• Linux 使用标准位置配置文件（如 ~/.config/…）。

示例用法
示例 1：用户作用域（当前用户）+ 组织 + 应用

QSettings settings(QSettings::UserScope, "MyCompany", "MyApp");
settings.setValue("ui/theme", "dark");

Windows 存储位置：

HKEY_CURRENT_USER\Software\MyCompany\MyApp

Linux/macOS：

~/.config/MyCompany/MyApp.conf 或 plist

示例 2：系统作用域（所有用户）+ 组织 + 应用

QSettings settings(QSettings::SystemScope, "MyCompany", "MyApp");
settings.setValue("installPath", "C:/Program Files/MyApp");

存储位置（需权限）
Windows：

HKEY_LOCAL_MACHINE\Software\MyCompany\MyApp

Linux：

/etc/xdg/MyCompany/MyApp.conf

示例 3：仅组织级设置（无应用名）

QSettings settings(QSettings::UserScope, "MyCompany");
settings.setValue("globalLanguage", "zh_CN");

*1.6 QSettings(const QString &organization, const QString &application = QString(), QObject parent = nullptr)

参数说明：

这是 QSettings 中最常用的构造方式之一，适合大多数 Qt 应用场景，使用默认的平台原生格式 (QSettings::NativeFormat) 和用户作用域 (QSettings::UserScope)。

示例 1：指定组织和应用名

QSettings settings("MyCompany", "MyApp");settings.setValue("window/width", 1280);
settings.setValue("window/height", 720);int w = settings.value("window/width", 800).toInt();
int h = settings.value("window/height", 600).toInt();qDebug() << "Window size:" << w << "x" << h;

这段代码会在各平台保存为：
Windows 注册表

HKEY_CURRENT_USER\Software\MyCompany\MyApp

Linux 配置文件

~/.config/MyCompany/MyApp.conf

macOS plist 文件

~/Library/Preferences/com.MyCompany.MyApp.plist

示例 2：仅组织名，无应用名

QSettings settings("MyCompany");
settings.setValue("language", "zh_CN");

此时，配置是组织级别的：
Windows：

HKEY_CURRENT_USER\Software\MyCompany

Linux：

~/.config/MyCompany.conf

和 QCoreApplication::setOrganizationName() 的区别

二、QSettings的常用函数

2.1 QStringList allKeys() const
作用：

• 返回所有存储的键（完整路径，包含分组信息）
• 用于检查已有的配置项
• 可用于调试、遍历所有设置项

使用示例
获取所有键并打印：

#include <QSettings>
#include <QDebug>int main() {QSettings settings("config.ini", QSettings::IniFormat);// 写入一些测试数据settings.setValue("window/width", 1280);settings.setValue("window/height", 720);settings.setValue("user/name", "Alice");settings.setValue("user/age", 25);// 获取所有键QStringList keys = settings.allKeys();// 输出所有键qDebug() << "All keys:";for (const QString &key : keys) {qDebug() << key << "=" << settings.value(key).toString();}return 0;
}

输出结果：

过滤某个分组的键：
如果只想获取 user/ 下面的键：

QStringList keys = settings.allKeys();
QStringList userKeys = keys.filter("user/");
qDebug() << "User keys:" << userKeys;

输出：

用 allKeys() 遍历并恢复所有设置：

QSettings settings("config.ini", QSettings::IniFormat);
QStringList keys = settings.allKeys();for (const QString &key : keys) {QVariant value = settings.value(key);qDebug() << key << "=" << value.toString();
}

2.2 QString QSettings::applicationName() const
功能说明：返回当前 QSettings 对象中设置的应用程序名称（即构造时传入的 application 参数）。这和 QCoreApplication::applicationName() 不同，它是针对该 QSettings 实例本身的应用名，而非整个应用程序全局。

示例使用：
示例 1：通过构造函数指定应用名

QSettings settings("MyCompany", "SecurityPlatform");
qDebug() << "App name:" << settings.applicationName();

输出：

示例 2：未指定应用名（默认空字符串）

QSettings settings("MyCompany");
qDebug() << "App name:" << settings.applicationName();

输出：

示例 3：结合 QCoreApplication 全局设置

QCoreApplication::setOrganizationName("MyCompany");
QCoreApplication::setApplicationName("BaggageStation");QSettings settings;
qDebug() << "App name:" << settings.applicationName();

输出：

2.3 void QSettings::beginGroup(const QString &prefix)
功能介绍：
beginGroup() 让你进入一个指定的配置组（group），后续对键的读写都将自动加上这个前缀路径。就像进入了某个“文件夹”，操作的键值都变成相对路径。必须配合 endGroup() 使用，否则路径栈会出错。

配合使用的函数：

• void endGroup()：退出当前组，返回上一级。
• QString group() const：获取当前组路径。

使用示例：

QSettings settings("MyCompany", "MyApp");// 写入数据
settings.beginGroup("window");
settings.setValue("width", 800);
settings.setValue("height", 600);
settings.endGroup();// 读取数据
settings.beginGroup("window");
int w = settings.value("width", 1024).toInt();  // 默认值为 1024
int h = settings.value("height", 768).toInt();  // 默认值为 768
settings.endGroup();

等价于存储如下内容：

[window]
width=800
height=600

2.4 int QSettings::beginReadArray(const QString &prefix)
功能介绍：
这个函数用于开始读取一个“数组组”，也就是一组以相同前缀命名、带有索引的配置项。调用后，你可以通过 setArrayIndex(int i) 设置当前要读取的索引。返回值是数组中元素的数量（即这个前缀下有多少个条目）。必须在读取完毕后调用 endArray()。

示例代码：写入 + 读取结构体数组

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>
#include <QVector>
#include <QString>struct Person {QString name;int age;
};// 写入结构体数组到配置文件
void writePeople(const QVector<Person> &people) {QSettings settings("config.ini", QSettings::IniFormat);settings.beginWriteArray("people");for (int i = 0; i < people.size(); ++i) {settings.setArrayIndex(i);settings.setValue("name", people[i].name);settings.setValue("age", people[i].age);}settings.endArray();
}// 从配置文件读取结构体数组
QVector<Person> readPeople() {QSettings settings("config.ini", QSettings::IniFormat);QVector<Person> people;int size = settings.beginReadArray("people");qDebug() << "Array size:" << size;for (int i = 0; i < size; ++i) {settings.setArrayIndex(i);Person p;p.name = settings.value("name").toString();p.age = settings.value("age").toInt();people.append(p);}settings.endArray();return people;
}int main(int argc, char *argv[])
{QCoreApplication a(argc, argv);// 要写入的结构体数组QVector<Person> peopleToWrite = {{"Alice", 30},{"Bob", 25},{"Charlie", 40}};// 写入writePeople(peopleToWrite);// 读取QVector<Person> loadedPeople = readPeople();// 输出读取结果for (const auto& p : loadedPeople) {qDebug() << "Name:" << p.name << ", Age:" << p.age;}return 0;
}

写入后的 config.ini 文件会长这样：

[people]
1\name=Alice
1\age=30
2\name=Bob
2\age=25
3\name=Charlie
3\age=40
size=3

输出结果：

2.5 void QSettings::beginWriteArray(const QString &prefix, int size = -1)
功能说明:
这个函数用于开始写入一个数组结构到配置文件中。

• prefix：表示数组的“组名”，比如 “people”。
• size：如果你传了 size（如 size = 3），Qt 会自动在 [people] 组中写入 size=3。如果你传的是默认值 -1，你需要手动写入 size。

必须搭配 setArrayIndex(int) 来写每个数组元素，写完之后调用 endArray()。

使用示例（写入）：

QSettings settings("config.ini", QSettings::IniFormat);settings.beginWriteArray("people", 2); // 告诉 Qt 我要写 2 个元素settings.setArrayIndex(0);
settings.setValue("name", "Alice");
settings.setValue("age", 30);settings.setArrayIndex(1);
settings.setValue("name", "Bob");
settings.setValue("age", 25);settings.endArray();

2.6 QStringList QSettings::childGroups() const
功能说明：
childGroups() 用于获取当前组（group）下所有的子组名称列表。可以配合 beginGroup() / endGroup() 使用，用来递归遍历配置结构或查看分组结构。

示例：配置文件内容如下

[window]
width=800
height=600[network]
timeout=30[network/proxy]
host=127.0.0.1
port=8080

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);// 获取顶层组名
QStringList groups = settings.childGroups();
qDebug() << "Top-level groups:" << groups;settings.beginGroup("network");
QStringList subGroups = settings.childGroups();
qDebug() << "Subgroups of [network]:" << subGroups;
settings.endGroup();

输出结果：

假设配置文件内容如下：

[window]
width=800
height=600[network]
timeout=30[network/proxy]
host=127.0.0.1
port=8080[user]
name=Tom
email=tom@example.com

递归遍历函数代码：

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>void traverseSettings(QSettings &settings, const QString &path = QString()) {settings.beginGroup(path);// 输出当前组下的所有键QStringList keys = settings.childKeys();for (const QString &key : keys) {qDebug() << settings.group() + "/" + key << "=" << settings.value(key).toString();}// 递归遍历子组QStringList groups = settings.childGroups();for (const QString &group : groups) {traverseSettings(settings, group);  // 递归进入子组}settings.endGroup();
}int main(int argc, char *argv[])
{QCoreApplication a(argc, argv);QSettings settings("config.ini", QSettings::IniFormat);traverseSettings(settings);return 0;
}

输出结果：

2.7 QStringList QSettings::childKeys() const
功能说明：
childKeys() 用于获取当前组下的所有“键名”列表（不包括子组）。

• 它不会列出子组名（那是 childGroups() 的工作）
• 需要在 beginGroup() 之后使用，才能列出该组下的键
• 如果没进入任何组，它会列出顶层键（通常很少）

配置示例（config.ini）

[window]
width=800
height=600[network]
timeout=30[network/proxy]
host=127.0.0.1
port=8080

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);settings.beginGroup("window");
QStringList keys = settings.childKeys();  // 获取 window 组下所有键
for (const QString &key : keys) {qDebug() << "window/" + key << "=" << settings.value(key).toString();
}
settings.endGroup();

输出结果：

遍历所有组和键的示例：

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>// 递归遍历配置
void printSettings(QSettings &settings, const QString &path = QString()) {settings.beginGroup(path);// 打印当前组的键for (const QString &key : settings.childKeys()) {QString fullPath = settings.group();  // 当前组路径QString fullKey = fullPath.isEmpty() ? key : fullPath + "/" + key;qDebug() << fullKey << "=" << settings.value(key).toString();}// 递归子组for (const QString &group : settings.childGroups()) {printSettings(settings, group);}settings.endGroup();
}int main(int argc, char *argv[])
{QCoreApplication a(argc, argv);QSettings settings("config.ini", QSettings::IniFormat);printSettings(settings);return 0;
}

输出结果：

2.8 void QSettings::clear()
功能说明：
clear() 会清空当前 QSettings 对象所操作的所有配置项（不管是 INI 文件、注册表还是系统配置）。

• 它会删除整个配置文件或配置树的内容
• 清除的是“所有键值对和组”
• 调用后不需要 sync() 也会立即生效

注意：不可恢复！清空的是所有内容！

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);// 清空配置
settings.clear();qDebug() << "配置文件已清空";

执行 settings.clear()后; config.ini 文件仍存在，但内容为空（或可能被删除，取决于平台）。

2.9 bool QSettings::contains(const QString &key) const
功能说明：
contains() 用来判断配置文件中是否存在某个键。

• 如果键存在，返回 true
• 如果键不存在，返回 false
• 支持带路径的键名，比如 “window/width”

示例配置（config.ini）：

[window]
width=800
height=600

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);// 检查 window/width 是否存在
if (settings.contains("window/width")) {int width = settings.value("window/width").toInt();qDebug() << "Window width:" << width;
} else {qDebug() << "window/width 不存在，使用默认值 1024";
}// 检查 window/title 是否存在
if (!settings.contains("window/title")) {qDebug() << "window/title 不存在，写入默认值";settings.setValue("window/title", "MyApp");
}

输出结果：

注意：

• contains() 检查的是键，不是组（比如 “window” 本身不是一个键）
• 如果要判断组是否存在，通常要看它下面有没有 childKeys() 或 childGroups()
• 可以搭配 setDefaultValue() 这种逻辑使用

2.10.1 bool QSettings::fallbacksEnabled() const
功能说明:
这个函数用于查询 QSettings 是否启用了“后备键查找机制（fallbacks）”。

什么是 fallback？
在使用 beginGroup() 进入某个组后，读取键时，如果该键在当前组中找不到，默认会向上一级查找（回退），直到最顶层。
举个例子，如果启用了 fallback：

settings.beginGroup("window");
settings.value("width"); // 如果找不到 window/width，会去查顶层的 width

fallbacksEnabled() 的作用：这个函数只是 判断 fallback 是否开启（默认是开启的）。也可以通过 setFallbacksEnabled(false) 关闭这个机制。

示例配置内容（config.ini）

width=1024[window]
height=768

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);// 开启 fallback（默认就是开启）
settings.setFallbacksEnabled(true);settings.beginGroup("window");// height 找得到，window/height 存在
qDebug() << "height:" << settings.value("height").toInt();  // 输出 768// width 在 window 组内没有，但顶层有，会 fallback 到上层取
qDebug() << "width:" << settings.value("width").toInt();    // 输出 1024settings.endGroup();

输出结果：

2.10.2 QString QSettings::fileName() const
功能说明：
fileName() 返回 当前 QSettings 对象所关联的文件的完整路径。

• 只对基于文件的 QSettings 有意义，比如用 QSettings::IniFormat 或 QSettings::NativeFormat（在 Windows 上是注册表，返回空字符串）
• 如果是读写 .ini 文件，这个函数能告诉你确切操作的是哪个文件

注意：如果是注册表或 macOS 的 plist 文件，通常返回空字符串（因为不是普通文件路径）。

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);
qDebug() << "配置文件路径:" << settings.fileName();

输出结果：

2.10.3 QSettings::Format QSettings::format() const
功能说明：
format() 用来查询当前 QSettings 使用的存储格式。

Qt 支持几种配置存储格式，比如：

format() 就是返回当前 settings 是属于哪种类型。

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);if (settings.format() == QSettings::IniFormat) {qDebug() << "当前使用的是 INI 文件格式";
} else if (settings.format() == QSettings::NativeFormat) {qDebug() << "当前使用的是系统原生配置格式";
} else {qDebug() << "当前使用的是其他格式";
}

输出结果：

2.10.4 QString QSettings::group() const
功能说明：
group() 用来返回当前正在操作的组（Group）路径。

• 如果没有调用 beginGroup()，那么返回空字符串 “”
• 如果进入了某个组，比如 “window”，返回 “window”
• 如果进入了嵌套组，比如 “network/proxy”，返回 “network/proxy”

示例配置（config.ini）

[window]
width=800
height=600[network/proxy]
ip=192.168.0.1
port=8080

示例代码

QSettings settings("config.ini", QSettings::IniFormat);// 最开始，group是空的
qDebug() << "当前组:" << settings.group();  // 输出 ""settings.beginGroup("window");
qDebug() << "当前组:" << settings.group();  // 输出 "window"settings.endGroup();settings.beginGroup("network/proxy");
qDebug() << "当前组:" << settings.group();  // 输出 "network/proxy"settings.endGroup();

输出结果：

*2.10.5 QTextCodec QSettings::iniCodec() const
功能说明:
iniCodec() 用来返回当前 QSettings 对象使用的文本编码器，只对 INI 格式的配置文件有效。

• 主要影响读取和保存 .ini 文件时的文字编码格式（比如 UTF-8、GBK、Latin1 等）
• 如果没有显式设置编码器，Qt 默认用 UTF-8（从 Qt5 开始是 UTF-8，之前的版本是本地编码）

示例代码

QSettings settings("config.ini", QSettings::IniFormat);// 设置编码为 GBK
settings.setIniCodec("GBK");// 读取内容
QString title = settings.value("app/title").toString();
qDebug() << "读取到的标题是:" << title;// 查询当前编码
QTextCodec *codec = settings.iniCodec();
if (codec) {qDebug() << "当前 iniCodec 是:" << codec->name();
}

2.10.6 bool QSettings::isAtomicSyncRequired() const
功能说明:
这个函数用于查询当前 QSettings 是否需要“原子性同步”到磁盘。

• 原子性同步（atomic sync） 是指在 sync() 时，先写到临时文件，然后一次性替换原文件。
• 这样做的好处是防止意外中断（比如程序崩溃、断电）时，配置文件变成半写状态或损坏。
• 如果返回 true，说明需要用原子操作保护写入过程。
• 如果返回 false，就直接写到原文件，效率高一些，但有小风险。

默认情况下，QSettings 在 IniFormat 时通常需要原子同步。

示例代码:

QSettings settings("config.ini", QSettings::IniFormat);bool needAtomic = settings.isAtomicSyncRequired();if (needAtomic) {qDebug() << "需要原子性同步，写入时会先生成临时文件。";
} else {qDebug() << "不需要原子性同步，直接写入原文件。";
}

输出结果：

为什么要有 isAtomicSyncRequired()？

• 有些平台（比如写到磁盘的 INI 文件）容易因为写一半崩掉，导致文件损坏。
• 有些平台（比如 Windows 注册表）本身就是事务性的，就不需要额外处理了。
• 这个函数可以让你根据情况优化程序性能：如果不需要原子性，可以跳过临时文件的创建，加快写入速度（不过一般不推荐手动跳过，Qt自己管理更安全）。

注意：
QSettings::sync() 是实际触发同步的方法，如果需要，Qt 会自动决定是否用临时文件，无需你手动干预。

settings.setValue("key", "value");
settings.sync();  // 自动根据 isAtomicSyncRequired 决定怎么同步

2.10.7 bool QSettings::isWritable() const
功能说明：
isWritable() 用来判断当前 QSettings 是否可以写入数据。

• 如果返回 true，说明可以正常写入配置。
• 如果返回 false，说明无法写入，可能因为：配置文件是只读权限，当前用户没有写权限，QSettings初始化时只读（某些特殊情况，比如被锁定）

**注意：**这个函数只反映 “能否尝试写入”，并不能100%保证写成功（比如磁盘写入失败是运行时错误）。

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);if (settings.isWritable()) {settings.setValue("app/title", "智能安检系统");qDebug() << "配置文件可写，保存成功！";
} else {qDebug() << "配置文件只读，无法保存更改。";
}

2.10.8 QString QSettings::organizationName() const
功能说明：
organizationName() 用来返回当前 QSettings 实例设置的“组织名称”。

• 组织名一般是在 QSettings 构造时传进去的，比如 QSettings(“MyCompany”, “MyApp”) 中的 “MyCompany”。
• 这个组织名通常影响配置文件或注册表的存储路径。

简单理解：这是用来标识"这是谁家的软件"的。

示例代码：

QSettings settings("MyCompany", "MyApp");qDebug() << "组织名是:" << settings.organizationName();  // 输出 "MyCompany"
qDebug() << "应用名是:" << settings.applicationName();  // 输出 "MyApp"

输出结果：

2.10.9 void QSettings::remove(const QString &key)
功能说明：
remove() 用来删除指定键（key）或组（group）下的所有键值。

• 如果 key 是普通键名，就删除这个单独的键。
• 如果 key 是组名，就删除整个组及其所有子键。
• 删除操作会立刻生效，并可以通过 sync() 将变更写回磁盘。

简单理解： 就是按键名或者组名删除配置内容。

示例配置（config.ini）

[window]
width=800
height=600[network/proxy]
ip=192.168.0.1
port=8080

示例代码：删除单个键

QSettings settings("config.ini", QSettings::IniFormat);// 删除 window 组下的 width
settings.beginGroup("window");
settings.remove("width");
settings.endGroup();// 保存到磁盘
settings.sync();

删除后，window组只剩下 height=600。

示例代码：删除整个组

QSettings settings("config.ini", QSettings::IniFormat);// 直接删除整个 network/proxy 组
settings.remove("network/proxy");// 保存到磁盘
settings.sync();

删除后，[network/proxy] 和里面的 ip, port 都不见了。

注意事项：

也可以用绝对路径删除键，比如：

settings.remove("window/height");

• 删除组时，不需要 beginGroup()，直接 remove(“组名”)。
• 如果想安全删除，可以先 contains() 检查键是否存在。

2.10.10 QSettings::Scope QSettings::scope() const
功能说明：
scope() 返回当前 QSettings 对象使用的作用域（Scope）。Scope 是用来区分配置文件是用户专属（UserScope），还是**系统级别（SystemScope）**的。

Qt定义了两个作用域：

简单理解：

• UserScope 是每个用户一份（常用）
• SystemScope 是全系统一份（管理员权限）

示例代码：

QSettings settings(QSettings::NativeFormat, QSettings::UserScope, "MyCompany", "MyApp");if (settings.scope() == QSettings::UserScope) {qDebug() << "当前是用户作用域(UserScope)";
} else {qDebug() << "当前是系统作用域(SystemScope)";
}

输出结果：

2.10.11 void QSettings::setArrayIndex(int i)
功能说明：
setArrayIndex(int i) 是在处理数组型数据时使用的，用来指定当前要读/写数组的第 i 个元素。它通常在你使用 beginReadArray() 或 beginWriteArray() 之后配合使用。

• beginReadArray() 或 beginWriteArray() 打开了一个数组
• setArrayIndex(i) 表示"我要操作第 i 个元素"
• 后续的 setValue() 或 value() 都是针对这个元素的

示例代码：写数组

struct Student {QString name;int age;
};QList<Student> students = {{"Alice", 20},{"Bob", 22},{"Charlie", 21}
};QSettings settings("config.ini", QSettings::IniFormat);settings.beginWriteArray("students", students.size());
for (int i = 0; i < students.size(); ++i) {settings.setArrayIndex(i);  // 指定当前是第 i 个学生settings.setValue("name", students[i].name);settings.setValue("age", students[i].age);
}
settings.endArray();
settings.sync();

示例代码：读数组

QList<Student> loadedStudents;QSettings settings("config.ini", QSettings::IniFormat);int size = settings.beginReadArray("students");
for (int i = 0; i < size; ++i) {settings.setArrayIndex(i);  // 指定读取第 i 个学生Student s;s.name = settings.value("name").toString();s.age = settings.value("age").toInt();loadedStudents.append(s);
}
settings.endArray();// 打印
for (const auto &s : loadedStudents) {qDebug() << s.name << s.age;
}

注意：

• 一定要在 beginWriteArray 或 beginReadArray 后使用 setArrayIndex。
• 如果忘了 setArrayIndex，默认是操作第0个元素。
• setArrayIndex 不是“跳到位置”，而是“告诉 QSettings 当前上下文是哪一项”。

2.10.12 void QSettings::setAtomicSyncRequired(bool enable)
功能说明：
setAtomicSyncRequired(bool enable) 用来控制 QSettings 在保存(sync)配置数据时是否必须使用"原子操作"。

• 原子操作（atomic operation）：指的是写文件时，要么一次成功完整写入，要么不改变原有文件，防止在断电、崩溃时造成配置文件半写坏掉。
• 如果 enable == true，表示强制要求原子写入。
• 如果 enable == false，表示允许普通方式写入（有极小概率文件损坏，但速度更快）。

简单理解： 这个设置是为了保证配置保存的安全性 vs 速度。

默认行为：

• 默认是：false（普通写入）
• 在大部分情况下，QSettings自己已经做了很安全的处理，只有你特别在意极端安全性时，才需要设置为 true。

示例代码：

QSettings settings("config.ini", QSettings::IniFormat);// 强制开启原子写入
settings.setAtomicSyncRequired(true);// 正常设置一些值
settings.setValue("username", "admin");
settings.setValue("password", "123456");// 同步保存
settings.sync();

2.10.13 void QSettings::setFallbacksEnabled(bool b)
功能说明：
setFallbacksEnabled(bool b) 用来启用或禁用“回退查找机制（fallbacks）”。

• 如果 b == true，开启回退（默认就是开的）
• 如果 b == false，禁用回退，只在当前 Scope 和 Group 查找，找不到就返回默认值

简单理解：正常找不到键时，QSettings会自动往上一级，或者到更宽泛的作用域去找，直到找到或者彻底没有。但如果你关掉 fallbacks，就只在当前层级找，找不到就认输。

比如有这样一份配置：

[default]
theme=light[user]
name=alice

如果的代码是这样：

QSettings settings("config.ini", QSettings::IniFormat);settings.beginGroup("user");
QString theme = settings.value("theme", "not found").toString();
settings.endGroup();qDebug() << theme;

因为 user 组下没有 theme，但是有 fallback 到 default/theme，所以你能拿到 “light”。

关闭 fallback 后示例：

QSettings settings("config.ini", QSettings::IniFormat);settings.setFallbacksEnabled(false);  // 关掉回退！settings.beginGroup("user");
QString theme = settings.value("theme", "not found").toString();
settings.endGroup();qDebug() << theme;

这次输出就是 “not found”，不会自动去 [default] 找了！

*2.10.14 void QSettings::setIniCodec(QTextCodec codec)
功能说明：
setIniCodec(QTextCodec *codec) 用来设置 QSettings 读写 .ini 文件时使用的字符编码（Encoding）。

• .ini 文件本质是文本文件，不同的编码格式（如 UTF-8、GBK、Latin1）会影响文件的读写正确性。
• 默认情况下，Qt5 以前 .ini 文件通常使用系统编码（比如 Windows 的 GBK）。
• Qt5+之后默认倾向于 UTF-8，但是老项目可能会遇到其他编码。

使用 setIniCodec()，可以指定正确的编码，避免乱码问题。

示例代码：
强制用 UTF-8（推荐现代项目）

QSettings settings("config.ini", QSettings::IniFormat);// 强制使用 UTF-8 编码
settings.setIniCodec("UTF-8");settings.setValue("username", "小明");
settings.setValue("city", "北京");
settings.sync();

兼容旧版 GBK 文件

QSettings settings("config.ini", QSettings::IniFormat);// 如果是老 Windows 系统的配置文件，需要设置 GBK
settings.setIniCodec("GBK");QString username = settings.value("username").toString();
qDebug() << username;

注意事项：

• setIniCodec() 只影响 IniFormat。
• 对于 NativeFormat（比如 Windows 注册表），无效。
• 必须在读写操作前设置（最好一开始就设置）。
• Qt6以后 QTextCodec 被废弃，改用 QStringConverter；Qt5中还是用 QTextCodec。

2.10.15 void QSettings::setValue(const QString &key, const QVariant &value)
功能说明：
setValue() 是 QSettings最常用的方法之一，用来：

• 根据键（key） 保存一条设置项（键值对）。
• 值（value） 是 QVariant 类型，支持存各种常见类型，比如 int、double、QString、QColor、QSize、QPoint、QDateTime、QStringList
  甚至自定义类型（带Q_DECLARE_METATYPE的）。

基本使用方法

QSettings settings("config.ini", QSettings::IniFormat);// 保存简单字符串
settings.setValue("username", "admin");// 保存数字
settings.setValue("age", 30);// 保存布尔值
settings.setValue("isAdmin", true);// 保存字符串列表
QStringList cities = {"Beijing", "Shanghai", "Shenzhen"};
settings.setValue("cities", cities);// 保存时间
settings.setValue("lastLogin", QDateTime::currentDateTime());

写入成功后，这些内容就存到硬盘上了（可以用 sync() 强制保存，也可以等待自动保存）。

QVariant 支持的常见类型

2.10.16 QSettings::Status status() const
功能说明：
status() 用来检查 QSettings 当前的工作状态，看看读写配置过程中有没有遇到错误，比如：

• 文件打不开
• 文件损坏
• 解析失败
• 权限不足导致写入失败
• …

如果一切正常，返回 QSettings::NoError。但如果出问题了，可以通过 status() 得到具体的错误类型，便于做异常处理。

返回的状态类型（QSettings::Status 枚举）

示例代码

QSettings settings("config.ini", QSettings::IniFormat);// 尝试读写配置
settings.setValue("username", "admin");
settings.sync();  // 强制保存到磁盘// 检查状态
if (settings.status() == QSettings::NoError) {qDebug() << "配置保存成功！";
} else if (settings.status() == QSettings::AccessError) {qWarning() << "访问错误，可能是权限问题！";
} else if (settings.status() == QSettings::FormatError) {qWarning() << "配置文件格式错误，无法正确解析！";
}

注意事项：

• status() 通常只会在你进行 读/写/同步(sync) 之后才有意义。
• sync() 后再检查 status() 更可靠，因为 sync() 会触发实际的磁盘写入。
• 如果在初始化阶段遇到错误，可以考虑重新生成配置文件。

2.10.17 void QSettings::sync()
功能说明：
sync() 是用来手动同步（保存）QSettings 中的所有设置到磁盘或注册表，确保所有写入的配置立即生效。通常，QSettings 会在程序退出时自动同步配置文件，或者在特定情况下（如应用被强制关闭）会进行自动保存。但是如果你需要确保设置被及时保存，比如在程序运行中间保存配置（避免丢失），就可以使用 sync()。

使用场景：

• 确保立即保存配置：例如在程序的某个关键时刻，需要立即将配置保存到磁盘，而不是等到应用退出时才保存。
• 写入大量设置时，控制保存时机：避免多次写入配置，减少磁盘IO压力，可以统一在某个时刻调用 sync()。
• 调试或确保数据一致性：如果你在操作系统级别的注册表或文件系统上进行配置更改，调用 sync() 可以确保这些更改被立即反映出来。

示例代码：
保存用户设置，并确保配置立即同步到磁盘

QSettings settings("config.ini", QSettings::IniFormat);// 保存用户设置
settings.setValue("username", "admin");
settings.setValue("theme", "dark");// 强制保存到磁盘
settings.sync();// 现在所有的设置都已经被写入到配置文件
qDebug() << "设置已保存到 config.ini";

多次写入后调用 sync()

QSettings settings("config.ini", QSettings::IniFormat);// 批量保存设置
settings.setValue("username", "alice");
settings.setValue("language", "English");
settings.setValue("window/size", QSize(800, 600));// 在必要时统一保存（避免频繁调用 sync()）
settings.sync();

注意事项：

• 自动保存：在很多情况下，QSettings 会在应用退出时自动将数据保存到磁盘或注册表中。
• 调用时机：sync() 通常用在你希望手动控制配置保存时机的场合，例如在程序运行过程中即时保存设置。
• 影响性能：如果你频繁调用 sync()，可能会影响性能，尤其是频繁读写磁盘文件时。

2.10.18 QVariant QSettings::value(const QString &key, const QVariant &defaultValue = QVariant()) const
功能说明：
value() 用来从配置文件（或注册表）中读取指定键（key）对应的值，并返回一个 QVariant 类型。

• key：要查询的设置项的键。
• defaultValue：如果指定的 key 不存在或者读取失败时，返回的默认值。默认是一个空的 QVariant()，表示没有提供默认值。

这个函数非常灵活，能够根据指定的键读取不同类型的数据，而不需要事先知道存储的数据类型。你可以将返回的 QVariant 转换成所需的具体类型（如 QString、int、bool 等）。

示例代码：
读取字符串类型的配置

QSettings settings("config.ini", QSettings::IniFormat);// 读取用户名，如果不存在则返回 "guest" 作为默认值
QString username = settings.value("username", "guest").toString();
qDebug() << "Username: " << username;

读取整数类型的配置

QSettings settings("config.ini", QSettings::IniFormat);// 读取窗口宽度，如果不存在则返回 800 作为默认值
int windowWidth = settings.value("window/width", 800).toInt();
qDebug() << "Window width: " << windowWidth;

读取布尔类型的配置

QSettings settings("config.ini", QSettings::IniFormat);// 读取是否启用自动更新，如果不存在则返回 true 作为默认值
bool autoUpdate = settings.value("autoUpdate", true).toBool();
qDebug() << "Auto update: " << autoUpdate;

读取更复杂的类型（如字符串列表）

QSettings settings("config.ini", QSettings::IniFormat);// 读取语言列表，如果不存在则返回空列表作为默认值
QStringList languages = settings.value("languages", QStringList()).toStringList();
qDebug() << "Languages: " << languages;

注意事项：

• 返回值是 QVariant，你需要根据具体类型进行转换（如 toString()、toInt() 等）。
• 提供默认值：defaultValue 只有在 key 不存在时才会生效。如果 key 存在但无法读取（格式错误或值不可转换），则返回默认值。
• 常用于检查键是否存在：如果读取的键不存在，可以通过 defaultValue 提供一个回退值，避免程序崩溃。

三、QSettings的常用的静态函数

3.1 QSettings::Format QSettings::defaultFormat()
功能说明：

• defaultFormat() 返回的是 默认的配置文件格式，即 QSettings 在没有显式指定格式时所使用的格式。
• 这个返回值的类型是 QSettings::Format，它是一个枚举类型，用来表示不同的配置格式。

QSettings::Format 枚举值：

• QSettings::IniFormat：INI 文件格式（键值对格式，通常用于 Windows 系统）。
• QSettings::RegistryFormat：注册表格式（通常用于 Windows 上的注册表）。
• QSettings::NativeFormat：原生格式（在不同平台上根据系统决定使用的格式）。
• QSettings::XmlFormat：XML 格式（较为通用的配置格式）。

示例代码

QSettings::Format format = QSettings::defaultFormat();switch (format) {case QSettings::IniFormat:qDebug() << "使用 INI 格式";break;case QSettings::RegistryFormat:qDebug() << "使用注册表格式";break;default:qDebug() << "未知格式";break;
}

3.2 static void QSettings::setDefaultFormat(QSettings::Format format)
参数说明：
format：指定要设置的默认格式。可以是以下的 QSettings::Format 枚举值之一：

• QSettings::IniFormat：INI 格式，通常用于 Windows 系统。
• QSettings::NativeFormat：原生格式，依赖于系统平台，自动选择最合适的格式。

功能说明：
setDefaultFormat() 用于设置全局的默认配置格式。调用这个函数后，所有未明确指定格式的 QSettings 对象都会使用新的默认格式。例如，在没有指定格式的情况下，QSettings 将根据 setDefaultFormat() 设置的格式来读取和写入配置文件。

示例代码：
设置默认格式为 INI 格式

// 设置全局默认格式为 INI 格式
QSettings::setDefaultFormat(QSettings::IniFormat);// 使用 QSettings 创建配置对象时会自动使用 INI 格式
QSettings settings("config.ini", QSettings::NativeFormat);  // 这里使用的是 INI 格式
settings.setValue("username", "admin");
settings.sync();

3.3 static void QSettings::setPath(QSettings::Format format, QSettings::Scope scope, const QString &path)
参数说明：
format：指定配置文件的格式。可以是以下的 QSettings::Format 枚举值之一：

• QSettings::IniFormat：INI 格式。
• QSettings::NativeFormat：原生格式（Windows 上使用注册表，Linux/macOS 使用类似 INI 格式的文件）。

scope：指定配置文件的作用域。可以是以下的 QSettings::Scope 枚举值之一：

• QSettings::UserScope：用户范围，指示配置文件是为当前用户设置的。
• QSettings::SystemScope：系统范围，指示配置文件是为整个系统设置的（通常用于全局设置，如系统配置）。

path：配置文件的路径。它可以是一个目录路径，也可以是一个文件路径，具体取决于你选择的格式。

功能说明：
setPath() 用于设置 QSettings 使用的配置文件的路径、格式和作用域。这使得你可以灵活地控制 QSettings 保存和读取配置文件的位置和格式。

• 作用域 (scope)：决定配置文件是针对单一用户的配置文件，还是针对全系统的配置文件。你可以选择用户范围（UserScope）或系统范围（SystemScope）。对于大多数应用程序，通常选择
  UserScope 来保存用户特定的配置文件。
• 格式 (format)：你可以选择 INI、XML 或原生格式来保存配置文件。选择的格式会影响配置文件的存储方式。
• 路径 (path)：指定配置文件的路径，可以是目录路径或者完整文件路径。

示例代码：
指定用户配置文件路径和格式

// 设置用户范围的配置文件路径，使用 INI 格式
QSettings::setPath(QSettings::IniFormat, QSettings::UserScope, "/home/user/myapp/config.ini");// 创建 QSettings 对象时会使用指定的路径和格式
QSettings settings("/home/user/myapp/config.ini", QSettings::IniFormat);
settings.setValue("username", "admin");
settings.sync();

为跨平台应用设置路径

#ifdef Q_OS_WINDOWS// Windows 配置文件路径和格式QSettings::setPath(QSettings::IniFormat, QSettings::UserScope, "C:/ProgramData/MyApp/config.ini");
#elif defined(Q_OS_LINUX)// Linux 配置文件路径和格式QSettings::setPath(QSettings::XmlFormat, QSettings::UserScope, "/home/user/.config/myapp/config.xml");
#endif// 创建 QSettings 对象时会根据平台和路径设置正确的路径和格式
QSettings settings;
settings.setValue("username", "admin");
settings.sync();

注意事项：

• setPath() 是静态函数，影响全局设置。在调用它之后，QSettings 会使用你指定的路径、格式和作用域设置配置文件。
• 确保你指定的路径具有足够的读写权限，特别是在系统范围（SystemScope）时。
• setPath() 会影响应用程序中的所有 QSettings 实例，除非你在创建 QSettings 对象时显式指定了其他路径和格式。