材料风格¶

附加属性¶

• accent :ref:` ` : 颜色

• 背景 :ref:` ` : 颜色

• elevation :ref:` ` : int

• foreground :ref:` ` : 颜色

• primary :ref:` ` : 颜色

• theme :ref:` ` : 枚举

• roundedScale :ref:` ` : 枚举

• containerStyle :ref:` ` : 枚举

附加方法¶

• 颜色 color :ref:` ` (枚举预定义, 枚举阴影)

详细描述¶

Material 风格基于 Google Material Design Guidelines。它允许跨平台和设备尺寸的统一体验。

Material 风格的浅色主题。

Material 风格的深色主题。

要使用Material风格运行应用程序，请参阅在Qt Quick Controls中使用样式。

自定义¶

Material 样式支持多个可自定义的属性。其中一些属性会以与字体相同的方式传播到子元素：

• 主题

• primary

• accent

• 前景

• 背景

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

• 海拔

• roundedScale

• containerStyle

在以下示例中，窗口和所有三个单选按钮使用紫色强调颜色显示在深色主题中：

++———————————————————+ || .. 图片:: images/qtquickcontrols-material-purple.png| ++———————————————————+

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

配置文件¶

变量	描述
Theme	指定默认的Material主题。该值可以是可用的主题之一，例如"Dark"。
Variant	指定材料变体。材料设计有两种变体：一种是为触摸设备设计的普通变体，另一种是为桌面设计的密集变体。密集变体使用较小的控件尺寸和字体。 值可以是 "Normal" 或 "Dense"。
Accent	指定默认的Material 强调色。该值可以是任何颜色，但建议使用预定义的 Material 颜色之一，例如"Teal"。
Primary	指定默认的Material 主色。该值可以是任何颜色，但建议使用预定义的 Material 颜色之一，例如"BlueGrey"。
Foreground	指定默认的Material前景色。该值可以是任何颜色，或者是预定义的Material颜色之一，例如"Brown"。
背景	指定默认的Material背景颜色。该值可以是任何颜色，或者是预定义的Material颜色之一，例如"Grey"。

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

环境变量¶

变量	描述
QT_QUICK_CONTROLS_MATERIAL_THEME	指定默认的Material主题。该值可以是可用主题之一，例如"Dark"。
QT_QUICK_CONTROLS_MATERIAL_VARIANT	指定Material变体。Material Design有两种变体：一种是为触摸设备设计的普通变体，另一种是为桌面设计的密集变体。密集变体使用较小的控件尺寸和字体。 值可以是"Normal"或"Dense"。
QT_QUICK_CONTROLS_MATERIAL_ACCENT	指定默认的Material强调色。该值可以是任何颜色，但建议使用预定义的Material颜色之一，例如"Teal"。
QT_QUICK_CONTROLS_MATERIAL_PRIMARY	指定默认的Material 主色。该值可以是任何颜色，但建议使用预定义的 Material 颜色之一，例如 "BlueGrey"。
QT_QUICK_CONTROLS_MATERIAL_FOREGROUND	指定默认的Material前景色。该值可以是任何颜色，或者是预定义的Material颜色之一，例如"Brown"。
QT_QUICK_CONTROLS_MATERIAL_BACKGROUND	指定默认的Material背景颜色。该值可以是任何颜色，或者是预定义的Material颜色之一，例如"Grey"。

查看Qt Quick Controls中支持的环境变量以获取支持的环境变量的完整列表。

依赖¶

必须单独导入Material样式才能访问特定于Material样式的属性。需要注意的是，无论是否引用Material样式，相同的应用程序代码都可以与任何其他样式一起运行。只有在使用Material样式运行应用程序时，特定于Material的属性才会生效。

如果在始终加载的QML文件中导入了Material样式，则必须将Material样式与应用程序一起部署，以便无论应用程序以哪种样式运行，都能运行应用程序。通过使用文件选择器，可以应用特定于样式的调整，而无需创建对样式的硬依赖。

预定义的材料颜色¶

尽管主色和强调色可以是任何颜色，但建议使用预定义的颜色之一，这些颜色设计为与Material风格调色板的其余部分很好地配合：

可用的预定义颜色：

• 材料.红色

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

• 材料.红色

预定义阴影¶

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

• Material.Shade50

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

变体¶

Material 风格还支持密集变体，其中按钮和委托等控件的高度较小，并使用较小的字体大小。建议在桌面平台上使用密集变体，因为鼠标和键盘允许更精确和灵活的用户交互。

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

以下图片展示了在使用普通和密集变体时，一些控件之间的差异：

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

控件特定说明¶

文本区域¶

TextArea 支持两种 containerStyles：Filled 和 Outlined。Outlined TextAreas 具有浮动占位符文本，该文本位于控件的顶部。这要求占位符文本超出控件的边界，当 TextArea 或其父级 Flickable 将 clip 设置为 true 时，可能会导致文本被裁剪。为了避免这种情况，在这些情况下将 topInset 设置为适当的值。

根据Material指南，占位符文本应保持简短，不应占用多行。

文本字段¶

上面解释的裁剪问题同样可能发生在TextField中。为了避免这种情况，当TextField将clip设置为true时，topInset会被设置为一个适当的值。

根据Material指南，占位符文本应保持简短，不应占用多行。

附加属性文档¶

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

默认值为Material.Pink。

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

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

此附加属性保存主题的背景颜色。该属性可以附加到任何窗口或项目。该值会传播到子元素。

默认值是主题特定的（浅色或深色）。

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

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

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

默认值是控件特定的。

在以下示例中，窗格的高度设置为 6 以实现 elevated card 的外观：

Pane { width: 120 height: 120 Material.elevation: 6 Label { text: qsTr("我是一个卡片！") anchors.centerIn: parent } }

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

默认值是主题特定的（浅色或深色）。

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

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

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

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

默认值为Material.Indigo。

此附加属性保存主题是浅色还是深色。该属性可以附加到任何窗口或项目。该值会传播到子项。

可用主题：

• 材质.光

• 浅色主题（默认）

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

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

面板 { 材质.主题: 材质.暗色 按钮 { 文本: qsTr("按钮") } }

此附加属性保存目标控件上使用的圆角半径。该属性可以附加到任何窗口或项目，但只有一些控件支持它。该值不会传播到子元素。

默认值是控件特定的。

可用的比例尺：

• 材料.未圆角

• 方形角落

此属性在Qt 6.5中添加。

另请参阅：Material Style: Shape 。

此附加属性保存目标控件使用的容器的样式。该属性可以附加到任何窗口或项目，但默认情况下只有TextField和TextArea支持它。该值不会传播到子元素。

默认值是控件特定的。

可用样式：

• Material.Filled

• 如果有可用的填充容器变体，请使用它

此属性在Qt 6.5中添加。

另请参阅：Material Style: Text Field Containers 。

附加方法文档¶

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

相关信息¶

• 样式化Qt Quick控件