En esta página

Propiedades vinculables

Muestra cómo el uso de propiedades vinculables puede simplificar tu código C++.

En este ejemplo mostraremos dos enfoques para expresar las relaciones entre diferentes objetos que dependen unos de otros: el basado en la conexión señal/ranura y el basado en propiedades vinculables. Para ello, tomaremos como ejemplo un modelo de servicio de suscripción para calcular el coste de la suscripción.

Formulario de suscripción con edad, periodicidad, banderas de países y precio mensual

Modelado del sistema de suscripción con el enfoque de señales y ranuras

Consideremos primero la implementación habitual anterior a Qt 6. Para modelar el servicio de suscripción se utiliza la clase ` Subscription `:

class Subscription : public QObject
{
    Q_OBJECT
public:
    enum Duration { Monthly = 1, Quarterly = 3, Yearly = 12 };

    Subscription(User *user);

    void calculatePrice();
    int price() const { return m_price; }

    Duration duration() const { return m_duration; }
    void setDuration(Duration newDuration);

    bool isValid() const { return m_isValid; }
    void updateValidity();

signals:
    void priceChanged();
    void durationChanged();
    void isValidChanged();

private:
    double calculateDiscount() const;
    int basePrice() const;

    QPointer<User> m_user;
    Duration m_duration = Monthly;
    int m_price = 0;
    bool m_isValid = false;
};

Esta almacena la información sobre la suscripción y proporciona los métodos getter, setter y señales de notificación correspondientes para informar a los oyentes de los cambios en la información de la suscripción. Además, mantiene un puntero a una instancia de la clase ` User `.

El precio de la suscripción se calcula en función de la duración de la misma:

double Subscription::calculateDiscount() const
{
    switch (m_duration) {
    case Monthly:
        return 1;
    case Quarterly:
        return 0.9;
    case Yearly:
        return 0.6;
    }
    Q_ASSERT(false);
    return -1;
}

Y la ubicación del usuario:

int Subscription::basePrice() const
{
    if (m_user->country() == User::Country::AnyTerritory)
        return 0;

    return (m_user->country() == User::Country::Norway) ? 100 : 80;
}

Cuando el precio cambia, se emite la señal ` priceChanged() ` para notificar a los oyentes sobre el cambio:

void Subscription::calculatePrice()
{
    const auto oldPrice = m_price;

    m_price = qRound(calculateDiscount() * int(m_duration) * basePrice());
    if (m_price != oldPrice)
        emit priceChanged();
}

Del mismo modo, cuando cambia la duración de la suscripción, se emite la señal ` durationChanged() `.

void Subscription::setDuration(Duration newDuration)
{
    if (newDuration != m_duration) {
        m_duration = newDuration;
        calculatePrice();
        emit durationChanged();
    }
}

Nota: Ambos métodos deben comprobar si los datos han cambiado realmente y solo entonces emitir las señales. « setDuration() » también debe recalcular el precio cuando la duración haya cambiado.

La clase ` Subscription ` no es válida a menos que el usuario tenga un país y una edad válidos, por lo que la validez se actualiza de la siguiente manera:

void Subscription::updateValidity()
{
    bool isValid = m_isValid;
    m_isValid = m_user->country() != User::Country::AnyTerritory && m_user->age() > 12;

    if (m_isValid != isValid)
        emit isValidChanged();
}

La clase « User » es sencilla: almacena el país y la edad del usuario y proporciona los métodos getter, setter y las señales de notificación correspondientes:

class User : public QObject
{
    Q_OBJECT

public:
    using Country = QLocale::Territory;

public:
    Country country() const { return m_country; }
    void setCountry(Country country);

    int age() const { return m_age; }
    void setAge(int age);

signals:
    void countryChanged();
    void ageChanged();

private:
    Country m_country { QLocale::AnyTerritory };
    int m_age { 0 };
};

void User::setCountry(Country country)
{
    if (m_country != country) {
        m_country = country;
        emit countryChanged();
    }
}

