Settings QML Type

提供与平台无关的持久性应用程序设置。更多

Import Statement:	`import QtCore`
Since:	Qt 6.5
Inherits:	QtObject

所有成员（包括继承成员）的列表

属性

category : string
location : url

方法

setValue(string key, var value)
sync()
var value(string key, var defaultValue)

详细说明

设置类型提供与平台无关的持久性应用程序设置。

用户通常希望应用程序能跨会话记住其设置（窗口大小和位置、选项等）。设置 "类型使您能以最小的代价保存和恢复此类应用程序设置。

单个设置值可通过在设置元素中声明属性来指定。只有QSettings 能识别的值类型才受支持。建议的方法是使用属性别名，以便双向自动更新属性。下面的示例展示了如何使用 "设置 "来存储和还原窗口的几何图形。

import QtCore
import QtQuick

Window {
    id: window

    width: 800
    height: 600

    Settings {
        property alias x: window.x
        property alias y: window.y
        property alias width: window.width
        property alias height: window.height
    }
}

首次启动应用程序时，窗口的默认尺寸为 800x600。注意没有指定默认位置--我们让窗口管理器来处理。以后当窗口几何形状发生变化时，新值将自动存储到持久设置中。第二个应用程序运行时，将从持久设置中获取初始值，使窗口恢复到以前的位置和大小。

通过使用属性别名实现完全声明式语法的代价是，每当别名属性的值发生变化时，都要存储持久设置。可以使用普通属性对存储持久设置进行更精细的控制。下面的示例说明了如何在组件销毁时保存设置。

import QtCore
import QtQuick

Item {
    id: page

    state: settings.state

    states: [
        State {
            name: "active"
            // ...
        },
        State {
            name: "inactive"
            // ...
        }
    ]

    Settings {
        id: settings
        property string state: "active"
    }

    Component.onDestruction: {
        settings.state = page.state
    }
}

请注意默认值现在是如何在持久化设置属性中指定的，实际属性与设置绑定，以便从持久化设置中获取初始值。

应用程序标识符

应用程序特定设置可通过提供应用程序name 、organization 和domain 或指定location 来标识。

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    app.setOrganizationName("Some Company");
    app.setOrganizationDomain("somecompany.com");
    app.setApplicationName("Amazing Application");

    QQmlApplicationEngine engine("main.qml");
    return app.exec();
}

这些通常在main() 开头的 C++ 中指定，但也可在 QML 中通过以下属性控制：

类别

通过category 属性指定类别名称，可将应用程序设置划分为逻辑类别。使用逻辑类别不仅能使设置结构更简洁，还能防止设置键之间可能出现的冲突。

如果需要多个类别，可使用多个 "设置 "对象，每个对象都有自己的类别：

Item {
    id: panel

    visible: true

    Settings {
        category: "OutputPanel"
        property alias visible: panel.visible
        // ...
    }

    Settings {
        category: "General"
        property alias fontSize: fontSizeSpinBox.value
        // ...
    }
}

与其确保应用程序中的所有设置都有唯一的名称，不如将设置划分为唯一的类别，这样就可以包含与其他类别中使用的名称相同的设置，而不会产生冲突。

设置单例

让每个 QML 文件都能以单例形式使用设置通常很有用。有关例子，请参阅To Do List 示例。具体来说，AppSettings.qml是单例，在CMakeLists.txt 文件中，QT_QML_SINGLETON_TYPE 属性通过set_source_files_properties 设置为TRUE 。

注释

当前的实现基于QSettings 。这带来了某些限制，例如缺少更改通知。使用一个 "设置 "实例写入设置值不会更新另一个 "设置 "实例中的值，即使它们引用的是同一类别中的同一设置。

这些信息在 Windows 系统中存储在系统注册表中，在 macOS 系统中存储在 XML 偏好设置文件中。在其他 Unix 系统上，由于缺乏标准，则使用 INI 文本文件。更多详情，请参阅QSettings 文档。

另请参见 QSettings 。

属性文档

category : string

该属性包含设置类别的名称。

类别可用于将相关设置分组。

另请参阅 QSettings::group 。

location : url

此属性包含设置文件的路径。如果文件不存在，则将创建该文件。

如果该属性为空（默认值），则将使用QSettings::defaultFormat() 。否则，将使用QSettings::IniFormat 。

另请参阅 QSettings::fileName,QSettings::defaultFormat, 和QSettings::IniFormat 。

方法文档

setValue(string key, var value)

将设置key 的值设置为value 。如果键已经存在，先前的值将被覆盖。

另请参阅 value() 和QSettings::setValue 。

sync()

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

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

另请参阅 QSettings::sync 。

var value(string key, var defaultValue)

返回key 的设置值。如果设置不存在，则返回defaultValue 。

另请参阅 setValue() 和QSettings::value 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.