Back to Qt.io
Contact Us Blog Download Qt
本页内容

图标 基本样式

样式Qt Quick Controls

可用样式

Qt Quick Controls 提供多种样式供选择。

基本样式

Basic风格控件图库

“基本样式”是一种简单轻量且用途广泛的样式，可为Qt Quick Controls 提供最佳性能。

Fusion 风格

Fusion 风格浅色主题的控件图库

Fusion 风格的浅色主题。

Fusion 风格深色主题的控件图库

Fusion 风格的深色主题。

“融合”样式是一种与平台无关的样式，为Qt Quick Controls 提供了以桌面为导向的外观和感觉。

Imagine 样式

Imagine 风格的控件图库

“Imagine”风格基于图像资源。该风格自带一组默认图像，只需提供一个遵循预定义命名规范的图像目录，即可轻松更换这些图像。

macOS 样式

macOS 风格浅色主题的控件图库

macOS 样式的浅色主题。

macOS 风格深色主题的控件图库

macOS 风格的深色主题。

macOS 样式是一种具有原生外观的 macOS 样式。

注意：此 样式仅适用于在 macOS 上运行的应用程序。

iOS 风格

iOS 风格浅色主题的控件图库

iOS 风格的浅色主题。

iOS 风格深色主题的控件图库

iOS 风格的深色主题。

iOS 样式是一种基于图像资源、具有 iOS 原生外观的样式。

注意：此 样式仅适用于在 iOS 上运行的应用程序。

Material 风格

Material 风格浅色主题的控件图集

Material 风格的浅色主题。

Material 风格深色主题的控件图库

Material 风格的深色主题。

Material 风格基于Google Material Design 设计指南，提供引人入胜的设计，但比 Basic 风格消耗更多的系统资源。

通用样式

通用风格浅色主题的控件图库

通用风格的浅色主题。

通用风格深色主题的控件图库

通用风格的深色主题。

通用样式基于 Microsoft 通用设计指南，提供了赏心悦目的设计，但比基本样式消耗更多的系统资源。

Windows 样式

Windows 风格的控件图库

“Windows 样式”是一种具有 Windows 原生外观的样式。

注意：此 样式仅适用于在 Windows 上运行的应用程序。

FluentWinUI3 样式

FluentWinUI3 风格浅色主题控件图库

FluentWinUI3 样式的浅色主题。

FluentWinUI3 风格深色主题的控件图库

FluentWinUI3 样式中的深色主题。

FluentWinUI3 样式是一种现代且具有原生外观的样式，专为运行 Windows 11 及以上版本的平台设计，遵循 Fluent UI 和 WinUI 3 设计指南。FluentWinUI3 可在所有受支持的平台上运行。

在Qt Quick Controls

默认样式

如果未显式设置样式，将使用默认样式。具体使用的样式取决于操作系统：

对于所有其他操作系统，将使用“基础风格”。

编译时样式选择

编译时样式选择是一种通过在 QML 中直接或间接导入样式来指定使用样式的做法。由于是在编译时进行的，因此若使用编译时样式选择，则无法在运行时更改样式。

使用编译时样式选择的最便捷方式是导入QtQuick.Controls.Native样式。QtQuick.Controls.Native 会自动导入目标平台的默认样式。若导入QtQuick.Controls.Native ，则不应再导入任何其他特定样式，也不应导入（运行时选择的）QtQuick.Controls 模块。QtQuick.Controls.Native 会为您导入平台默认样式，该样式会自行处理其备用方案。 您不能同时拥有多个顶级样式。例如：

// Refrain from importing QtQuick.Controls or specific styles.
import QtQuick.Controls.Native

ApplicationWindow {
    // ...
}

不过，你也可以在编译时导入一个特定的样式，而忽略平台的默认样式。例如，要导入 Material 样式：

// The style must be imported before any other QtQuick.Controls imports
// in order for run-time style selection API like QQuickStyle::name() to
// work.
import QtQuick.Controls.Material

ApplicationWindow {
    // ...
}

请注意，QtQuick.Controls （负责运行时样式选择）并未被导入。回退样式由该样式的 qmldir 指定：

module QtQuick.Controls.Material
# ...
import QtQuick.Controls.Basic auto

编译时样式选择的优势在于，QML 编译器知道正在使用的是哪个特定样式，并能据此生成用于绑定的 C++ 代码。

