En esta página

PropertyChanges QML Type

Describe nuevas asignaciones de propiedades o valores para un estado. Más información...

Import Statement: import QtQuick

Propiedades

Descripción detallada

PropertyChanges se utiliza para definir los valores de las propiedades o los enlaces en un elemento de tipo « State ». Esto permite modificar los valores de las propiedades de un elemento cuando este cambia de estado.

Para crear un objeto PropertyChanges, vincúlalo a las propiedades del elemento de destino del mismo modo que lo harías con las propiedades locales. De esta forma, podrás definir los nuevos valores de las propiedades o los enlaces. Por ejemplo:

import QtQuick

Item {
    id: container
    width: 300; height: 300

    Rectangle {
        id: rect
        width: 100; height: 100
        color: "red"

        MouseArea {
           id: mouseArea
           anchors.fill: parent
        }

        states: State {
           name: "resized"; when: mouseArea.pressed
           PropertyChanges {
               rect {
                   color: "blue"
                   height: container.height
               }
           }
        }
    }
}

Al pulsar el botón del ratón, el « Rectangle » pasa al estado «resized ». En este estado, el objeto «PropertyChanges» establece el color del rectángulo en azul y el valor de « height » en el de « container.height ».

Ten en cuenta que esto vincula automáticamente rect.height a container.height en el estado «resized ». Si no se debe establecer una vinculación de propiedad y la altura solo debe fijarse en el valor de container.height en el momento del cambio de estado, establece la propiedad explicit en true.

Un objeto `PropertyChanges` también puede anular el controlador de señales predeterminado de un objeto para implementar un controlador de señales específico para el nuevo estado:

PropertyChanges {
    myMouseArea.onClicked: doSomethingDifferent()
}

Nota: PropertyChanges se puede utilizar para modificar los márgenes de anclaje, pero no otros valores de anclaje; para ello, utilice en su lugar AnchorChanges. Del mismo modo, para modificar el valor de « parent » de un « Item », utilice en su lugar ParentChange.

Restablecimiento de los valores de las propiedades

El valor undefined se puede utilizar para restablecer el valor de la propiedad de un estado. En el siguiente ejemplo, cuando myText cambia al estado widerText, su propiedad width se restablece, lo que da al texto su ancho natural y muestra toda la cadena en una sola línea.

Rectangle {
    width: 300; height: 200

    Text {
        id: myText
        width: 50
        wrapMode: Text.WordWrap
        text: "a text string that is longer than 50 pixels"

        states: State {
            name: "widerText"
            PropertyChanges { myText.width: undefined }
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: myText.state = "widerText"
    }
}

Cambios inmediatos en las propiedades durante las transiciones

Cuando se utilizan transiciones para animar cambios de estado, estas animan las propiedades desde sus valores en el estado actual hasta los definidos en el nuevo estado (tal y como se definen en los objetos `PropertyChanges`). Sin embargo, a veces resulta conveniente establecer el valor de una propiedad de forma inmediata durante una ` Transition`, sin animación; en estos casos, se puede utilizar el tipo ` PropertyAction ` para forzar un cambio inmediato de la propiedad.

Consulte la documentación de ` PropertyAction ` para obtener más detalles.

Nota: Las propiedades « visible » y « enabled » de « Item » no se comportan exactamente igual que otras propiedades en «PropertyChanges». Dado que estas propiedades pueden modificarse implícitamente a través del estado de su elemento padre, deben establecerse explícitamente en todos los «PropertyChanges». Un elemento seguirá sin estar habilitado o visible si alguno de sus elementos padres no lo está.

Nota: Para garantizar la compatibilidad con versiones anteriores de Qt 5, también puedes especificar PropertyChanges utilizando la propiedad « target » y nombres de propiedad sin identificadores. Por ejemplo: « PropertyChanges { target: myItem; x: 15 } ». Se recomienda utilizar la forma con «ID» en lugar de « target ». Es posible que también tengas que utilizar la forma con « target » si el archivo se va a editar con Qt Design Studio. Ten en cuenta que Qt Design Studio también impone una serie de restricciones adicionales sobre los archivos con los que puede trabajar.

Véase también el ejemplo de «Estados», Qt Quick States, y Qt Qml.

Documentación sobre propiedades

explicit : bool

Si «explicit» se establece en «true», las vinculaciones se interpretarán como asignaciones. La expresión solo se evaluará una vez y no se producirán actualizaciones, aunque cambien las dependencias.

En el siguiente ejemplo, la inclusión de «explicit» impide que « myItem.width » se vincule a « parent.width ». En su lugar, se le asigna el valor de « parent.width » en el momento del cambio de estado.

PropertyChanges {
    target: myItem
    explicit: true
    width: parent.width
}

Por defecto, «explicit» es «false».

restoreEntryValues : bool

Esta propiedad determina si se deben restaurar los valores anteriores al salir del estado.

El valor por defecto es « true ». Al establecer este valor en « false », se crea un estado temporal que tiene efectos permanentes en los valores de las propiedades.

target : QtObject

Esta propiedad contiene el objeto que incluye las propiedades que se van a modificar.

Nota: Por lo general, no es necesario utilizar esta propiedad. Solo existe por motivos de compatibilidad con Qt 5 y con Qt Design Studio.

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