变更内容Qt Quick

Qt 6 的变更，源于我们有意识地致力于提升该框架的效率并使其更易于使用。

我们力求在每个版本中保持所有公开 API 的二进制和源代码兼容性。但在努力使 Qt 成为更优秀的框架的过程中，某些变更在所难免。

在本主题中，我们将总结Qt Quick 中的这些变更，并提供相应的处理指南。

Qt Quick 中的变更QML 类型

font.weight 类型的变更

font.weight 的类型已更改为int 。预定义的字重类别仍然存在，但现在可以使用任意整数来选择不属于这些字重类别的字体。这确保了与 C++ API 的一致性——在 C++ API 中，一直可以使用任意整数来表示字体字重。

除使用了字符串到枚举值的隐式转换的情况外，大多数代码不会受到此变更的影响。

font.weight: "Bold"

此类代码将无法正确解析，必须替换为等效的枚举值，如下所示。

font.weight: Font.Bold

FontLoader.name 现已成为只读属性

在 Qt 5 中，FontLoader 的name 属性是可写的，设置时会覆盖该项的源属性。这导致对其用途产生了一些混淆，并且如果冲突属性的设置器之间存在竞争条件，可能会引发不可预测的行为。

这意味着如下所示的代码将不再有效。

FontLoader {
    id: fontLoader
    name: "Helvetica"
}

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

取而代之，请使用自定义属性来存储字体家族名称。

property string fontName: "Helvetica"

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

已移除 OpenGLInfo QML 类型

在 Qt 5.8 中，OpenGLInfo 已被标记为弃用，并在 Qt 6 中移除。请改用GraphicsInfo 代替。

ShaderEffect 不再支持内联 GLSL 着色器字符串

与custom materials 一样，效果不再以 GLSL 着色器字符串的形式指定。 取而代之的是，着色器应由QtShader Tools模块中的工具（例如qsb 命令行工具）进行预处理，从而确保无论运行时使用哪种图形 API（Vulkan、Metal、OpenGL 或 Direct 3D），着色器资源均可正常使用。ShaderEffect 项应引用生成的.qsb 文件。

ShaderEffect 源属性现为 URL

ShaderEffect 的属性vertexShader 和fragmentShader 现均采用QUrl 类型，而非QByteArray 。因此，其行为与其他类似属性（如Image.source ）完全一致。现有通过file 或qrc 方案引用文件的代码将保持原样继续运行。此外，此变更允许使用相对于组件（即.qml文件）位置的相对路径来引用文件。 因此，指定file: 方案现在是可选的。

Qt Quick C++ API 的变更

QQuickItem 的更改

QQuickItem的 geometryChanged() 函数已重命名为geometryChange()。

QQuick* API 的变更

