设置 QML 类型

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

导入语句	import QtCore
自	Qt 6.5
继承	QtObject

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

属性

category : string
location : url

方法

setValue(string key, var value)
同步()
var value(string key, var defaultValue)

详细描述

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

用户通常期望应用程序能够记住其设置（窗口大小和位置、选项等），跨会话保持不变。Settings 类型使您能够以最小的努力保存和恢复此类应用程序设置。

通过在 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 中控制

分类

可以通过通过在 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。

方法文档

setValue(string key, var value)

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

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

同步()

将任何未保存的更改写入永久存储，并重新加载在同时由另一个应用程序更改的任何设置。

此函数会自动从 QSettings 的析构函数和事件循环以常规时间间隔调用，因此您通常不需要自己调用它。

另请参阅 QSettings::sync。

var value(string key, var defaultValue)

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

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