En esta página

Cambios en Qt Quick

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 en un esfuerzo por convertir a Qt en un marco de trabajo mejor.

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

Cambios en Qt Quick Tipos QML

Tipo modificado de `font.weight`

El tipo de ` font.weight ` se ha cambiado a ` int`. Las clases de peso predefinidas siguen existiendo, pero ahora es posible utilizar números enteros arbitrarios para seleccionar fuentes que no se correspondan con ninguna de estas clases de peso. Esto garantiza la paridad con la API de C++, donde siempre ha sido posible expresar el peso de la fuente como un número entero arbitrario.

La mayor parte del código no se verá afectado por este cambio, salvo en los casos en los que se utilizara una conversión implícita de una cadena a un valor de enumeración.

font.weight: "Bold"

Este código ya no se interpretará correctamente y deberá sustituirse por su valor de enumeración equivalente, tal y como se muestra a continuación.

font.weight: Font.Bold

«FontLoader.name» es ahora una propiedad de solo lectura

En Qt 5, la propiedad « name » de « FontLoader » era modificable y, al establecerla, anulaba la propiedad «source» del elemento. Esto generaba cierta confusión en cuanto a su finalidad y podía provocar un comportamiento indeterminado si se producía una condición de carrera entre los setters de las propiedades en conflicto.

Esto significa que un código como el siguiente ya no funcionará.

FontLoader {
    id: fontLoader
    name: "Helvetica"
}

Text {
    font.family: fontLoader.name
    text: "Foobar"
}

En su lugar, utiliza una propiedad personalizada para almacenar los nombres de las familias de fuentes.

property string fontName: "Helvetica"

Text {
    font.family: fontName
    text: "Foobar"
}

Se ha eliminado el tipo QML OpenGLInfo

En Qt 5.8, OpenGLInfo quedó obsoleto y se ha eliminado en Qt 6. Utiliza en su lugar GraphicsInfo.

ShaderEffect ya no admite cadenas de shader GLSL en línea

Al igual que con custom materials, los efectos ya no se especifican en forma de cadenas de shader GLSL. En su lugar, se espera que los shaders sean preprocesados por las herramientas del módulo Qt « Shader Tools », como la herramienta de línea de comandos « qsb », lo que garantiza que los recursos de shader sean utilizables independientemente de la API gráfica (Vulkan, Metal, OpenGL o Direct 3D) que se utilice en tiempo de ejecución. Se espera que los elementos « ShaderEffect » hagan referencia a los archivos « .qsb » resultantes.

Las propiedades de origen de ShaderEffect son ahora URL

Las propiedades de ShaderEffect vertexShader y fragmentShader tienen ahora un tipo QUrl, en lugar de QByteArray. Por lo tanto, su comportamiento es idéntico al de otras propiedades similares, como Image.source. El código existente que hace referencia a archivos mediante los esquemas file o qrc seguirá funcionando tal cual. Además, este cambio permite hacer referencia a archivos con una ruta relativa a la ubicación del componente (el archivo .qml). Por lo tanto, ahora es opcional especificar el esquema file:.

Cambios en las API de C++ de « Qt Quick »

Cambios en la función `geometryChanged()` de `QQuickItem`

QQuickItemLa función geometryChanged() ha pasado a llamarse geometryChange().

