En esta página

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

Al 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.qml

En Qt 6, +material pasa a ser +Material:

MyProject
├── main.qml
├── HomePage.qml
└── +Material
    └───HomePage.qml

Todas 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.Controls

A 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.Material

Ahora, 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:

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.