Qt實(shí)現(xiàn)QSettings的項(xiàng)目實(shí)踐
更新時(shí)間：2026年07月13日 10:05:43 作者：華麗的周遭
QSettings作為Qt生態(tài)的配置管理利器,能輕松處理應(yīng)用的鍵值對(duì)持久化,本文就來(lái)詳細(xì)的介紹一下QSettings的使用,感興趣的可以了解一下
可以這么說(shuō)：QSettings是Qt生態(tài)中，跨平臺(tái)持久化存儲(chǔ)應(yīng)用配置的“瑞士軍刀”。
一、QSettings 是什么？
QSettings 是 Qt 提供的鍵值對(duì)（Key-Value）持久化存儲(chǔ)類，用于保存應(yīng)用程序的配置信息（如窗口位置、主題、網(wǎng)絡(luò)參數(shù)、用戶偏好）。其核心優(yōu)勢(shì)是：
- 跨平臺(tái)：自動(dòng)適配 Windows（注冊(cè)表）、macOS（Plist 文件）、Linux（INI/XDG 文件）；
- 分層組織：用
/分隔的“組（Group）”管理配置（如Window/Size、Network/IP）； - 多格式支持：原生平臺(tái)格式（注冊(cè)表/Plist）+ 通用 INI 格式；
- 類型安全：直接支持 Qt 基礎(chǔ)類型（
int/bool/QString）和擴(kuò)展類型（QSize/QColor/QFont），甚至自定義類型。
二、QSettings 的底層邏輯：組織與存儲(chǔ)
我們知道，軟件的本質(zhì)是：邏輯+數(shù)據(jù)。而數(shù)據(jù)的本質(zhì)是：組織和存儲(chǔ)。
1. 配置的“路徑”與“組”
QSettings 用層級(jí)路徑組織配置，類似文件系統(tǒng)的目錄結(jié)構(gòu)。例如：
- 鍵
Window/Size表示“Window 組下的 Size 鍵”； - 通過(guò)
beginGroup()/endGroup()嵌套管理組（棧式結(jié)構(gòu)）。
2. 跨平臺(tái)的存儲(chǔ)位置
QSettings 會(huì)根據(jù)平臺(tái)和構(gòu)造參數(shù)自動(dòng)選擇存儲(chǔ)位置：
平臺(tái) | 默認(rèn)存儲(chǔ)位置（UserScope） | 系統(tǒng)級(jí)存儲(chǔ)（SystemScope） |
|---|---|---|
Windows? | 注冊(cè)表：HKEY_CURRENT_USER\Software\<Org>\<App> | 注冊(cè)表：HKEY_LOCAL_MACHINE\Software\<Org>\<App> |
macOS? | Plist 文件：~/Library/Preferences/org.<org>.<app>.plist | Plist 文件：/Library/Preferences/org.<org>.<app>.plist |
Linux? | XDG 配置目錄：~/.config/<Org>/<App>.conf（優(yōu)先）或 ~/.config/<Org>/<App>/<App>.conf | 系統(tǒng)配置目錄：/etc/xdg/<Org>/<App>.conf |
注：若顯式指定QSettings::IniFormat，則強(qiáng)制用 INI 文件存儲(chǔ)（如config.ini），方便調(diào)試。
三、QSettings 的核心操作
1. 構(gòu)造 QSettings 對(duì)象
QSettings 有兩種常見(jiàn)構(gòu)造方式：
（1）用“組織名+應(yīng)用名”（跨平臺(tái)原生存儲(chǔ)）
#include <QSettings>
// 組織名（如公司名）、應(yīng)用名（如產(chǎn)品名）
QSettings settings("Xilinx", "PortableMonitor");- 自動(dòng)適配平臺(tái)存儲(chǔ)位置（如 Windows 注冊(cè)表、macOS Plist）；
- 默認(rèn)
UserScope（僅當(dāng)前用戶可見(jiàn)），可通過(guò)QSettings::setScope()修改。
（2）用“文件路徑+格式”（顯式控制存儲(chǔ)）
// 用 INI 格式存儲(chǔ)到當(dāng)前目錄的 config.ini
QSettings settings("config.ini", QSettings::IniFormat);
// 用 NativeFormat（平臺(tái)原生）存儲(chǔ)到 /etc/myapp.conf（需 root 權(quán)限）
QSettings settings(QSettings::NativeFormat, QSettings::SystemScope, "MyOrg", "MyApp");2. 讀寫配置值
QSettings 的核心是setValue()（寫）和value()（讀），均基于QVariant實(shí)現(xiàn)類型兼容。
（1）寫配置：setValue(key, value)
key：帶組的路徑（如"Window/Size"）；value：支持QVariant兼容的類型（int/bool/QString/QSize等）。
QSettings settings("Xilinx", "PortableMonitor");
// 寫基礎(chǔ)類型
settings.setValue("Window/Width", 1920);
settings.setValue("Window/Height", 1080);
settings.setValue("Theme/DarkMode", true);
// 寫 Qt 擴(kuò)展類型（自動(dòng)序列化）
settings.setValue("Window/Position", QPoint(100, 200));
settings.setValue("Display/ColorDepth", QColor(Qt::red));（2）讀配置：value(key, defaultValue)
key：同寫操作的路徑；defaultValue：鍵不存在時(shí)的返回值（必選，避免空值）；- 返回值需用
QVariant的轉(zhuǎn)換函數(shù)（如toInt()/toString()）轉(zhuǎn)成目標(biāo)類型。
QSettings settings("Xilinx", "PortableMonitor");
// 讀基礎(chǔ)類型（帶默認(rèn)值）
int width = settings.value("Window/Width", 1280).toInt();
int height = settings.value("Window/Height", 720).toInt();
bool darkMode = settings.value("Theme/DarkMode", false).toBool();
// 讀 Qt 擴(kuò)展類型
QPoint pos = settings.value("Window/Position", QPoint(0, 0)).toPoint();
QColor color = settings.value("Display/ColorDepth", QColor(Qt::black)).value<QColor>();（3）分組管理：beginGroup()/endGroup()
用組嵌套簡(jiǎn)化鍵的書寫（避免重復(fù)前綴）：
QSettings settings("Xilinx", "PortableMonitor");
settings.beginGroup("Window");
settings.setValue("Width", 1920); // 等價(jià)于 "Window/Width"
settings.setValue("Height", 1080); // 等價(jià)于 "Window/Height"
settings.endGroup(); // 退出組，回到根
settings.beginGroup("Window/SubWindow"); // 嵌套組
settings.setValue("Opacity", 0.8); // 等價(jià)于 "Window/SubWindow/Opacity"
settings.endGroup();3. 同步與持久化：sync()
QSettings 內(nèi)部有緩存（減少磁盤IO），setValue()后數(shù)據(jù)先存緩存，調(diào)用sync()才會(huì)強(qiáng)制寫入磁盤。
建議在關(guān)鍵配置變更后（如用戶點(diǎn)擊“保存”）或程序退出前調(diào)用：
settings.setValue("Theme/DarkMode", true);
settings.sync(); // 立即寫入磁盤（可選，析構(gòu)時(shí)也會(huì)自動(dòng) sync）4. 刪除配置：remove()/clear()
remove(key)：刪除指定鍵（含組路徑）；clear()：刪除所有配置（清空文件/注冊(cè)表項(xiàng)）。
settings.remove("Window/Width"); // 刪除 Window 組的 Width 鍵
settings.clear(); // 清空所有配置（謹(jǐn)慎使用?。?/pre>四、支持的數(shù)據(jù)類型
QSettings 原生支持以下類型（無(wú)需額外處理）：
類型 | 示例 | 轉(zhuǎn)換函數(shù) |
|---|---|---|
基礎(chǔ)類型 | int/bool/double/QString | toInt()/toBool()/toString() |
Qt 幾何類型 | QPoint/QSize/QRect | toPoint()/toSize()/toRect() |
Qt 樣式類型 | QColor/QFont/QPalette | value<QColor>()/value<QFont>() |
其他 | QByteArray/QStringList | toByteArray()/toStringList() |
擴(kuò)展：自定義類型的存儲(chǔ)
若需存儲(chǔ)自定義結(jié)構(gòu)體，需注冊(cè)元類型并實(shí)現(xiàn)流操作符（<</>>）：
步驟1：定義結(jié)構(gòu)體并注冊(cè)元類型
#include <QMetaType>
#include <QDataStream>
// 自定義設(shè)備校準(zhǔn)參數(shù)
struct CalibrationParams {
double gainR; // R通道增益
double offsetB; // B通道偏移
};
// 注冊(cè)元類型（需唯一名稱）
Q_DECLARE_METATYPE(CalibrationParams)
qRegisterMetaType<CalibrationParams>("CalibrationParams");步驟2：實(shí)現(xiàn)流操作符（序列化/反序列化）
// 序列化（寫入QDataStream）
QDataStream &operator<<(QDataStream &out, const CalibrationParams ¶ms) {
out << params.gainR << params.offsetB;
return out;
}
// 反序列化（從QDataStream讀?。?
QDataStream &operator>>(QDataStream &in, CalibrationParams ¶ms) {
in >> params.gainR >> params.offsetB;
return in;
}
// 注冊(cè)流操作符（讓QSettings識(shí)別）
qRegisterMetaTypeStreamOperators<CalibrationParams>("CalibrationParams");步驟3：讀寫自定義類型
// 寫自定義類型
CalibrationParams params{1.2, -0.5};
settings.setValue("Device/Calibration", QVariant::fromValue(params));
// 讀自定義類型
QVariant var = settings.value("Device/Calibration");
if (var.canConvert<CalibrationParams>()) {
CalibrationParams p = var.value<CalibrationParams>();
qDebug() << "GainR:" << p.gainR << "OffsetB:" << p.offsetB;
}五、高級(jí)技巧
1. 顯式指定格式與范圍
構(gòu)造時(shí)可指定存儲(chǔ)格式（Format）和作用域（Scope）：
// 格式：IniFormat（通用INI）/ NativeFormat（平臺(tái)原生）/ InvalidFormat
// 范圍：UserScope（當(dāng)前用戶）/ SystemScope（所有用戶）
QSettings settings(
QSettings::IniFormat, // 用INI文件
QSettings::UserScope, // 當(dāng)前用戶
"Xilinx", // 組織名
"PortableMonitor" // 應(yīng)用名
);INI 格式示例（PortableMonitor.ini）：
[Window] Width=1920 Height=1080 [Theme] DarkMode=true
2. 獲取所有配置鍵/組
allKeys()：返回所有鍵的路徑（如["Window/Width", "Theme/DarkMode"]）；childGroups()：返回當(dāng)前組下的所有子組（如["Window", "Theme"]）；childKeys()：返回當(dāng)前組下的所有鍵（如["Width", "Height"]）。
QSettings settings("Xilinx", "PortableMonitor");
QStringList allKeys = settings.allKeys();
QStringList groups = settings.childGroups(); // 根組下的所有組3. 監(jiān)聽配置變化（實(shí)時(shí)更新）
QSettings本身無(wú)信號(hào)，但可通過(guò)QFileSystemWatcher監(jiān)控配置文件的變化（適用于INI格式）：
#include <QFileSystemWatcher>
QSettings settings("config.ini", QSettings::IniFormat);
QFileSystemWatcher watcher;
watcher.addPath("config.ini"); // 監(jiān)控配置文件
// 連接信號(hào)：文件變化時(shí)重新加載配置
connect(&watcher, &QFileSystemWatcher::fileChanged, [&](const QString &path) {
settings.sync(); // 重新讀取磁盤上的最新配置
loadConfig(); // 自定義函數(shù)：重新應(yīng)用配置
});4. 線程安全
QSettings 是可重入（Reentrant）但非線程安全（Thread-Safe）的——多線程同時(shí)讀寫會(huì)導(dǎo)致數(shù)據(jù)競(jìng)爭(zhēng)。需用互斥鎖（QMutex）保護(hù)：
QMutex mutex;
QSettings settings("Xilinx", "PortableMonitor");
// 寫操作加鎖
mutex.lock();
settings.setValue("Theme/DarkMode", true);
settings.sync();
mutex.unlock();
// 讀操作加鎖
mutex.lock();
bool darkMode = settings.value("Theme/DarkMode", false).toBool();
mutex.unlock();六、注意事項(xiàng)
- 鍵名大小寫：Windows 注冊(cè)表不區(qū)分大小寫，INI 文件區(qū)分——建議統(tǒng)一用小寫+下劃線（如
window_width）； - 默認(rèn)值必選：
value()的第二個(gè)參數(shù)（默認(rèn)值）不可省略，否則鍵不存在時(shí)返回?zé)o效QVariant； - 權(quán)限問(wèn)題：SystemScope（系統(tǒng)級(jí)）存儲(chǔ)需管理員權(quán)限（如 Linux 下
/etc/xdg），否則寫入失敗； - 性能優(yōu)化：頻繁讀寫時(shí)用
beginGroup()/endGroup()減少鍵的拼接開銷； - 調(diào)試技巧：用
QSettings::IniFormat顯式生成 INI 文件，直接查看配置內(nèi)容。
七、實(shí)戰(zhàn)示例：產(chǎn)品配置存儲(chǔ)
假設(shè)你的產(chǎn)品需要保存窗口狀態(tài)、視頻輸入源、色彩校正參數(shù)，代碼如下：
// 定義配置鍵（常量，避免硬編碼）
namespace ConfigKeys {
const QString WindowGroup = "Window";
const QString WindowSize = WindowGroup + "/Size";
const QString WindowPos = WindowGroup + "/Pos";
const QString VideoGroup = "Video";
const QString InputSource = VideoGroup + "/InputSource"; // HDMI/SDI/VGA
const QString ColorGroup = "Color";
const QString Brightness = ColorGroup + "/Brightness";
const QString Contrast = ColorGroup + "/Contrast";
}
// 保存配置
void saveSettings(MainWindow *win, VideoInput input, ColorParams color) {
QSettings settings("Xilinx", "PortableMonitor");
// 窗口狀態(tài)
settings.beginGroup(ConfigKeys::WindowGroup);
settings.setValue("Size", win->size());
settings.setValue("Pos", win->pos());
settings.endGroup();
// 視頻輸入源
settings.beginGroup(ConfigKeys::VideoGroup);
settings.setValue("InputSource", static_cast<int>(input)); // 枚舉轉(zhuǎn)int
settings.endGroup();
// 色彩參數(shù)
settings.beginGroup(ConfigKeys::ColorGroup);
settings.setValue("Brightness", color.brightness);
settings.setValue("Contrast", color.contrast);
settings.endGroup();
settings.sync(); // 強(qiáng)制寫入
}
// 加載配置
void loadSettings(MainWindow *win, VideoInput *input, ColorParams *color) {
QSettings settings("Xilinx", "PortableMonitor");
// 窗口狀態(tài)
settings.beginGroup(ConfigKeys::WindowGroup);
QSize size = settings.value("Size", QSize(1280, 720)).toSize();
QPoint pos = settings.value("Pos", QPoint(0, 0)).toPoint();
settings.endGroup();
win->resize(size);
win->move(pos);
// 視頻輸入源
settings.beginGroup(ConfigKeys::VideoGroup);
*input = static_cast<VideoInput>(settings.value("InputSource", 0).toInt()); // 默認(rèn)HDMI
settings.endGroup();
// 色彩參數(shù)
settings.beginGroup(ConfigKeys::ColorGroup);
color->brightness = settings.value("Brightness", 50).toInt(); // 默認(rèn)50%
color->contrast = settings.value("Contrast", 50).toInt();
settings.endGroup();
}八、總結(jié)
QSettings 是配置持久化的首選方案——它幫你屏蔽了跨平臺(tái)差異，用簡(jiǎn)單的鍵值對(duì)管理復(fù)雜配置。
到此這篇關(guān)于Qt實(shí)現(xiàn)QSettings的項(xiàng)目實(shí)踐的文章就介紹到這了,更多相關(guān)Qt QSettings內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
這篇文章主要介紹了C語(yǔ)言的遞歸思想,以一個(gè)實(shí)例的形式針對(duì)數(shù)據(jù)變化規(guī)律分析了遞歸思想的本質(zhì),需要的朋友可以參考下2014-09-09
這篇文章主要為大家詳細(xì)介紹了C語(yǔ)言字符串替換空格實(shí)例，使用數(shù)據(jù)庫(kù)，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下，希望能夠給你帶來(lái)幫助2022-02-02
這篇文章主要介紹了C語(yǔ)言中的編碼小技巧，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2023-02-02
C語(yǔ)言實(shí)現(xiàn)串的順序存儲(chǔ)表示與基本操作
這篇文章主要為大家詳細(xì)介紹了C語(yǔ)言實(shí)現(xiàn)串的順序存儲(chǔ)表示與基本操作，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2021-09-09
C++深入右值引用之移動(dòng)語(yǔ)義與完美轉(zhuǎn)發(fā)(最新推薦)
本文給大家介紹了C++深入右值引用之移動(dòng)語(yǔ)義與完美轉(zhuǎn)發(fā),文章討論了移動(dòng)構(gòu)造與移動(dòng)賦值的概念,以及它們?cè)谌萜髦械膽?yīng)用,感興趣的朋友一起看看吧2026-05-05
C語(yǔ)言實(shí)現(xiàn)單鏈表逆序與逆序輸出實(shí)例
這篇文章主要介紹了C語(yǔ)言實(shí)現(xiàn)單鏈表逆序與逆序輸出,是數(shù)據(jù)結(jié)構(gòu)與算法中比較基礎(chǔ)的重要內(nèi)容,有必要加以牢固掌握,需要的朋友可以參考下2014-08-08
這篇文章主要介紹了C++中淺拷貝與深拷貝的詳解及其作用介紹，本文給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2021-09-09
這篇文章主要介紹了Qt?QTableView詳解,主要包括常用接口，設(shè)置item屬性，右鍵彈出菜單，結(jié)合示例代碼給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2022-03-03
C語(yǔ)言算法練習(xí)之?dāng)?shù)組求素?cái)?shù)
這篇文章主要為大家介紹了C語(yǔ)言算法練習(xí)中數(shù)組求素?cái)?shù)的實(shí)現(xiàn)方法，文中的示例代碼講解詳細(xì)，對(duì)我們學(xué)習(xí)C語(yǔ)言有一定幫助，需要的可以參考一下2022-09-09
在C語(yǔ)言中自定義類型主要有結(jié)構(gòu)體類型、位段、枚舉類型、聯(lián)合體類型，自定義類型是面試常會(huì)碰到的內(nèi)容，本篇文章帶你徹底解決自定義類型2022-02-02