void User::setAge(int age)
{
    if (m_age != age) {
        m_age = age;
        emit ageChanged();
    }
}

En la función « main() » inicializamos instancias de « User » y « Subscription »:

    User user;
    Subscription subscription(&user);

Y realizamos las conexiones adecuadas entre señales y ranuras para actualizar los datos de user y subscription cuando cambian los elementos de la interfaz de usuario. Esto es muy sencillo, así que nos saltaremos esta parte.

A continuación, nos conectamos a Subscription::priceChanged() para actualizar el precio en la interfaz de usuario cuando este cambie.

    QObject::connect(&subscription, &Subscription::priceChanged, priceDisplay, [&] {
        QLocale lc{QLocale::AnyLanguage, user.country()};
        priceDisplay->setText(lc.toCurrencyString(subscription.price() / subscription.duration()));
    });

También nos conectamos a Subscription::isValidChanged() para desactivar la visualización del precio si la suscripción no es válida.

    QObject::connect(&subscription, &Subscription::isValidChanged, priceDisplay, [&] {
        priceDisplay->setEnabled(subscription.isValid());
    });

Dado que el precio y la validez de la suscripción también dependen del país y la edad del usuario, también debemos conectarnos a las señales User::countryChanged() y User::ageChanged() y actualizar subscription en consecuencia.

    QObject::connect(&user, &User::countryChanged, &subscription, [&] {
        subscription.calculatePrice();
        subscription.updateValidity();
    });

    QObject::connect(&user, &User::ageChanged, &subscription, [&] {
        subscription.updateValidity();
    });

Esto funciona, pero hay algunos problemas:

  • Hay mucho código repetitivo para las conexiones de señales y ranuras con el fin de realizar un seguimiento adecuado de los cambios tanto en user como en subscription. Si cambia alguna de las dependencias del precio, debemos acordarnos de emitir las señales de notificación correspondientes, recalcular el precio y actualizarlo en la interfaz de usuario.
  • Si en el futuro se añaden más dependencias para el cálculo del precio, tendremos que añadir más conexiones de señal-ranura y asegurarnos de que todas las dependencias se actualicen correctamente cada vez que alguna de ellas cambie. La complejidad general aumentará y el código será más difícil de mantener.
  • Las clases « Subscription » y « User » dependen del sistema de metaobjetos para poder utilizar el mecanismo de señales y ranuras.

¿Podemos hacerlo mejor?

Modelado del sistema de suscripción con propiedades vinculables

Veamos ahora cómo las propiedades vinculables de Qt pueden ayudar a resolver el mismo problema. En primer lugar, echemos un vistazo a la clase ` BindableSubscription `, que es similar a la clase ` Subscription `, pero está implementada mediante propiedades vinculables:

class BindableSubscription
{
public:
    enum Duration { Monthly = 1, Quarterly = 3, Yearly = 12 };

    BindableSubscription(BindableUser *user);
    BindableSubscription(const BindableSubscription &) = delete;

    int price() const { return m_price; }
    QBindable<int> bindablePrice() { return &m_price; }

    Duration duration() const { return m_duration; }
    void setDuration(Duration newDuration);
    QBindable<Duration> bindableDuration() { return &m_duration; }

    bool isValid() const { return m_isValid; }
    QBindable<bool> bindableIsValid() { return &m_isValid; }

private:
    double calculateDiscount() const;
    int basePrice() const;

    BindableUser *m_user;
    QProperty<Duration> m_duration { Monthly };
    QProperty<int> m_price { 0 };
    QProperty<bool> m_isValid { false };
};

La primera diferencia que podemos observar es que los campos de datos ahora están envueltos dentro de clases ` QProperty `, y las señales del notificador (y, en consecuencia, la dependencia del sistema de metaobjetos) han desaparecido; en su lugar, se han añadido nuevos métodos que devuelven un ` QBindable ` para cada ` QProperty `. También se han eliminado los métodos ` calculatePrice() ` y ` updateValidty() `. Más adelante veremos por qué ya no son necesarios.

