En esta página

Qt Protobuf Tipos QML

Con el complemento generador, puedes registrar mensajes protobuf en QML. Para registrar el tipo, utiliza las claves de generación QML y QML_URI. Consulta los detalles de la API en el comando qt_add_protobuf() y el ejemplo de uso de la API «QML extended protobuf».

Los mensajes protobuf registrados están disponibles en QML, al igual que los tipos Q_GADGET integrados. El registro se realiza a través del módulo QML.

Uso de mensajes protobuf en QML

Utiliza el complemento generador para generar bibliotecas de mensajes protobuf a las que puedas acceder desde aplicaciones Qt Quick. La API de CMake deQt Protobuf dispone de opciones específicas que controlan la creación del módulo QML.

Por ejemplo, tienes el esquema protobuf « userdb.proto » que contiene el mensaje « User »:

syntax = "proto3";

package userdb;

message User {
    enum Type {
        Admin = 0;
        Manager = 1;
        Account = 2;
        Director = 3;
    }
    Type type = 1;
    string name = 2;
    string email = 3;
}

Para exponer el mensaje « User » en QML, utiliza el esquema protobuf y el comando `qt_add_protobuf()` con el argumento « QML »:

qt_add_executable(appuserdb
    ...
)

qt_add_qml_module(appuserdb
    URI userdb
    VERSION 1.0
    QML_FILES
        ...
    SOURCES
        ...
)

qt_add_protobuf(userdb_gen
    QML
    QML_URI "userdb.pb"
    PROTO_FILES
        userdb.proto
)

target_link_libraries(appuserdb PRIVATE userdb_gen)

La función qt_add_protobuf() generará una biblioteca llamada userdb_gen, que contiene los mensajes protobuf de userdb.proto con soporte para QML. Para utilizar los mensajes en QML, importa el módulo QML generado utilizando el URI especificado en el argumento QML_URI de la llamada a qt_add_protobuf:

import userdb.pb

Todos los mensajes protobuf se registran como tipos de valor de QML. Para utilizarlos en QML, define el atributo «property» para algún elemento de QML:

Window {
    id: userAddForm
    property user newUser
    ...
}

Para modificar los campos « type », « name » o « email » de la propiedad « newUser », utiliza las señales de QML. Por ejemplo:

TextField {
    id: userNameField
    onTextChanged: {
        userAddForm.newUser.name = userNameField.text
    }
}
...
TextField {
    id: userEmailField
    onTextChanged: {
        userAddForm.newUser.email = userEmailField.text
    }
}

También se puede acceder a los valores de la enumeración ` User.Type ` desde QML. El siguiente ejemplo muestra cómo crear un elemento ` ComboBox ` utilizando los valores de la enumeración:

ComboBox {
    id: userTypeField
    textRole: "key"
    model: ListModel {
        id: userTypeModel
        ListElement { key: "Admin"; value: User.Admin }
        ListElement { key: "Second"; value: User.Manager }
        ListElement { key: "Account"; value: User.Account }
        ListElement { key: "Director"; value: User.Director }
    }
    onActivated: function(index) {
        userAddForm.newUser.type = userTypeModel.get(index).value
    }
}

Integración de QML y C++

Las clases de C++ registradas en QML pueden utilizar los mensajes creados en QML tanto en propiedades como en métodos invocables.

El objeto QML de tipo singleton ` UserDBEngine ` expone la propiedad ` lastAddedUser ` y el método invocable ` addUser ` a QML:

class UserDBEngine : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON

    Q_PROPERTY(userdb::User lastAddedUser READ lastAddedUser WRITE setLastAddedUser NOTIFY lastAddedUserChanged FINAL)
public:
    ...
    Q_INVOKABLE void addUser(const userdb::User &newUser);
    ...
}

La propiedad ` lastAddedUser ` tiene el tipo ` userdb::User `, generado a partir del esquema ` userdb.proto ` de la sección anterior. El método invocable ` addUser ` acepta una referencia constante a un objeto de tipo ` userdb::User `. Tanto la propiedad como el método pueden utilizarse desde QML:

Button {
    text: "Add"
    onClicked: {
        // Use the property created in the previous section
        UserDBEngine.addUser(userAddForm.newUser)
    }
}
...
Text {
    // The text will be updated automatically when lastAddedUser is changed
    text: "Last added user: " + UserDBEngine.lastAddedUser.name
}

Duplicados de mensajes Protobuf

Debes evitar declarar mensajes Protobuf duplicados en tus archivos *.proto o hacerlo con prudencia. Si tu aplicación utiliza varios nombres de mensajes Protobuf idénticos declarados dentro de diferentes paquetes Protobuf, estos podrían entrar en conflicto entre sí en el código generado automáticamente. En el ejemplo siguiente, dos paquetes Protobuf diferentes, qtprotobufnamespace y qtprotobufnamespace1.nested, utilizan el mismo mensaje Protobuf NestedFieldMessage. El archivo nested.proto:

syntax = "proto3";

package qtprotobufnamespace;
import "externalpackage.proto";

message NestedFieldMessage {
    sint32 testFieldInt = 1;
}

El archivo nestedspace1.proto:

