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