QQmlPropertyMap Class
La clase QQmlPropertyMap permite definir pares clave-valor que se pueden utilizar en los enlaces de QML. Más información...
| Encabezado: | #include <QQmlPropertyMap> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Heredado de: | QObject |
Funciones públicas
| virtual | ~QQmlPropertyMap() override |
| void | clear(const QString &key) |
| bool | contains(const QString &key) const |
| int | count() const |
(since 6.1) void | freeze() |
(since 6.1) void | insert(const QVariantHash &values) |
| void | insert(const QString &key, const QVariant &value) |
| bool | isEmpty() const |
| QStringList | keys() const |
| int | size() const |
| QVariant | value(const QString &key) const |
| QVariant & | operator[](const QString &key) |
| QVariant | operator[](const QString &key) const |
Señales
| void | valueChanged(const QString &key, const QVariant &value) |
Miembros públicos estáticos
| QQmlPropertyMap * | create(QObject *parent = nullptr) |
Funciones protegidas
| QQmlPropertyMap(DerivedType *derived, QObject *parent) | |
| virtual QVariant | updateValue(const QString &key, const QVariant &input) |
Descripción detallada
QQmlPropertyMap ofrece una forma cómoda de exponer datos de dominio a la capa de interfaz de usuario. El siguiente ejemplo muestra cómo se pueden declarar datos en C++ y, a continuación, acceder a ellos en QML.
En el archivo C++:
// create our data
QQmlPropertyMap ownerData;
ownerData.insert("name", QVariant(QString("John Smith")));
ownerData.insert("phone", QVariant(QString("555-5555")));
// expose it to the UI layer
QQuickView view;
QQmlContext *ctxt = view.rootContext();
ctxt->setContextProperty("owner", &ownerData);
view.setSource(QUrl::fromLocalFile("main.qml"));
view.show();A continuación, en main.qml:
Text { text: owner.name + " " + owner.phone }El enlace es dinámico: cada vez que se actualice el valor de una clave, todo lo vinculado a esa clave se actualizará también.
Para detectar los cambios de valor realizados en la capa de interfaz de usuario, puedes conectarte a la señal ` valueChanged()`. Sin embargo, ten en cuenta que ` valueChanged()` NO se emite cuando los cambios se realizan llamando a ` insert()` o ` clear()`; solo se emite cuando se actualiza un valor desde QML.
Nota: Noes posible eliminar claves del mapa; una vez añadida una clave, solo se puede modificar o borrar el valor asociado a ella.
Nota: Al derivar una clase de QQmlPropertyMap, utiliza el protected two-argument constructor, que garantiza que la clase se registre correctamente en el sistema de metaobjetos de Qt.
Nota: El QMetaObject de un QQmlPropertyMap se genera y modifica dinámicamente. Las operaciones sobre ese metaobjeto no son seguras para subprocesos, por lo que las aplicaciones deben asegurarse de sincronizar explícitamente el acceso al metaobjeto.
Documentación de las funciones miembro
[protected] template <typename DerivedType> QQmlPropertyMap::QQmlPropertyMap(DerivedType *derived, QObject *parent)
Crea un mapa vinculable con el objeto padre ` parent`. Utiliza este constructor en clases derivadas de `QQmlPropertyMap`.
El tipo de ` derived ` se utiliza para registrar el mapa de propiedades en el sistema de metaobjetos, lo cual es necesario para garantizar que se pueda acceder a las propiedades de la clase derivada. Este tipo debe derivarse de `QQmlPropertyMap`.
En el archivo C++:
class MyQmlPropertyMap : public QQmlPropertyMap
{
Q_OBJECT
QML_NAMED_ELEMENT(MyQmlPropertyMap)
public:
explicit MyQmlPropertyMap(QObject *parent = nullptr)
: QQmlPropertyMap(this, parent)
{
insert("name", "John Smith");
insert("phone", "555-5555");
insert("email", "john.smith@example.com");
}
public slots:
void updateEmail(const QString &newEmail)
{
insert("email", newEmail);
}
};
QQuickView view;
view.setSource(QUrl("qrc:/main.qml"));
view.show();A continuación, en main.qml:
MyQmlPropertyMap
{
id : owner
Component.onCompleted: { owner.updateEmail("new.email@example.com") }
}
Text { text : owner.name + " " + owner.phone + " " + owner.email }[override virtual noexcept] QQmlPropertyMap::~QQmlPropertyMap()
Elimina el mapa vinculable.
void QQmlPropertyMap::clear(const QString &key)
Borra el valor (si lo hay) asociado a « key ».
bool QQmlPropertyMap::contains(const QString &key) const
Devuelve «true» si el mapa contiene « key ».
Véase también size().
int QQmlPropertyMap::count() const
Es lo mismo que « size()».
[static] QQmlPropertyMap *QQmlPropertyMap::create(QObject *parent = nullptr)
Crea un mapa vinculable cuyo objeto padre es parent.
[since 6.1] void QQmlPropertyMap::freeze()
No permite añadir más propiedades a este mapa de propiedades. Las propiedades existentes se pueden modificar o eliminar.
A su vez, se activa una caché interna para las propiedades existentes, lo que puede traducirse en un acceso más rápido desde QML.
Esta función se introdujo en Qt 6.1.
[since 6.1] void QQmlPropertyMap::insert(const QVariantHash &values)
Inserta la tabla « values » en la base de datos « QQmlPropertyMap ».
Las claves que no existen se crean automáticamente.
Este método es considerablemente más rápido que llamar a ` insert(key, value) ` varias veces seguidas.
Esta función se introdujo en Qt 6.1.
void QQmlPropertyMap::insert(const QString &key, const QVariant &value)
Establece el valor asociado a « key » en « value ».
Si la clave no existe, se crea automáticamente.
bool QQmlPropertyMap::isEmpty() const
Devuelve «true» si el mapa no contiene claves; en caso contrario, devuelve «false».
Véase también size().
[invokable] QStringList QQmlPropertyMap::keys() const
Devuelve la lista de claves.
Las claves que se hayan borrado seguirán apareciendo en esta lista, aunque sus valores asociados sean QVariants no válidos.
Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.
int QQmlPropertyMap::size() const
Devuelve el número de claves del mapa.
Véase también isEmpty() y count().
[virtual protected] QVariant QQmlPropertyMap::updateValue(const QString &key, const QVariant &input)
Devuelve el nuevo valor que se va a almacenar para la clave « key ». Esta función se proporciona para interceptar las actualizaciones de una propiedad desde QML, donde el valor proporcionado desde QML es « input ».
Sobrescribe esta función para manipular el valor de la propiedad a medida que se actualiza. Ten en cuenta que esta función solo se invoca cuando el valor se actualiza desde QML.
QVariant QQmlPropertyMap::value(const QString &key) const
Devuelve el valor asociado a « key ».
Si no se ha establecido ningún valor para esta clave (o si se ha borrado el valor), se devuelve un ` QVariant ` no válido.
[signal] void QQmlPropertyMap::valueChanged(const QString &key, const QVariant &value)
Esta señal se emite cada vez que se modifica uno de los valores del mapa. « key » es la clave correspondiente al « value » que se ha modificado.
Nota: valueChanged () NO se emite cuando los cambios se realizan llamando a insert() o clear(); solo se emite cuando se actualiza un valor desde QML.
QVariant &QQmlPropertyMap::operator[](const QString &key)
Devuelve el valor asociado a la clave « key » como una referencia modificable.
Si el mapa no contiene ningún elemento con la clave key, la función inserta un QVariant no válido en el mapa con la clave key y devuelve una referencia al mismo.
Véase también insert() y value().
QVariant QQmlPropertyMap::operator[](const QString &key) const
Es lo mismo que ` value()`.
Esta es una función sobrecargada.
© 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.