Settings QML Type

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

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

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

属性

• category : string
• fileName : string (since Qt 5.12)

方法

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

详细说明

请改用Qt Qml Core 中的 `Settings `。

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

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

通过在 Settings 元素中声明属性来指定各个设置值。支持所有值类型的属性。建议使用属性别名，以便实现双向的自动属性更新。以下示例展示了如何使用 Settings 来存储和恢复窗口的几何属性。

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

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

• Qt.application.name,
• Qt.application.organization 以及
• Qt.application.domain。

类别

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

如果需要多个类别，请使用多个 Settings 对象，每个对象对应一个类别：

Item {
    id: panel

    visible: true

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

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

与其确保应用程序中的所有设置名称都是唯一的，不如将设置划分为不同的类别，这样同一名称的设置即使出现在不同类别中，也不会产生冲突。

注意事项

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

该信息在 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] void setValue(string key, var value)

将key 设置的值设为value 。如果该键已存在，则会覆盖其原有值。

该方法自 Qt 5.12 起引入。

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

void sync()

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

该函数会由QSettings 的析构函数自动调用，并由事件循环以固定间隔调用，因此通常无需手动调用。

另请参阅 QSettings::sync 。

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

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

该方法自 Qt 5.12 起引入。

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