syntax = "proto3";

package qtprotobufnamespace1.nested;

message NestedFieldMessage {
    message NestedMessage {
        sint32 field = 1;
    }
    NestedMessage nested = 1;
}

En caso de que no sea posible evitar la duplicación de nombres entre paquetes, coloque los mensajes duplicados en diferentes módulos QML y utilice un <Qualifier> para cada importación de módulo QML; consulte Importaciones de módulos (espacios de nombres). A continuación se muestra un ejemplo de cómo añadir paquetes protobuf a diferentes módulos QML:

# qtprotobufnamespace QML module
qt_add_protobuf(nestedtypes_qtprotobuf_qml
    PROTO_FILES
        nested.proto
    QML
    QML_URI
        qtprotobufnamespace
    OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen1"
)

...

# qtprotobufnamespace1.nested QML module
qt_add_protobuf(nestedspace_qml
    PROTO_FILES
        nestedspace1.proto
    QML
    QML_URI
        qtprotobufnamespace1.nested
    OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen2"
)

Ejemplo de uso de <Qualifier>:

import qtprotobufnamespace as NestedFieldMessages
import qtprotobufnamespace1.nested as FieldMessages_Nested1

...

property NestedFieldMessages.nestedFieldMessage fieldMsg1;
property FieldMessages_Nested1.nestedFieldMessage fieldMsg2;

Nota: El uso de nombres duplicados generará una advertencia en el momento de la compilación.

Duplicados de tipos QML

Si tu aplicación utiliza mensajes protobuf con nombres que ya están reservados en QML como tipos de QML, no se puede garantizar un comportamiento correcto y se generará un error de « Element is not creatable ». Para evitar la superposición de tipos de QML, utiliza un <Qualifier> al importar módulos QML; consulta «Importaciones de módulos (espacios de nombres)». Por ejemplo, los siguientes mensajes protobuf entrarían en conflicto con los tipos QML Text y Item al importarlos al espacio de nombres global:

syntax = "proto3";
package test.example;

message Text {
    string text = 1;
}

message Item {
    sint32 width = 1;
    sint32 height = 2;
}

Utilice la macro ` qt_add_protobuf() ` con la opción ` QML ` para habilitar la generación de tipos QML a partir de los mensajes protobuf anteriores. Consulte el ejemplo siguiente:

qt_add_protobuf(example
    PROTO_FILES
        test.proto
    QML
    QML_URI
        test.example
)

Se producirán conflictos con los tipos QML si los mensajes protobuf se importan a un espacio de nombres global después de la importación de QtQuick. Véase el ejemplo siguiente:

 import QtQuick
 import test.example

 Item {
    id: root
    ...
    property ProtobufMessages.item itemData
}

Para evitar conflictos con los tipos QML, utiliza un ` <Qualifier> ` para importar el módulo QML generado a un espacio de nombres local. Consulta el ejemplo siguiente:

// No qualifier - global namespace
import QtQuick
// ProtobufMessages - a qualifier of local namespace.
import test.example as ProtobufMessages

Item {
    id: root
    ...
    property ProtobufMessages.item itemData
}

Manejo de palabras clave de QML

Presta atención a las palabras clave que están reservadas en el contexto de QML o JavaScript, pero no en el contexto *.proto. El complemento generador ampliará de forma silenciosa los campos cuyos nombres estén reservados por QML añadiéndoles el sufijo « _proto ». Por ejemplo, « id », « property » y « import » son palabras clave reservadas. Serán sustituidas por « id_proto », « property_proto » y « import_proto »:

message MessageUpperCaseReserved {
    sint32 Import = 1;
    sint32 Property = 2;
    sint32 Id = 3;
}

Código generado:

Q_PROPERTY(QtProtobuf::sint32 import_proto READ import_proto ...)
Q_PROPERTY(QtProtobuf::sint32 property_proto READ property_proto ...)
Q_PROPERTY(QtProtobuf::sint32 id_proto READ id_proto ...)

Además, los valores de las enumeraciones no pueden comenzar con una letra minúscula. El complemento generador pondrá en mayúscula la primera letra en el código generado. Véase el ejemplo de « *.proto » a continuación:

enum LowerCaseEnum {
    enumValue0 = 0;
    enumValue1 = 1;
    enumValue2 = 2;
}

Código generado:

enum LowerCaseEnum {
    EnumValue0 = 0,
    EnumValue1 = 1,
    EnumValue2 = 2,
};
Q_ENUM(LowerCaseEnum)

Asimismo, los campos de enumeración no pueden comenzar con un guión bajo. Dichos campos se generarán tal cual, pero quedarán sin definir en el QML, a menos que el motor QML permita registrarlos en el futuro. Véase el ejemplo « *.proto » a continuación:

enum UnderScoreEnum {
    _enumUnderscoreValue0 = 0;
    _EnumUnderscoreValue1 = 1;
}

Código generado:

enum UnderScoreEnum {
    _enumUnderscoreValue0 = 0,
    _EnumUnderscoreValue1 = 1,
};
Q_ENUM(UnderScoreEnum)

Para obtener más información sobre la sintaxis de las propiedades de QML, consulta Definición de atributos de propiedad.

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