En esta página

Settings QML Type

Proporciona una configuración de aplicación persistente e independiente de la plataforma. Más información...

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

Este tipo está obsoleto desde Qt.labs.settings 6.5. Recomendamos encarecidamente no utilizarlo en código nuevo.

Propiedades

Métodos

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

Descripción detallada

Utiliza en su lugar « Settings » de Qt Qml Core.

El tipo «Settings» proporciona una configuración de aplicación persistente e independiente de la plataforma.

Nota: Este tipo está disponible al importar el módulo Qt.labs.settings. No se garantiza que los tipos del módulo Qt.labs sigan siendo compatibles en futuras versiones.

Los usuarios suelen esperar que una aplicación recuerde su configuración (tamaños y posiciones de ventanas, opciones, etc.) entre sesiones. El tipo «Settings» te permite guardar y restaurar dicha configuración de la aplicación con el mínimo esfuerzo.

Los valores de configuración individuales se especifican declarando propiedades dentro de un elemento «Settings». Se admiten todas las propiedades de tipo valor. Se recomienda utilizar alias de propiedades para obtener actualizaciones automáticas de las mismas en ambos sentidos. El siguiente ejemplo muestra cómo utilizar «Settings» para almacenar y restaurar la geometría de una ventana.

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
    }
}

Al iniciar la aplicación por primera vez, la ventana adquiere unas dimensiones predeterminadas de 800x600. Obsérvese que no se especifica ninguna posición por defecto: dejamos que el gestor de ventanas se encargue de ello. Más adelante, cuando cambie la geometría de la ventana, los nuevos valores se almacenarán automáticamente en la configuración persistente. La segunda vez que se ejecute la aplicación, se obtendrán los valores iniciales de la configuración persistente, lo que devolverá la ventana a su posición y tamaño anteriores.

Una sintaxis totalmente declarativa, que se consigue mediante el uso de alias de propiedades, conlleva el coste de almacenar la configuración persistente cada vez que cambian los valores de las propiedades con alias. Se pueden utilizar propiedades normales para obtener un control más preciso sobre el almacenamiento de la configuración persistente. El siguiente ejemplo ilustra cómo guardar una configuración al destruirse un componente.

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
    }
}

Fíjate en cómo ahora se especifica el valor por defecto en la propiedad de configuración persistente, y la propiedad real está vinculada a dicha configuración para obtener el valor inicial de la configuración persistente.

Identificadores de aplicación

Los ajustes específicos de la aplicación se identifican proporcionando los identificadores de aplicación name, organization y domain, o bien especificando 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();
}

Normalmente se especifican en C++ al principio de main(), pero también se pueden controlar en QML mediante las siguientes propiedades:

Categorías

La configuración de la aplicación se puede dividir en categorías lógicas especificando un nombre de categoría mediante la propiedad category. El uso de categorías lógicas no solo proporciona una estructura de configuración más clara, sino que también evita posibles conflictos entre las claves de configuración.

Si se necesitan varias categorías, utiliza varios objetos `Settings`, cada uno con su propia categoría:

Item {
    id: panel

    visible: true

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

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

En lugar de asegurarse de que todas las configuraciones de la aplicación tengan nombres únicos, estas se pueden dividir en categorías únicas que, a su vez, pueden contener configuraciones con los mismos nombres que se utilizan en otras categorías, sin que ello suponga ningún conflicto.

Notas

La implementación actual se basa en QSettings. Esto impone ciertas limitaciones, como la ausencia de notificaciones de cambios. Escribir un valor de configuración utilizando una instancia de Settings no actualiza el valor en otra instancia de Settings, incluso si ambas hacen referencia a la misma configuración dentro de la misma categoría.

La información se almacena en el registro del sistema en Windows y en archivos de preferencias XML en macOS. En otros sistemas Unix, a falta de un estándar, se utilizan archivos de texto INI. Consulta la documentación de QSettings para obtener más detalles.

Véase también Settings y QSettings.

Documentación sobre propiedades

category : string

Esta propiedad contiene el nombre de la categoría de configuración.

Las categorías se pueden utilizar para agrupar ajustes relacionados.

fileName : string [since Qt 5.12]

Esta propiedad contiene la ruta al archivo de configuración. Si el archivo aún no existe, se crea.

Esta propiedad se introdujo en Qt 5.12.

Véase también QSettings::fileName y QSettings::IniFormat.

Documentación del método

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

Establece el valor de la propiedad « key » en « value ». Si la clave ya existe, se sobrescribe el valor anterior.

Este método se introdujo en Qt 5.12.

Véase también value() y QSettings::setValue.

void sync()

Guarda en el almacenamiento permanente cualquier cambio no guardado y vuelve a cargar cualquier configuración que haya sido modificada entretanto por otra aplicación.

Esta función se invoca automáticamente desde el destructor de ` QSettings` y mediante el bucle de eventos a intervalos regulares, por lo que normalmente no es necesario que la invoques tú mismo.

Véase también QSettings::sync.

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

Devuelve el valor de la configuración « key ». Si la configuración no existe, devuelve « defaultValue ».

Este método se introdujo en Qt 5.12.

Véase también setValue() y QSettings::value.

© 2026 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.