• 希望集成自己的一套 Vulkan、Metal 或 Direct3D 渲染命令的应用程序，除了QQuickWindow::beforeRendering() 和 afterRendering() 之外，还应注意新的QQuickWindow 信号。 Qt 5 中仅连接 to just beforeRendering 或 afterRendering 的现有模式通常已不再足够，可能需要通过连接其他信号（如beforeRenderPassRecording() 或afterRenderPassRecording()）来补充。
• 依赖于QQuickWindow::beforeRendering() 或 afterRendering() 信号来发出自身 OpenGL 渲染命令的应用程序，应在 OpenGL 调用之前调用QQuickWindow::beginExternalCommands()，并在调用之后调用QQuickWindow::endExternalCommands()。这可确保应用程序代码所做的状态更改不会与场景图渲染器自身的缓存状态产生冲突。 但请注意，与 Qt 5 一样，修改Qt Quick 渲染器未使用的 OpenGL 3.x 或 4.x 状态仍可能导致意外问题，因此建议应用程序在从与这些信号关联的槽或 lambda 表达式返回之前，将此类 OpenGL 状态重置为默认值。
• 现有的QQuickWindow::setRenderTarget()重载及其相关的获取器已被移除，并由一个接受QQuickRenderTarget 参数的新函数取代。进行重定向渲染并结合QQuickRenderControl 使用的应用程序，现在应使用此新函数以不依赖于OpenGL的方式指定渲染目标。
• 接受QSGRendererInterface::GraphicsApi 参数的QQuickWindow::setSceneGraphBackend() 重载已重命名为setGraphicsApi()。
• QQuickWindow 中的 setPersistentOpenGLContext 和 isPersistentOpenGLContext 函数已重命名，现分别为QQuickWindow::setPersistentGraphics() 和QQuickWindow::isPersistentGraphics()。
• QQuickWindow 中已移除了 setClearBeforeRendering() 和 clearBeforeRendering()。在 Qt 6 中，不存在跳过颜色缓冲区清空的选项。在 Qt 5 中，为防止Qt Quick 清空渲染到颜色缓冲区中的内容，通常需要结合底层图像调用 setClearBeforeRendering()。 在 Qt 6 中，有一种更稳健的方法：订阅 `beforeRenderPassRecording() ` 信号，该信号在清除操作完成后、但渲染Qt Quick 的内容之前发出。
• 已移除了 QQuickWindow::openglContext() 函数。当应用程序确保场景图使用 OpenGL 进行渲染后，可通过QSGRendererInterface::getResource() 查询QOpenGLContext 。
• 已移除 QQuickWindow::openglContextCreated() 信号。
• 已移除已弃用的 QQuickWindow::createTextureFromId() 函数。 请改用 QPlatformInterface::QSGOpenGLTexture、QPlatformInterface::QSGVulkanTexture、QPlatformInterface::QSGD3D11Texture 或 QPlatformInterface::QSGMetalTexture 中的 fromNative() 函数。
• QQuickFramebufferObject 类的API保持不变，但仅在场景图使用OpenGL渲染时才有效。使用其他图形API（如Vulkan或Metal）时，该类将无法正常工作。依赖QQuickFramebufferObject 的应用程序应在main()函数中调用QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL) ，以强制使用OpenGL。
• QQuickRenderControl API 略有变更：`grab()` 已被移除，在适用情况下请改用 `QQuickWindow::grabWindow()`。`initialize()` 函数不再接受 `QOpenGLContext` 参数。应用程序现在还需根据实际情况调用 `QQuickRenderControl::beginFrame()` 和 `QQuickRenderControl::endFrame()`。若需进行多采样，必须调用新函数 `QQuickRenderControl::setSamples()` 以指定采样次数。
• 希望结合现有的本机图形设备或上下文对象执行Qt Quick 渲染的应用程序，必须使用新的QQuickWindow::setGraphicsDevice() 函数，因为QQuickRenderControl 不再提供initialize(QOpenGLContext*) 函数。
• 将QQuickPaintedItem 和Context2D 设置为Framebuffer 模式将不会产生任何效果。其行为将与模式设置为默认的 Image 模式时相同。
• Qt 6.0 仍支持环境变量QSG_NO_DEPTH_BUFFER ，但建议将其用法替换为：在QQuickGraphicsConfiguration 上调用setDepthBufferFor2D()，然后将该 与QQuickWindow 关联。

QSG* API 的变更

• QSGMaterialShader 接口已发生变更。实现不应再依赖 OpenGL，且不能假设诸如现已移除的 updateState() 等函数会以QOpenGLContext 对象作为参数被调用。在新的、以数据为导向的接口中，updateState() 已被updateUniformData()、updateSampledImage() 和updateGraphicsPipelineState() 所取代。 着色器不再以字符串形式提供 GLSL 着色器代码，而是需要由 QtShader Tools 模块中的工具（例如qsb 命令行工具）进行预处理，从而确保无论运行时使用哪种图形 API（Vulkan、Metal、OpenGL 或 Direct 3D），着色器资源均可正常使用。
• 已移除 QSGEngine。若应用程序（尽管可能性极低）仍在使用该类，建议改用QQuickRenderControl 进行移植。
• QSGAbstractRenderer 不再为公共类。该类的用法仅在与 QSGEngine 结合使用时才有意义，鉴于该类已被移除，QSGAbstractRenderer 已恢复为私有类。
• 已移除 QSGSimpleMaterial 便利类。建议应用程序改用经过修订的、与 OpenGL 无关的QSGMaterial API。
• 若要访问QSGTexture 的底层原生纹理对象，textureId() 方法已不可用。 取而代之，请使用 QSGTexture::platformInterface() 并配合 QPlatformInterface::QSGOpenGLTexture、QPlatformInterface::QSGVulkanTexture、QPlatformInterface::QSGD3D11Texture 或 QPlatformInterface::QSGMetalTexture。
• QSGImageNode 的子类现在必须重写新的附加虚函数，例如 setAnisotropyLevel() 和 anisotropyLevel()。
• QSGTexture 的子类很可能需要重新设计。一些 OpenGL 特有的虚拟函数（例如 bind() 或 updateBindOptions()）已不复存在，而一些新的虚拟函数（例如comparisonKey()）则必须实现。

OpenGL 使用方面的变更Qt Quick

尽管这对许多应用程序不会造成兼容性问题，但应用程序开发人员应注意：在 Qt 6 中，OpenGL 已不再是Qt Quick 渲染的默认选择。除非使用software 后端，否则Qt Quick 应用程序在运行时可能会使用 OpenGL、Vulkan、Metal 或 Direct3D 11。 如果未通过QSG_RHI_BACKEND 环境变量或QQuickWindow::setSceneGraphBackend()函数进行显式请求，Qt Quick 将选择平台特有的默认渲染器。

如需了解更多信息，请访问Qt Quick 场景图和Qt Quick 场景图默认渲染器页面。