Settings QML Type

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

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

属性

• category : string
• location : url

方法

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

详细说明

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

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

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

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

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

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

设置单例

通常，将设置作为单例供每个 QML 文件使用非常有用。有关示例，请参阅“待办事项列表”示例。具体来说，AppSettings.qml就是该单例，而在CMakeLists.txt 文件中，通过set_source_files_properties 将该文件的QT_QML_SINGLETON_TYPE 属性设置为TRUE 。

注释

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

在 Windows 系统中，信息存储在系统注册表中；在 macOS 系统中，则存储在 XML 首选项文件中。在其他 Unix 系统中，由于缺乏统一标准，通常使用 INI 文本文件。更多详细信息请参阅QSettings 文档。

另请参阅 QSettings 。

属性文档

category : string

该属性存储设置类别的名称。

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

另请参阅 QSettings::group 。

location : url

该属性存储设置文件的路径。如果该文件尚不存在，系统将自动创建该文件。

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

另请参阅 QSettings::fileName 、QSettings::defaultFormat 以及QSettings::IniFormat 。

方法文档

void setValue(string key, var value)

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

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

void sync()

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

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

另请参阅 QSettings::sync 。

var value(string key, var defaultValue)

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

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