En esta página

Synchronizer QML Type

Sincroniza los valores entre dos o más propiedades. Más...

Import Statement: import Qt.labs.synchronizer
Since: Qt 6.10

Propiedades

Señales

Descripción detallada

Un objeto Synchronizer vincula dos o más propiedades entre sí, de modo que cualquier cambio en una de ellas actualiza automáticamente todas las demás. Al hacerlo, no se rompe ninguna de las vinculaciones de ninguna de las propiedades. Puedes utilizar el «Synchronizer» si la dirección del flujo de datos entre dos propiedades no está predeterminada. Por ejemplo, un control « TextInput » puede inicializarse con un valor del modelo, pero también debe actualizar dicho valor una vez finalizada la edición.

Nota: Los elementos de entrada que proporcionan los controles « Qt Quick » y « Qt Quick » resuelven este problema al ofrecer señales de interacción del usuario independientes de las señales de cambio de valor y al ocultar las asignaciones de valor en el código C++. No se necesita Synchronizer para su funcionamiento interno. Sin embargo, puede resultar útil a la hora de conectar un control a un modelo.

Consideremos el siguiente ejemplo.

Sin Synchronizer

// MyCustomTextInput.qml
Item {
    property string text
    function append(characters: string) { text += characters }
    [...]
}

Es posible que se sienta tentado a rellenar la propiedad text desde un modelo y actualizar el modelo cuando se reciba la señal textChanged.

// Does not work!
Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        text: root.model
        onTextChanged: root.model = text
    }
}

Esto no funciona. Cuando se llama a la función ` append `, se modifica la propiedad ` text ` y se rompe el enlace que la actualiza a partir de la propiedad ` model `. La próxima vez que se actualice ` model ` de forma independiente, ` text ` ya no se actualizará.

Para resolverlo, puedes omitir por completo el enlace y utilizar únicamente señales para actualizar ambas propiedades. De esta forma, tendrías que renunciar a la comodidad que ofrecen los enlaces.

O bien, puedes utilizar Synchronizer.

Con Synchronizer

Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        Synchronizer on text {
            property alias source: root.model
        }
    }
}

Synchronizer garantiza que, cada vez que cambie el modelo o el texto, la otra propiedad se actualice.

Puedes especificar las propiedades que se van a sincronizar de varias formas:

  • Utilizando la sintaxis « on »
  • Rellenando las propiedades « sourceObject » y « sourceProperty »
  • Rellenando las propiedades ` targetObject ` y ` targetProperty `
  • Creando alias en el ámbito del sincronizador

El siguiente ejemplo sincroniza cuatro propiedades diferentes, utilizando todas las opciones disponibles:

Item {
    id: root
    property string model: "lorem ipsum"

    MyCustomTextInput {
        Synchronizer on text {
            sourceObject: other
            sourceProperty: "text"

            targetObject: root.children[0]
            targetProperty: "objectName"

            property alias source: root.model
            property alias another: root.objectName
        }
    }

    MyCustomTextInput {
        id: other
    }
}

Opcionalmente, Synchronizer realizará una sincronización inicial:

  • Si uno de los alias se llama source, se utilizará para inicializar las demás propiedades.
  • De lo contrario, si los valores asignados a sourceObject y sourceProperty corresponden a una propiedad, dicha propiedad se utilizará como fuente para la sincronización inicial.
  • De lo contrario, si se utiliza la sintaxis on, la propiedad sobre la que se crea el sincronizador de esa forma se utilizará como fuente para la sincronización inicial.
  • De lo contrario, no se lleva a cabo ninguna sincronización inicial. Solo cuando una de las propiedades cambie se actualizarán las demás.

El «Synchronizer» elimina automáticamente el rebote. Mientras se está sincronizando utilizando un valor determinado como fuente, no acepta más actualizaciones de ninguna de las propiedades que se espera que sean el destino de la actualización. De lo contrario, dicho comportamiento conduciría fácilmente a bucles de actualización infinitos. El Synchronizer utiliza la señal « valueBounced » para notificar esta condición. Además, detecta las propiedades que rechazan una actualización de forma silenciosa y emite la señal « valueIgnored » para ellas. En este contexto, se considera «silencioso» la ausencia de una señal de cambio tras llamar al setter de la propiedad en cuestión.

Si las propiedades que se van a sincronizar son de tipos diferentes, se aplican las coerciones de tipo habituales de QML.

Nota: Noes posible crear un alias para una propiedad de un singleton. Al utilizar Synchronizer junto con singletons, utilice sourceObject y sourceProperty, así como las propiedades de destino correspondientes.

Documentación de propiedades

sourceObject : QtObject

Esta propiedad contiene la parte «sourceObject» del par «sourceObject/sourceProperty », que, en conjunto, pueden especificar una de las propiedades que Synchronizer sincronizará.

sourceProperty : string

Esta propiedad «sourceProperty» contiene la parte «sourceProperty» del par « sourceObject »/«sourceProperty», que, en conjunto, pueden especificar una de las propiedades que Synchronizer sincronizará.

targetObject : QtObject

Esta propiedad contiene la parte «targetObject» del par «targetObject/targetProperty », que, en conjunto, pueden especificar una de las propiedades que Synchronizer sincronizará.

targetProperty : string

Esta propiedad «targetProperty» contiene la parte «targetProperty» del par « targetObject » / «targetProperty», que, en conjunto, pueden especificar una de las propiedades que Synchronizer sincronizará.

Documentación de Signal

valueBounced(QtObject object, string property)

Esta señal se emite si el ` property ` del ` object ` ha rechazado un intento de establecer su valor como parte de la sincronización y ha devuelto un valor diferente como respuesta. Dichos valores rechazados se ignoran y no desencadenan otra ronda de sincronización.

Nota: El controlador correspondiente es onValueBounced.

valueIgnored(QtObject object, string property)

Esta señal se emite si un property del object no ha respondido a un intento de establecer su valor como parte de la sincronización.

Nota: El controlador correspondiente es onValueIgnored.

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