Settings QML Type

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

Import Statement:	`import Qt.labs.settings 1.0`
Status:	Deprecated since 6.5

自 Qt.labs.settings 6.5 起，该类型已被弃用。我们强烈建议不要在新代码中使用它。

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

属性

category : string
fileName : string (since Qt 5.12)

方法

setValue(string key, var value) (since Qt 5.12)
sync()
var value(string key, var defaultValue) (since Qt 5.12)

详细说明

请使用Settings fromQt Qml Core 。

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

注意： 该类型通过导入Qt.labs.settings模块可用。Qt.labs 模块中的类型不保证在未来版本中保持兼容。

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

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

import QtQuick.Window
import Qt.labs.settings

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 QtQuick
import Qt.labs.settings

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 或指定fileName 来标识。

#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
        // ...
    }
}

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

注释

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

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

另请参阅 Settings 和QSettings 。

属性文档

category : string

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

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

fileName : string [since Qt 5.12]

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

此属性在 Qt 5.12 中引入。

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

方法文档

[since Qt 5.12] setValue(string key, var value)

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

此方法在 Qt 5.12 中引入。

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

sync()

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

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

另请参见 QSettings::sync 。

[since Qt 5.12] var value(string key, var defaultValue)

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

此方法在 Qt 5.12 中引入。

另请参阅 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.