另一个好处是，QtQuick.Controls 插件不会被使用，因此无需随应用程序一起部署。

如果您的应用程序采用静态构建，则还必须进行显式导入。

编译时样式选择的一个缺点是，一个可执行文件无法支持多种样式，因为每种样式都需要对应的可执行文件。

有关混合使用编译时和运行时样式选择的信息，请参阅“混合样式选择”。

运行时样式选择

运行时样式选择是一种通过导入QtQuick.Controls 来指定要使用的样式的方法：

import QtQuick.Controls

QtQuick.Controls 插件将通过以下任一方式，在运行时导入已设置的样式：

这些方法的优先级按列出的顺序从高到低排列。也就是说，例如，使用QQuickStyle 设置样式始终优先于使用命令行参数。

同样，可以通过以下任一方法设置备用样式：

注意： 只有当主样式对应的 qmldir 文件中未静态指定备用样式时，才可 动态选择备用样式。

运行时样式选择的优势在于，一个应用程序二进制文件可以支持多种样式，这意味着最终用户可以选择使用哪种样式来运行应用程序。

这种方法的一个缺点是，QML 编译器无法知道正在使用的是哪种具体样式，因此无法为Qt Quick Controls 类型的属性绑定生成 C++ 代码。这并不影响 QML 编译器为其他模块中的类型绑定生成 C++ 代码的能力。

有关混合运行时和编译时样式选择的信息，请参阅《样式选择的混合》。

特定于样式的 API

某些样式会提供其特有的 API，例如Material 样式的附加对象或Universal 样式的附加对象。这些样式特有的 API 仅在通过编译时或运行时样式选择（无论是直接还是间接）实际选中该样式时才可用。

混合样式选择

建议在应用程序中仅使用编译时或运行时样式选择其中一种。但是，如果您的应用程序加载了第三方 QML 代码，例如，可能无法控制使用哪些导入。如果您确实混合了这两种方法，请注意以下限制：

  • 编译时样式选择会覆盖运行时样式选择。
  • 您希望使用的样式必须始终在导入任何其他控件之前显式导入。若未这样做，主题设置（如字体和调色板）将无法按预期工作。QQuickStyle::name() 方法报告的样式即为第一个显式导入的样式。
  • 最后显式导入的样式才是实际使用的样式。例如，如果您先导入QtQuick.Controls ，然后导入QtQuick.Controls.Material ，那么在创建 Button 时将使用 Material 样式的 Button.qml。鉴于前文关于主题设置的说明，正因如此，您绝不应在同一个应用程序中显式导入两种不同的样式。
  • 如果你打算使用编译时样式选择，但加载了导入QtQuick.Controls 的代码，请注意：在显式导入样式之前调用QQuickStyle::name() 会导致报告平台默认样式。如果无法避免这种情况，请事先通过QQuickStyle::setStyle()或“运行时样式选择”中列出的其他方法之一，将样式设置为与编译时样式一致。

在 C++ 中使用 QQuickStyle

QQuickStyle 提供了用于配置特定样式的 C++ API。以下示例运行一个采用 Material 样式的Qt Quick Controls 应用程序：

QQuickStyle::setStyle("Material");

有关更多详细信息，请参阅QQuickStyle 的详细说明。

命令行参数

传递-style 命令行参数是测试不同样式的便捷方式。该方法优先于下面列出的其他方法。以下示例以Material样式运行一个Qt Quick Controls 应用程序：

./app -style Material

环境变量

设置QT_QUICK_CONTROLS_STYLE 环境变量可用于设置全局样式偏好。该方法优先于下文提到的配置文件。以下示例以 Universal 样式运行Qt Quick Controls 应用程序：

QT_QUICK_CONTROLS_STYLE=Universal ./app

有关支持的环境变量的完整列表，请参阅《Qt Quick Controls 》中的“支持的环境变量”。

配置文件

Qt Quick Controls 支持一个名为:/qtquickcontrols2.conf 的特殊配置文件，该文件内置于应用程序的资源中。

该配置文件可指定首选样式（可被前面所述的任一方法覆盖）以及某些样式特有的属性。以下示例指定首选样式为 Material 样式。

[Controls]
Style=Material

有关配置文件的更多详细信息，请参阅《Qt Quick Controls 配置文件》。

图标 基本样式

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