材料风格

材质风格基于《谷歌材质设计指南》。更多

附加属性

• accent: 颜色
• 背景：颜色
• elevation: int
• 前景: 颜色
• 主色: 颜色
• 主题：枚举
• roundedScale: 枚举
• containerStyle: 枚举

附加方法

• colorcolor（枚举预定义，枚举阴影）

详细说明

Material 风格基于Google Material 设计指南。它可以实现跨平台和跨设备尺寸的统一体验。

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

自定义

材质 "样式支持多个可自定义的属性。其中一些属性propagate 到子代的方式与fonts 相同：

• 主题
• 主要
• 重音
• 前景
• 背景

其余属性不会传播给子代：

• 提升
• 圆角刻度
• 容器样式

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

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 中的"支持的环境变量"。

依赖关系

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

如果在始终加载的 QML 文件中导入了 Material 样式，则必须将 Material 样式与应用程序一起部署，这样才能运行应用程序，而不管应用程序以哪种样式运行。通过使用文件选择器，可以应用特定于样式的调整，而不会对样式产生硬性依赖。

预先定义的材质颜色

尽管主色调和重点色调可以是任何color ，但建议使用其中一种预定义颜色，这些颜色可与 Material 风格调色板的其余部分完美搭配：

可用的预定义颜色：

使用深色主题时，默认情况下会使用不同色调的预定义颜色：

预设色调

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

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

变体

材质样式还支持密集变体，在这种变体中，按钮和委托等控件的高度较小，使用的字体也较小。建议在桌面平台上使用密集变体，因为在桌面平台上使用鼠标和键盘可以实现更精确、更灵活的用户交互。

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

下面的图片说明了一些控件在使用普通和密集变体时的不同之处：

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

控件特定说明

文本区域

TextArea 支持两种容器样式： 和 。Outlined TextArea 具有浮动占位符文本，位于控件顶部。这就要求占位符文本超出控件的边界，当 或其子控件 Flickable 将 设置为 时，占位符文本就会被剪切。为避免这种情况，在这些情况下， 设置为适当的值。Filled Outlined TextArea clip true topInset

根据材料指南，占位符文本应保持简短，不要占据多行。

文本字段

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

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

附加属性文档

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

默认值为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
}

此附加属性表示控件的高度。高度越高，阴影越深。该属性可附加到任何控件，但并非所有控件都能将海拔高度可视化。该值不会传播给子控件。

默认值与控件相关。

在下面的示例中，窗格的标高被设置为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 时，会根据系统主题颜色选择浅色或深色主题。不过，在读取 theme 属性的值时，该值绝不是System ，而是实际主题。

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

Pane {
    Material.theme: Material.Dark

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

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

默认值与控件有关。

可用刻度

此属性在 Qt 6.5 中添加。

另请参阅：材质风格：形状

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

默认值是特定于控件的。

可用样式：

此属性在 Qt 6.5 中添加。

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

附加方法文档

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

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

相关信息

• 样式Qt Quick Controls