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

从Qt Quick Controls 1升级 受支持的环境变量

Qt Quick Controls 配置文件

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

该配置文件可指定首选样式以及某些样式特有的属性。以下示例指定首选样式为Material 样式。 此外，当应用程序以 Material 样式运行时，其主题为浅色，强调色和主色分别为青绿色和蓝灰色。但是，如果应用程序以Universal 样式运行，则强调色为红色，并且会根据系统主题颜色选择相应的主题。

[Controls]
Style=Material

[Universal]
Theme=System
Accent=Red

[Material]
Theme=Light
Accent=Teal
Primary=BlueGrey

可以通过QT_QUICK_CONTROLS_CONF环境变量为配置文件指定自定义位置。

控件部分

可在配置文件的Controls 部分中指定以下值：

变量描述
Style指定应用程序运行时使用的样式。该值可以是内置样式之一，也可以是自定义样式。
FallbackStyle指定用于未实现控件的样式。该样式必须是内置样式之一。默认情况下，使用“Basic”样式。

Imagine 部分

下表列出了可在配置文件的Imagine 部分中用于配置“Imagine”样式的值：

变量描述
Path指定包含 Imagine 样式资源的目录路径。如果未指定，则使用内置资源。

例如，要指定存储在资源系统中的目录路径：

[Imagine]
Path=:/imagine-assets

要指定本地目录的相对路径：

[Imagine]
Path=imagine-assets

注意：由于 技术限制，如果路径相对于qtquickcontrols2.conf 文件，则该路径不应命名为“imagine”。

材质部分

下表列出了可在配置文件的Material 部分中用于配置Material样式的参数值：

变量描述
Theme指定默认的Material主题。该值可以是可用主题之一，例如"Dark" 。
Variant指定 Material 变体。Material Design 有两种变体：一种是为触控设备设计的标准变体，另一种是适用于桌面的紧凑变体。紧凑变体采用更小的控件尺寸及其字体。

其值可以是"Normal" 或"Dense" 。

Accent指定默认的Material 强调色。该值可以是任意color ，但建议使用预定义的 Material 颜色之一，例如"Teal" 。
Primary指定默认的Material 主色。该值可以是任何color ，但建议使用预定义的 Material 颜色之一，例如"BlueGrey" 。
Foreground指定默认的Material 前景色。该值可以是任意color ，也可以是预定义的 Material 颜色之一，例如"Brown" 。
Background指定默认的Material 背景色。该值可以是任何color ，也可以是预定义的 Material 颜色之一，例如"Grey" 。

通用部分

下表列出了可在配置文件的Universal 部分中用于配置通用样式的值：

变量描述
Theme指定默认的通用主题。该值可以是可用主题之一，例如"Dark" 。
Accent指定“通用”样式的默认强调色。该值可以是任何color ，但建议使用预定义的“通用”颜色之一，例如"Violet" 。
Foreground指定默认的Universal 前景色。该值可以是任意color颜色，或预定义的 Universal 颜色之一，例如"Brown" 。
Background指定默认的通用背景色。该值可以是任何color ，或预定义的通用颜色之一，例如"Steel" 。

字体配置

可在配置文件中每个样式部分的Font 子组中指定默认font ：

[Basic]
Font\Family=Open Sans
Font\PixelSize=20

支持的字体属性：

变量描述
Familyfont family 。
PointSizepoint size 。
PixelSizepixel size 。
StyleHintstyle hint 。可用值：SansSerif 、Helvetica 、Serif 、Times 、TypeWriter 、Courier 、OldEnglish 、Decorative 、Monospace 、Fantasy 、Cursive 。
Weightweight 。Qt采用的字重标尺范围为1 至1000 ，与OpenType兼容。字重1 为细体，而1000 则为极粗体。 可用的预定义字重：Thin (100)、ExtraLight (200)、Light (300)、Normal (400)、Medium (500)、DemiBold (600)、Bold (700)、ExtraBold (800)、Black (900)。
Stylestyle 。可用值：StyleNormal 、StyleItalic 、StyleOblique 。

调色板配置

可以通过配置文件中的Palette 子组为每种样式配置默认的palette 。Palette 子组可通过以下两种方式定义：

[Fusion]
Palette\Window=#dedede
Palette\WindowText=#212121

有关更多信息，请参阅Palette QML类型。

在项目中使用配置文件

为了使Qt Quick Controls 能够找到配置文件，必须使用Qt 资源系统将其构建到应用程序的资源中。以下是一个.qrc 文件的示例：

<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/">
    <file>qtquickcontrols2.conf</file>
</qresource>
</RCC>

注意： Qt Quick Controls 使用文件选择器来加载配置文件。可以为不同的平台和区域设置提供不同的配置文件。有关更多详细信息，请参阅QFileSelector 文档。

最后，.qrc 文件必须在应用程序的构建文件中列出。例如：

set(CMAKE_AUTORCC ON)
qt_add_executable(my_app
    application.qrc
    main.cpp
    ...
)
RESOURCES = application.qrc
...

另请参阅：构建系统集成

从Qt Quick Controls 1升级 支持的环境变量

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