La clase BindableUser se diferencia de la clase User de manera similar:

class BindableUser
{
public:
    using Country = QLocale::Territory;

public:
    BindableUser() = default;
    BindableUser(const BindableUser &) = delete;

    Country country() const { return m_country; }
    void setCountry(Country country);
    QBindable<Country> bindableCountry() { return &m_country; }

    int age() const { return m_age; }
    void setAge(int age);
    QBindable<int> bindableAge() { return &m_age; }

private:
    QProperty<Country> m_country { QLocale::AnyTerritory };
    QProperty<int> m_age { 0 };
};

La segunda diferencia radica en la implementación de estas clases. En primer lugar, las dependencias entre subscription y user se controlan ahora mediante expresiones de enlace:

BindableSubscription::BindableSubscription(BindableUser *user) : m_user(user)
{
    Q_ASSERT(user);

    m_price.setBinding(
            [this] { return qRound(calculateDiscount() * int(m_duration) * basePrice()); });

    m_isValid.setBinding([this] {
        return m_user->country() != BindableUser::Country::AnyCountry && m_user->age() > 12;
    });
}

En segundo plano, las propiedades vinculables realizan un seguimiento de los cambios en las dependencias y actualizan el valor de la propiedad cada vez que se detecta un cambio. Así, si, por ejemplo, se modifica el país o la edad del usuario, el precio y la validez de la suscripción se actualizarán automáticamente.

Otra diferencia es que los setters ahora son muy sencillos:

void BindableSubscription::setDuration(Duration newDuration)
{
    m_duration = newDuration;
}

void BindableUser::setCountry(Country country)
{
    m_country = country;
}

void BindableUser::setAge(int age)
{
    m_age = age;
}

No es necesario comprobar dentro de los setters si el valor de la propiedad ha cambiado realmente, ya que « QProperty » ya se encarga de ello. Las propiedades dependientes solo recibirán una notificación sobre el cambio si el valor ha cambiado realmente.

El código para actualizar la información sobre el precio en la interfaz de usuario también se ha simplificado:

    auto priceChangeHandler = subscription.bindablePrice().subscribe([&] {
        QLocale lc{QLocale::AnyLanguage, user.country()};
        priceDisplay->setText(lc.toCurrencyString(subscription.price() / subscription.duration()));
    });

    auto priceValidHandler = subscription.bindableIsValid().subscribe([&] {
        priceDisplay->setEnabled(subscription.isValid());
    });

Nos suscribimos a los cambios a través de bindablePrice() y bindableIsValid() y actualizamos la visualización del precio en consecuencia cuando cualquiera de estas propiedades cambia de valor. Las suscripciones permanecerán activas mientras los controladores correspondientes estén activos.

Ten en cuenta también que los constructores de copia tanto de BindableSubscription como de BindableUser están desactivados, ya que no está definido qué debería ocurrir con sus enlaces al copiarlos.

Como se puede observar, el código se ha simplificado considerablemente y se han resuelto los problemas mencionados anteriormente:

  • Se ha eliminado el código repetitivo de las conexiones señal-ranura; ahora las dependencias se gestionan automáticamente.
  • El código es más fácil de mantener. Añadir más dependencias en el futuro solo requerirá añadir las propiedades vinculables correspondientes y configurar las expresiones de enlace que reflejen las relaciones entre ellas.
  • Las clases ` Subscription ` y ` User ` ya no dependen del sistema de metaobjetos. Por supuesto, aún puedes exponerlas al sistema de metaobjetos y añadir ` Q_PROPERTYs` si lo necesitas, y así disfrutar de las ventajas de las propiedades vinculables tanto en el código ` C++ ` como en el ` QML `. Para ello, puedes utilizar la clase ` QObjectBindableProperty `.

Proyecto de ejemplo en @code.qt.io

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