Material 风格

Material 风格基于 Google Material Design 设计指南。更多...

关联属性

• accent：颜色
• background: color
• elevation: int
• 前景色：颜色
• 主色：颜色
• 主题: 枚举
• 圆角刻度：枚举
• 容器样式：枚举

关联方法

• colorcolor(枚举 predefined, 枚举 shade)

详细说明

Material 风格基于Google Material Design 设计指南。它能够提供跨平台和跨设备尺寸的统一体验。

若要运行采用 Material 样式的应用程序，请参阅《Qt Quick Controls 中的样式使用指南》。

自定义

Material 样式支持多种可自定义属性。其中一些属性propagate 会像fonts 一样，将属性传递给子元素：

• theme
• primary
• accent
• 前景色
• 背景

其余属性不会传播到子元素：

• elevation
• roundedScale
• 容器样式

在下面的示例中，窗口和三个单选按钮均以深色主题显示，并使用紫色作为强调色：

import QtQuick
import QtQuick.Controls
import QtQuick.Controls.Material

ApplicationWindow {
    visible: true

    Material.theme: Material.Dark
    Material.accent: Material.Purple

    Column {
        anchors.centerIn: parent

        RadioButton {
            text: qsTr("Small")
        }
        RadioButton {
            text: qsTr("Medium")
            checked: true
        }
        RadioButton {
            text: qsTr("Large")
        }
    }
}

除了在 QML 中指定属性外，还可以通过环境变量或在配置文件中指定部分属性。在 QML 中指定的属性优先于所有其他指定方式。

配置文件

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

环境变量

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

依赖项

必须单独导入 Material 样式，才能使用该样式特有的属性。需要注意的是，无论是否引用了 Material 样式，相同的应用程序代码在任何其他样式下均可运行。Material 特有的属性仅在应用程序以 Material 样式运行时才生效。

如果 Material 样式被导入到一个始终加载的 QML 文件中，则必须将 Material 样式与应用程序一同部署，这样无论应用程序使用哪种样式运行，都能正常运行。通过使用文件选择器，可以在不与样式建立硬依赖关系的情况下应用特定于样式的调整。

预定义的 Material 颜色

尽管主色和点缀色可以是任意color ，但建议使用预定义的颜色之一，这些颜色经过专门设计，可与 Material 风格色板中的其他颜色完美搭配：

可用的预定义颜色：

当启用深色主题时，系统会默认使用预定义颜色的不同色调：

预定义色调

每种预定义颜色都有几种不同的色调，这些色调可以传递给Material.color()函数：

另请参阅 基本样式、通用样式

变体

“Material”样式还支持一种紧凑变体，其中按钮和委托等控件的高度较小，且使用较小的字体大小。建议在桌面平台上使用紧凑变体，因为在这些平台上，鼠标和键盘能够提供更精确、更灵活的用户交互。

要使用紧凑变体，可将QT_QUICK_CONTROLS_MATERIAL_VARIANT 环境变量设置为Dense ，或在qtquickcontrols2.conf文件中指定Variant=Dense 。这两种情况下的默认值均为Normal 。

下图展示了使用普通和密集变体时，部分控件之间的差异：

请注意，上图所示的高度可能会因不同平台字体差异而有所不同。

控件相关说明

TextArea

TextArea 支持两种容器样式：Filled 和Outlined 。带轮廓的 TextArea 其占位符文本为浮动式，位于控件顶部。 这要求占位符文本超出控件边界，当其父控件（TextArea 或Flickable）将clip 设置为true 时，可能会导致占位符文本被裁剪。为避免此情况，在上述情况下应将topInset 设置为适当值。

根据 Material 设计规范，占位文本应简短，且不应占用多行。

TextField

上文针对TextArea 所说明的裁剪问题，在 TextField中也可能出现。为避免此问题，当TextField 将clip设置为true 时，应将topInset 设置为适当值。

根据 Material 设计规范，占位符文本应简短，且不应占用多行。

附带的属性文档

此附加属性存储主题的强调色。该属性可附加到任何窗口或项目上。其值将传播给子元素。

默认值为Material.Pink 。

在下面的示例中，高亮按钮的强调色被更改为Material.Orange ：

Button {
    text: qsTr("Button")
    highlighted: true
    Material.accent: Material.Orange
}

此附加属性用于存储主题的背景色。该属性可附加到任何窗口或项目上。其值会传播给子元素。

默认值取决于主题（浅色或深色）。

在下面的示例中，按钮的背景色被更改为Material.Teal ：

Button {
    text: qsTr("Button")
    highlighted: true
    Material.background: Material.Teal
}

此附加属性保存控件的浮雕高度。浮雕高度越高，阴影越深。该属性可附加到任何控件，但并非所有控件都会显示浮雕效果。该值不会传播给子控件。

默认值因控件而异。

在下面的示例中，将窗格的 elevation 属性设置为6 ，以呈现出凸起的卡片效果：

Pane {
    width: 120
    height: 120

    Material.elevation: 6

    Label {
        text: qsTr("I'm a card!")
        anchors.centerIn: parent
    }
}

此附加属性保存主题的前景色。该属性可附加到任何窗口或项上。其值会传播给子元素。

默认值取决于主题（浅色或深色）。

在下面的示例中，按钮的前景色被设置为Material.Pink ：

Button {
    text: qsTr("Button")
    Material.foreground: Material.Pink
}

此附加属性保存了主题的主色。该属性可附加到任何窗口或项目上。其值会传播给子元素。

默认情况下，主色将用作ToolBar 的背景色。

默认值为Material.Indigo 。

此附加属性用于指定主题是浅色还是深色。该属性可附加到任何窗口或项目上。该值会传播给子元素。

可用主题：

将主题设置为System 时，系统会根据系统主题的颜色自动选择浅色或深色主题。但是，在读取主题属性的值时，该值绝不会是System ，而是实际的主题。

在下面的示例中，窗格和按钮的主题均设置为Material.Dark ：

Pane {
    Material.theme: Material.Dark

    Button {
        text: qsTr("Button")
    }
}

此附加属性保存目标控件所使用的圆角半径。该属性可附加到任何窗口或项目上，但仅部分控件支持该属性。该值不会传播给子控件。

默认值因控件而异。

可用圆角半径：

该属性是在 Qt 6.5 中添加的。

另请参阅：Material 样式：形状。

此附加属性存储目标控件所用容器的样式。该属性可附加到任何窗口或项上，但默认情况下仅TextField 和TextArea 支持该属性。该值不会传播到子控件。

默认值因控件而异。

可用样式：

该属性在 Qt 6.5 中新增。

另请参阅：Material 样式：文本字段容器。

附带的方法文档

此附加方法返回指定预定义 Material 颜色与给定色调组合后的实际颜色值。如果省略，色调参数的默认值为Material.Shade500 。

Rectangle {
    color: Material.color(Material.Red)
}

相关信息

• 样式设置Qt Quick Controls