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,qmlContextyqmlEnginesolí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 nombresQtQml. 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
qmlRegisterExtendedTypeyqmlRegisterInterfaceque 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. qmlAttachedPropertiesObjectByIdyqmlAttachedPropertiesObject(int *, const QObject *, const QMetaObject *, bool)se han eliminado. Utilice en su lugar la sobrecargaqmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool)deqmlAttachedPropertiesObject.QJSEngine::installTranslatorFunctionsse ha eliminado.QJSEngine::installExtensionsestá disponible como sustituto.Por ejemplo, si tienes un código como
QJSEngine engine; engine.installTranslatorFunctions();puedes reescribirlo como
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.