Cambios en las API de QQuick*

  • Las aplicaciones que deseen integrar su propio conjunto de comandos de renderizado de Vulkan, Metal o Direct3D deben tener en cuenta las nuevas señales « QQuickWindow », además de « QQuickWindow::beforeRendering()» y «afterRendering()». El patrón existente en Qt 5 de conectarse únicamente a «just beforeRendering» o «afterRendering» a menudo ya no es suficiente por sí solo, y probablemente será necesario complementarlo conectándose a señales adicionales, como « beforeRenderPassRecording()» o « afterRenderPassRecording()».
  • Las aplicaciones que dependen de las señales « QQuickWindow::beforeRendering » () o «afterRendering()» para emitir su propio conjunto de comandos de renderizado de OpenGL deben llamar a « QQuickWindow::beginExternalCommands » () antes y a « QQuickWindow::endExternalCommands » () después de las llamadas a OpenGL. Esto garantiza que los cambios de estado realizados por el código de la aplicación no provoquen confusión con respecto al estado almacenado en caché del propio renderizador del grafo de escena. Sin embargo, hay que tener en cuenta que, al igual que en Qt 5, modificar el estado de OpenGL 3.x o 4.x que no sea utilizado por el renderizador Qt Quick puede seguir provocando problemas inesperados; por lo tanto, se recomienda a las aplicaciones restablecer dicho estado de OpenGL a su valor por defecto antes de salir de las ranuras o lambdas conectadas a estas señales.
  • Las sobrecargas existentes de ` QQuickWindow::setRenderTarget()` y los getter relacionados se han eliminado y sustituido por una nueva función que toma un ` QQuickRenderTarget`. Ahora se espera que las aplicaciones que realicen un renderizado redirigido en combinación con ` QQuickRenderControl ` utilicen esta nueva función para especificar el destino de renderizado de una manera que no esté vinculada a OpenGL.
  • La sobrecarga de QQuickWindow::setSceneGraphBackend() que toma un argumento de tipo ` QSGRendererInterface::GraphicsApi ` ha pasado a denominarse setGraphicsApi().
  • Las funciones de QQuickWindow setPersistentOpenGLContext e isPersistentOpenGLContext han cambiado de nombre y ahora se denominan QQuickWindow::setPersistentGraphics() y QQuickWindow::isPersistentGraphics().
  • Las funciones setClearBeforeRendering() y clearBeforeRendering() se han eliminado de QQuickWindow. En Qt 6 no existe la opción de omitir el borrado del búfer de color. En Qt 5, a menudo era necesario llamar a setClearBeforeRendering() en combinación con underlays, para evitar que Qt Quick borrara el contenido renderizado en el búfer de color. En Qt 6, existe un enfoque más robusto: conectarse a la señal « beforeRenderPassRecording() », que se emite tras el borrado, pero antes de renderizar el contenido de « Qt Quick ».
  • Se ha eliminado la función QQuickWindow::openglContext(). Cuando la aplicación se ha asegurado de que el grafo de escena utiliza OpenGL para el renderizado, puede consultar QOpenGLContext desde QSGRendererInterface::getResource().
  • Se ha eliminado la señal QQuickWindow::openglContextCreated().
  • Se ha eliminado la función obsoleta QQuickWindow::createTextureFromId(). En su lugar, utilice la función fromNative() de QPlatformInterface::QSGOpenGLTexture, QPlatformInterface::QSGVulkanTexture, QPlatformInterface::QSGD3D11Texture o QPlatformInterface::QSGMetalTexture.
  • La clase ` QQuickFramebufferObject ` está disponible con una API sin cambios, pero solo funciona cuando el grafo de escena se renderiza con OpenGL. No funcionará si se utiliza otra API gráfica, como Vulkan o Metal. Las aplicaciones que dependan de ` QQuickFramebufferObject ` deben forzar el uso de OpenGL llamando a ` QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL) ` en su función `main()`.
  • QQuickRenderControl tiene una API ligeramente modificada: se ha eliminado `grab()`; en su lugar, utilice ` QQuickWindow::grabWindow()`, cuando sea aplicable. La función `initialize()` ya no admite un ` QOpenGLContext`. Ahora las aplicaciones también deben llamar a ` QQuickRenderControl::beginFrame()` y ` QQuickRenderControl::endFrame()` según corresponda. Cuando se desee realizar un muestreo múltiple, se debe llamar a la nueva función ` QQuickRenderControl::setSamples()` para indicar el número de muestras.
  • Las aplicaciones que deseen realizar un renderizado Qt Quick en combinación con un dispositivo gráfico nativo u objeto de contexto ya existente deben utilizar la nueva función QQuickWindow::setGraphicsDevice(), ya que QQuickRenderControl ya no proporciona la función initialize(QOpenGLContext*).
  • Establecer QQuickPaintedItem y Context2D en el modo Framebuffer no tiene ningún efecto. Se comportará como si el modo estuviera establecido en el modo Image predeterminado.
  • La variable de entorno QSG_NO_DEPTH_BUFFER sigue siendo compatible en Qt 6.0, pero se recomienda sustituir su uso por la llamada a setDepthBufferFor2D() sobre un QQuickGraphicsConfiguration que, a continuación, se asocie con QQuickWindow.

