设置 QML 类型

提供持久的平台无关的应用程序设置。更多信息...

导入声明	import Qt.labs.settings 1.0
状态	自 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)

详细描述

请使用来自 Qt QML 核心的 Settings。

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

注意：此类型通过导入 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
    }
}

注意现在已在持久设置属性中指定了默认值，并将实际属性绑定到设置中，以从持久设置中获取初始值。

应用程序标识符

应用程序特定设置可以通过提供应用程序名称、组织和域来识别，或者通过指定文件名。

#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();
}

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

分类

应用程序设置可以通过通过分类属性指定分类名称来分为逻辑分类。使用逻辑分类不仅可以提供更清晰的设置结构，还可以防止设置键之间可能发生的冲突。

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

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。