En esta página

Cambios en Qt Qml

Qt 6 son el resultado de un esfuerzo deliberado por hacer que el marco de trabajo sea más eficiente y fácil de usar.

Intentamos mantener la compatibilidad binaria y de código fuente para todas las API públicas en cada versión. Sin embargo, algunos cambios eran inevitables para hacer de Qt un marco de trabajo mejor.

En este tema resumimos esos cambios en Qt Qml y ofrecemos orientación para gestionarlos.

Lenguaje QML

Resolución de URL

En Qt 5, las URL relativas solían resolverse directamente, aunque de forma inconsistente, especialmente cuando se asignaban a una propiedad url. En Qt 6 esto ya no es así.

Si tuvieras un archivo QML almacenado en «/home/qml/example.qml», y «example.qml» contuviera

property url imageFolder: "./images"

entonces la propiedad url almacenaría la URL «/home/qml/images». Esto hacía imposible utilizar URL relativas en QML de esta manera, por lo que en Qt 6 la URL sigue siendo relativa y solo se resuelve cuando es necesario (por ejemplo, cuando se utiliza como fuente de un componente Image). Si necesitas el comportamiento anterior, puedes utilizar Qt.resolvedUrl

Por ejemplo, si tienes un código como

property url imageFolder: "./images"

puedes reescribirlo como

property url imageFolder: Qt.resolvedUrl("./images")

Qt.resolvedUrl se puede utilizar tanto en Qt 5 como en Qt 6.

Como ayuda para la migración, la variable de entorno ` QML_COMPAT_RESOLVE_URLS_ON_ASSIGNMENT ` se puede establecer en 1 para obtener el comportamiento de Qt 5. Esto es posible desde Qt 6.2.2. Sin embargo, se recomienda utilizarlo únicamente para desbloquear una migración y recurrir a ` Qt.resolvedUrl ` tal y como se ha explicado anteriormente.

Propiedades de variantes

variant Las propiedades de variante, que se consideraban obsoletas desde Qt 5, ahora se tratan exactamente de la misma manera que las propiedades de tipo « var ». El código que dependía de la conversión implícita de cadenas, que se activaba al asignar valores a propiedades de variante, debe actualizarse para crear explícitamente un objeto del tipo correcto.

Por ejemplo, si tienes un código como

property variant myColor: "red"

puedes reescribirlo como

property variant myColor: Qt.color("red")

Se realizaban conversiones implícitas para cadenas que podían interpretarse como

  • color (utiliza Qt.color en su lugar),
  • fecha (utiliza el objeto Date en su lugar),
  • rect (utiliza Qt.rect en su lugar) y
  • tamaño (utiliza Qt.size en su lugar)

variant sigue siendo una palabra clave obsoleta en Qt 6, aunque se recomienda encarecidamente que el código nuevo utilice propiedades de tipo « var » en su lugar.

Nota: Si se sabe que el tipo de la propiedad no va a cambiar, utiliza una propiedad del tipo concreto, en lugar de una propiedad « var ».

Nota: Estas conversiones también se han aplicado a las propiedades « QVariant » de las clases registradas en el motor. Al igual que con las propiedades « variant », el código que dependía de conversiones implícitas de cadenas debe utilizar las funciones correspondientes del objeto Qt.

Cambios en la API incompatibles con el código fuente

API modificada

QQmlListPropertyLas propiedades « CountFunction » y « AtFunction » se han modificado para utilizar « qsizetype » en lugar de « int », con el fin de alinearlas con los cambios correspondientes en los contenedores de Qt.

Por ejemplo, si tienes un código como

int myCountFunction(QQmlListProperty<MyType> *);
MyType *myAtFunction(QQmlListProperty<MyType> *, int);

QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
                                        &myAtFunction);

puedes reescribirlo como

qsizetype myCountFunction(QQmlListProperty<MyType> *);
MyType *myAtFunction(QQmlListProperty<MyType> *, qsizetype);

QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
                                        &myAtFunction);

El código que deba ser compatible tanto con Qt 5 como con Qt 6 puede utilizar un `typedef` que sea ` int ` en Qt 5 y ` qsizetype ` en Qt 6, o bien utilizar ` QList::size_type`, que ya es un alias de tipo de este tipo.

API eliminada

Se han eliminado varias funciones obsoletas.

  • Se ha eliminado el constructor de ` QQmlListProperty ` que tomaba una referencia.

    Por ejemplo, si tienes un código como

    QQmlListProperty<QObject>(owner, owner->objectList);

    puedes reescribirlo como

    QQmlListProperty<QObject>(owner, &owner->objectList);
  • Las funciones qmlDebug, qmlInfo, qmlWarning, qmlContext y qmlEngine solían existir tanto en el espacio de nombres global (o en el espacio de nombres de Qt en compilaciones con espacios de nombres) como en el espacio de nombres QtQml. Ahora estas funciones solo existen en el espacio de nombres global.

    Por ejemplo, si tienes un código como

    QQmlEngine *engine = QtQml::qmlEngine(qmlObject);

    puedes reescribirlo así:

    QQmlEngine *engine = qmlEngine(qmlObject);
  • Se ha eliminado la sobrecarga de ` qmlRegisterType ` que no admite argumentos. Utiliza en su lugar ` qmlRegisterAnonymousType `, o cambia al registro de tipos declarativo con ` QML_ANONYMOUS`.

    Por ejemplo, si tienes un código como

    class AnonymousType : public QObject {
      // ...
    };
    
    qmlRegisterType<AnonymousType>();

    puedes reescribirlo como

    class AnonymousType : public QObject {
      // ...
    };
    
    qmlRegisterAnonymousType<AnonymousType>("MyModule", 1);

    O, como alternativa,

    class AnonymousType : public QObject {
        QML_ANONYMOUS
        // ...
    };
  • Se han eliminado las sobrecargas de qmlRegisterExtendedType y qmlRegisterInterface que no admiten ningún argumento de versión. Utiliza las sobrecargas que proporcionan una versión o cambia al registro declarativo de tipos con QML_EXTENDED y QML_INTERFACE.

    Por ejemplo, si tienes un código como

    struct GreetInterface
    {
       virtual ~GreetInterface();
       virtual void greet();
    };
    Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
    
    qmlRegisterInterface<GreetInterface>("Greeter");

    puedes reescribirlo como

    struct GreetInterface
    {
       virtual ~GreetInterface();
       virtual void greet();
    };
    Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
    
    qmlRegisterInterface<GreetInterface>("Greeter", 1);

    Como alternativa

    struct GreetInterface
    {
       QML_INTERFACE(Greeter)
       virtual ~GreetInterface();
       virtual void greet();
    };
    Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")

    Nota: En el código nuevo, se debe dar preferencia al registro declarativo de tipos.

  • Se ha eliminado la función QJSValue::engine. Si se necesita acceder al motor, se debe almacenar una referencia al mismo.
  • qmlAttachedPropertiesObjectById y qmlAttachedPropertiesObject(int *, const QObject *, const QMetaObject *, bool) se han eliminado. Utilice en su lugar la sobrecarga qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) de qmlAttachedPropertiesObject.
  • QJSEngine::installTranslatorFunctions se ha eliminado. QJSEngine::installExtensions está disponible como sustituto.

    Por ejemplo, si tienes un código como

    QJSEngine engine;
    engine.installTranslatorFunctions();

    puedes reescribirlo como

    QJSEngine engine;
    engine.installExtensions(QJSEngine::TranslationExtension);

Véase también «Modernización demódulos QML » y «Portar módulos QML a CMake».

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