Qt Quick 控件变更

Qt 6 致力于使框架更加高效和易于使用。

我们试图在每个版本中保持所有公共 API 的兼容性。为了使 Qt 成为更好的框架，一些变更在所难免。

在本主题中，我们总结了 Qt Quick 控件中的这些变更，并提供了解决这些变更的指南。

从 Qt Quick Controls 1 迁移

Qt Quick Controls 1 在 Qt 5.11 中已被弃用，并在 Qt 6.0 中被移除。请使用 Qt Quick Controls（以前称为 Qt Quick Controls 2）。有关更多信息，请参阅 Qt 5 文档中的Qt 5.15: Qt Quick Controls 与 Qt Quick Controls 1 的比较部分。

类型注册变更

Qt Quick Controls 在 Qt 6 中经历了一些重大更改，大部分是内部更改。通过利用 Qt 5.15 中引入的类型注册改进，我们为编译该模块的 QML 文件铺平道路，并使工具更加有效。特别是，Qt Creator 的 QML 代码模型应该对类型有一个更全面的了解，使其对 Qt Quick Controls 代码的补全和错误检查更加可靠。像 qmllint 和 qmlformat 这样的静态分析工具也从现在可以在编译时声明类型意识中受益。

因此，一些事情的处理方式略有不同。

自定义样式现在是正确的 QML 模块

为了启用编译时类型注册，每个 Qt Quick Controls 风格现在是一个正确的 QML 模块。以前，一个单独的 Button.qml 就足够创建您自己的样式。虽然方便，但这需要一些非标准 API，进而需要像 Qt Designer 这样的工具进行适应性修改。

现在，所有实现于样式中的 QML 类型都必须在其 qmldir 文件中声明

module MyStyle
Button 1.0 Button.qml

通过与 QML 世界的其余部分统一，样式对开发者来说更为熟悉，也许对于初学者来说更容易理解。因此，以下 API 必须删除：

QQuickStyle::addStylePath()
QQuickStyle::availableStyles()
QQuickStyle::path()
QQuickStyle::stylePathList()
QT_QUICK_CONTROLS_STYLE_PATH

由于风格现在必须像任何其他 QML 模块一样出现在 QML 引擎的导入路径中，因此不再需要或可能支持此 API。

样式名称

此外，现在只有一个有效、区分大小写的样式名称形式：“Material”、“MyStyle”等。也就是说，样式名称必须与 QML 模块名称完全匹配。这也适用于文件选择器，以前，所有样式名称都是小写。例如，以下结构对于 Qt 5 项目是有效的：

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

在 Qt 6 中，+material 变为 +Material

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

现有的所有运行具有特定样式的应用程序的方式仍然受支持。

运行时和编译时样式选择

由于导入方式的内部原因，现在导入样式有额外含义。之前，导入 QtQuick.Controls 将注册当前样式的控件类型到 QML 引擎

import QtQuick.Controls

我们称之为运行时样式选择，因为样式是在运行时选择的。

显式导入 QtQuick.Controls.Material 将简单地公开该样式提供的任何额外 API（例如，附加的 Material 类型）

import QtQuick.Controls.Material

现在，显式导入样式会做两件事情。

这意味着将从最后导入的样式使用的控件类型（如按钮）。我们称之为编译时样式选择。

这将影响现有代码。具体来说，如果您的应用程序支持多个样式，请将此类导入移动到自己的 QML 文件中，并选择文件。

例如，如果您有以下 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.
}

您可以将常用代码移动到“基础”组件中

// MainWindow.qml

import QtQuick.Controls

ApplicationWindow {}

然后，添加一个 +Material 子目录，并在其中添加特定的 Material 代码到 MainWindow.qml

// +Material/MainWindow.qml

import QtQuick.Controls.Material

ApplicationWindow {
    Material.theme: darkMode ? Material.Dark : Material.Light
}

对通用型号做同样的事情

// +Universal/MainWindow.qml

import QtQuick.Controls.Universal

ApplicationWindow {
    Universal.theme: darkMode ? Universal.Dark : Universal.Light
}

然后，在 main.qml

import QtQuick.Controls

MainWindow {
    width: 600
    height: 400
    visible: true

    // Child items, etc.
}

另请参阅：与 Qt Quick Controls 一起使用文件选择器。

默认样式

默认样式已被重命名为“基本”，因为它不再是默认样式。相反，现在根据 Qt 构建的平台选择默认样式

Android：Material 样式
Linux：Fusion 样式
macOS：macos 样式
Windows：Windows 样式
所有其他平台：基本样式

因此，未在 Qt 5 中指定样式且已自定义控件的应用程序应在 Qt 6 中显式指定基本样式，以确保这些控件的外观和行为与 Qt 5 时相同。

调色板

调色板 API 已移动到 QQuickItem。Qt Quick Controls 中使用调色板的各个 API 未经更改。

控件

ApplicationWindow 的更改

已删除过时的覆盖属性和附加 API。请使用 Overlay 附加类型。

ComboBox 的更改

pressed 属性现在是只读的。要修改 ComboBox 的视觉按下状态，请使用 down 属性。

Container 的更改

已删除过时的 removeItem(var) 函数。removeItem(Item) 或 takeItem(int) 可以用。

Dialog 的更改

Dialog 的 accepted() 和 rejected() 信号现在在调用 done()、accept() 和 reject() 之前发出，当调用 closed() 时也是如此。

已弃用的removeItem(var)函数已被删除。可以使用removeItem(Item)或takeItem(int)代替。

ToolTip的计时器现在仅在opened()被触发后开始。这导致带有进入转换的提示框在整个计时器属性持续时间内可见。这意味着它们的可见时间比之前稍长，因此在必要时可能需要检查应用中的提示框并调整计时器。

StackView变动

StackView的 Transition 枚举值已被弃用。可以省略操作参数，以便在给定操作中使用默认转换。

Tumbler变动

implicitWidth和implicitHeight现在必须为Tumbler的contentItem提供，使其与其他所有控件保持一致。