对Qt Quick Controls

Qt 6 的变更，是出于让该框架更高效、更易于使用的有意识努力。

我们致力于在每个版本中保持所有公开 API 的兼容性。为了使 Qt 成为更好的框架，某些变更在所难免。

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

从Qt Quick Controls 1 迁移

Qt Quick Controls 1 已在 Qt 5.11 中被废弃，并从 Qt 6.0 中移除。请改用Qt Quick Controls （此前称为Qt Quick Controls 2）。有关更多信息，请参阅Qt5 文档中的“Qt 5.15：Qt Quick Controls 与Qt Quick Controls 1”主题。

类型注册变更

Qt Quick Controls 在 Qt 6 中经历了一些重大变更，其中大部分为内部变更。通过利用 Qt 5.15 中引入的改进型类型注册机制，我们为将该模块的 QML 文件编译为 C++ 铺平了道路，并使开发工具能够更高效地工作。 特别是，Qt Creator 的 QML 代码模型应能更全面地掌握类型信息，从而使其对Qt Quick Controls 代码的代码补全和错误检查更加可靠。qmllint 和 qmlformat 等静态分析工具也因此受益，因为它们能够识别现在在 C++ 编译时声明的类型。

由于这些变更，某些操作的方式略有不同。

自定义样式现已成为标准的 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

现在，显式导入样式会同时实现这两点。

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

这会对现有代码产生影响。具体来说，如果您的应用程序支持多种样式，请将这些导入语句移至各自的、经过文件选择的 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.
}

你可以将通用代码移入一个“base”组件中：

// 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 组件，也采用同样的做法：

// +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 中使用文件选择器。

默认样式

“Default”样式已更名为“Basic”，因为它不再是默认样式。取而代之的是，默认样式现在根据 Qt 的构建平台进行选择：

• Android：Material样式
• Linux：Fusion 样式
• macOS：macOS 样式
• Windows：Windows 样式
• 所有其他平台：Basic 样式

因此，在 Qt 5 中未指定样式且包含自定义控件的应用程序，应在 Qt 6 中明确指定“基本”样式，以确保这些控件的外观和行为与 Qt 5 中的表现一致。

调色板

调色板 API 已移至QQuickItem 。Qt Quick Controls 中使用调色板的各种 API 保持不变。

控件

ApplicationWindow 的变更

已移除了已弃用的 overlay 属性及 attached API。请改用Overlay 中的 attached 类型。

ComboBox 的更改

pressed 属性现为只读。若要修改ComboBox 的视觉按压状态，请改用down 属性。

Container 的更改

已废弃的removeItem(var) 函数已被移除。可改用removeItem （Item）或takeItem （int）。

Dialog 的更改

Dialog在调用 `done()`、`accept()` 和 `reject()` 时，`accepted()` 和 `rejected()` 信号现在会在 `closed()` 之前发出。

菜单变更

已移除了已弃用的removeItem(var) 函数。可改用removeItem(Item) 或takeItem(int) 代替。

ToolTip 的更改

ToolTip的超时现在仅在发出opened() 之后才开始计算。这会导致采用“进入”过渡效果的工具提示在超时属性设定的整个时长内保持可见。这意味着它们的显示时间比以前略长，因此建议您在应用程序中目视检查工具提示，并在必要时调整超时时间。

StackView 的更改

StackView.Transition 枚举值已被废弃。现在可以省略 operation 参数，以便对任何给定操作使用默认过渡效果。

Tumbler 的变更

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