Cambios en los controles de « Qt Quick »
Qt 6 es el resultado de un esfuerzo deliberado por hacer que el marco sea más eficiente y fácil de usar.
Intentamos mantener la compatibilidad con todas las API públicas en cada versión. Algunos cambios eran inevitables en nuestro esfuerzo por hacer de Qt un marco de trabajo mejor.
En este tema resumimos esos cambios en los controles de Qt Quick y ofrecemos orientación para gestionarlos.
Migración desde los controles « Qt Quick » 1
Qt Quick «Controls 1» quedó obsoleto en Qt 5.11 y se ha eliminado de Qt 6.0. Utilice en su lugar « Qt Quick Controls» (anteriormente conocido como « Qt Quick Controls 2»). Para obtener más información, consulte el tema «Qt 5.15: Comparación entre « Qt Quick Controls» y « Qt Quick Controls 1»» en la documentación de Qt 5.
Cambios en el registro de tipos
Qt Quick Los controles han experimentado algunos cambios importantes, en su mayoría internos, en Qt 6. Al aprovechar el registro de tipos mejorado introducido en Qt 5.15, allanamos el camino para la compilación de los archivos QML del módulo a C++ y permitimos que las herramientas sean más eficaces. En concreto, el modelo de código QML de Qt Creator debería ofrecer una visión más completa de los tipos, lo que hace que su función de autocompletado y la comprobación de errores del código de los controles de Qt Quick sean más fiables. Las herramientas de análisis estático, como qmllint y qmlformat, también se benefician al poder detectar los tipos que ahora se declaran en tiempo de compilación en C++.
Como resultado de estos cambios, algunas cosas se hacen de forma ligeramente diferente.
Los estilos personalizados son ahora módulos QML propiamente dichos
Para permitir el registro de tipos en tiempo de compilación, cada estilo de « Qt Quick » es ahora un módulo QML propiamente dicho. Anteriormente, bastaba con un único « Button.qml » para crear tu propio estilo. Aunque resultaba cómodo, esto requería una API no estándar, lo que a su vez exigía una adaptación en herramientas como Qt Designer.
Ahora, todos los tipos QML que implementa un estilo deben declararse en el archivo qmldir de dicho estilo:
module MyStyle
Button 1.0 Button.qmlAl unificar esto con el resto del entorno QML, los estilos resultan más familiares para los desarrolladores y, con suerte, más fáciles de entender para los principiantes. Como consecuencia, ha sido necesario eliminar la siguiente API:
- QQuickStyle::addStylePath()
- QQuickStyle::availableStyles()
- QQuickStyle::path()
- QQuickStyle::stylePathList()
- QT_QUICK_CONTROLS_STYLE_PATH
Ahora que los estilos deben encontrarse en la ruta de importación del motor QML, al igual que cualquier otro módulo QML, ya no es necesario ni posible dar soporte a esta API.
Nombres de estilos
Además, ahora solo hay una forma válida, que distingue entre mayúsculas y minúsculas, para los nombres de estilos: «Material», «MyStyle», etc. Es decir: el nombre del estilo debe coincidir exactamente con el nombre del módulo QML. Esto también se aplica a los selectores de archivos, donde antes todos los nombres de estilos estaban en minúsculas. Por ejemplo, mientras que lo siguiente era una estructura válida para un proyecto de Qt 5:
MyProject
├── main.qml
├── HomePage.qml
└── +material
└───HomePage.qmlEn Qt 6, +material pasa a ser +Material:
MyProject
├── main.qml
├── HomePage.qml
└── +Material
└───HomePage.qmlTodas las formas existentes de ejecutar una aplicación con un estilo específico siguen siendo compatibles.
Selección de estilos en tiempo de ejecución y de compilación
La importación de un estilo tiene ahora un significado adicional debido a la forma en que funcionan internamente las importaciones. Anteriormente, al importar QtQuick.Controls se registraban los tipos de control del estilo actual en el motor QML:
import QtQuick.ControlsA esto lo denominamos «selección de estilo en tiempo de ejecución», ya que el estilo se selecciona en tiempo de ejecución.
Al importar explícitamente QtQuick.Controls.Material, simplemente se exponían las API adicionales que proporcionaba ese estilo (por ejemplo, el tipo Material adjunto):
import QtQuick.Controls.MaterialAhora, al importar explícitamente un estilo se hacen ambas cosas.
Esto significa, en la práctica, que se utilizarán los tipos de control (como Button) del último estilo importado. A esto lo denominamos «selección de estilo en tiempo de compilación».
Esto tiene implicaciones para el código existente. Concretamente, si tu aplicación admite más de un estilo, traslada estas importaciones a sus propios archivos QML seleccionados por archivo.
Por ejemplo, si tienes el siguiente archivo « main.qml »:
import QtQuick.Controls
import QtQuick.Controls.Material
import QtQuick.Controls.Universal
ApplicationWindow {
width: 600
height: 400
visible: true
Material.theme: darkMode ? Material.Dark : Material.Light
Universal.theme: darkMode ? Universal.Dark : Universal.Light
// Child items, etc.
}Puedes trasladar el código común a un componente «base»:
// MainWindow.qml
import QtQuick.Controls
ApplicationWindow {}A continuación, añade un subdirectorio « +Material » y, en él, añade el código específico de Material a « MainWindow.qml »:
// +Material/MainWindow.qml
import QtQuick.Controls.Material
ApplicationWindow {
Material.theme: darkMode ? Material.Dark : Material.Light
}Haz lo mismo para Universal:
// +Universal/MainWindow.qml
import QtQuick.Controls.Universal
ApplicationWindow {
Universal.theme: darkMode ? Universal.Dark : Universal.Light
}A continuación, en ` main.qml`:
import QtQuick.Controls
MainWindow {
width: 600
height: 400
visible: true
// Child items, etc.
}Véase también: Uso de selectores de archivos con los controles de Qt Quick .
Estilo predeterminado
El estilo predeterminado ha pasado a llamarse «Basic», ya que ya no es el estilo predeterminado. En su lugar, el estilo predeterminado se elige ahora en función de la plataforma para la que se haya compilado Qt:
- Android: Estilo Material
- Linux: estilo «Fusion»
- macOS: Estilo macOS
- Windows: Estilo Windows
- Todas las demás plataformas: estilo «Básico»
Por lo tanto, las aplicaciones que no especificaran un estilo en Qt 5 y tuvieran controles personalizados deben especificar explícitamente el estilo «Básico» en Qt 6 para garantizar que dichos controles tengan el mismo aspecto y se comporten igual que en Qt 5.
Paleta
La API de la paleta se ha trasladado a QQuickItem. Las distintas API que utilizan paletas en Qt Quick Controls no han sufrido cambios.
Controles
Cambios en ApplicationWindow
Se han eliminado las propiedades de superposición obsoletas y la API «attached». Utiliza en su lugar el tipo « Overlay ».
Cambios en ComboBox
La propiedad « pressed » es ahora de solo lectura. Para modificar el estado visual de pulsación de un ComboBox, utilice en su lugar la propiedad « down ».
Cambios en «Container»
Se ha eliminado la función obsoleta ` removeItem(var) `. En su lugar, se puede utilizar ` removeItem` (`Item`) o ` takeItem` (`int`).
Cambios en el cuadro de diálogo
DialogLas señales « accepted »() y « rejected »() del «Dialog» ahora se emiten antes que « closed »() al llamar a « done »(), « accept »() y « reject »().
Cambios en el menú
Se ha eliminado la función obsoleta removeItem(var). En su lugar, se pueden utilizar removeItem(Item) o takeItem(int).
Cambios en ToolTip
ToolTipEl tiempo de espera de las descripciones emergentes ahora solo comienza una vez que se ha emitido opened(). Esto hace que las descripciones emergentes con transiciones de entrada permanezcan visibles durante todo el tiempo que dure la propiedad de tiempo de espera. Esto significa que permanecen visibles un poco más de tiempo que antes, por lo que puede merecer la pena revisar visualmente las descripciones emergentes de tu aplicación y ajustar los tiempos de espera si es necesario.
Cambios en StackView
El valor de la enumeración ` StackView.Transition` ha quedado obsoleto. Se puede omitir el argumento `operation` para utilizar la transición predeterminada en cualquier operación dada.
Cambios en Tumbler
implicitWidth y « implicitHeight » ahora deben especificarse para « contentItem » de « Tumbler », lo que lo hace coherente con el resto de controles.
© 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.