Cambios en las API de QSG*

  • QSGMaterialShader ha cambiado su interfaz. Las implementaciones ya no deben basarse en OpenGL y no pueden dar por sentado que funciones como `updateState()` —ahora eliminada— se llamen con un ` QOpenGLContext ` activo. En la nueva interfaz orientada a datos, `updateState()` se sustituye por ` updateUniformData()`, ` updateSampledImage()` y ` updateGraphicsPipelineState()`. En lugar de proporcionar el código de los sombreadores GLSL como cadenas de caracteres, ahora se espera que los sombreadores sean preprocesados por las herramientas del módulo Qt Shader Tools, como la herramienta de línea de comandos qsb, lo que garantiza que los recursos de los sombreadores sean utilizables independientemente de la API gráfica (Vulkan, Metal, OpenGL o Direct 3D) que se utilice en tiempo de ejecución.
  • Se ha eliminado QSGEngine. En el improbable caso de que una aplicación utilice esta clase, se recomienda migrar al uso de QQuickRenderControl en su lugar.
  • QSGAbstractRenderer ya no es pública. El uso de esta clase solo tenía sentido en combinación con QSGEngine y, al haberse eliminado dicha clase, QSGAbstractRenderer ha vuelto a ser privada.
  • Se ha eliminado la clase de conveniencia QSGSimpleMaterial. Se espera que las aplicaciones utilicen en su lugar las API revisadas de ` QSGMaterial `, independientes de OpenGL.
  • Para acceder al objeto de textura nativo subyacente de un ` QSGTexture`, la función `textureId()` ya no está disponible. En su lugar, utilice QSGTexture::platformInterface() con QPlatformInterface::QSGOpenGLTexture, QPlatformInterface::QSGVulkanTexture, QPlatformInterface::QSGD3D11Texture o QPlatformInterface::QSGMetalTexture.
  • Ahora es necesario que las subclases de ` QSGImageNode ` sobrescriban nuevas funciones virtuales adicionales, como `setAnisotropyLevel()` y `anisotropyLevel()`.
  • Es probable que sea necesario rediseñar las subclases de ` QSGTexture `. Algunas de las funciones virtuales específicas de OpenGL, como `bind()` o `updateBindOptions()`, ya no están presentes, mientras que hay nuevas funciones virtuales cuya implementación es obligatoria, como ` comparisonKey()`.

Cambios en el uso de OpenGL en Qt Quick

Aunque esto no supondrá ningún problema para muchas aplicaciones, los desarrolladores deben tener en cuenta que OpenGL ya no es siempre la opción predeterminada para el renderizado de « Qt Quick » en Qt 6. A menos que se utilice el backend « software », una aplicación « Qt Quick » podría utilizar OpenGL, Vulkan, Metal o Direct3D 11 en tiempo de ejecución. Cuando no se realiza ninguna solicitud explícita, ya sea a través de la variable de entorno QSG_RHI_BACKEND o de la función QQuickWindow::setSceneGraphBackend(), se elige un valor por defecto específico de la plataforma mediante Qt Quick.

Para obtener más información, visita las páginas «Qt Quick » (Grafo de escena ) y «Qt Quick » (Renderizador predeterminado del grafo de escena ).

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