材质风格

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

附加属性

• 突出显示 : 颜色
• 背景 : 颜色
• 高度 : 整数
• 前景 : 颜色
• 主要 : 颜色
• 主题 : 枚举
• 圆角缩放 : 枚举
• 容器样式 : 枚举

附加方法

• 颜色 颜色(枚举预定义，枚举阴影)

详细描述

材质风格基于谷歌材质设计指南。它允许跨平台和设备大小提供统一的体验。

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

定制

材质风格支持几个可定制的属性。其中一些属性以与字体相同的方式传输给子项

• 主题
• 主要
• 突出显示
• 前景
• 背景

其余属性不传输给子项

• 高度
• 圆角缩放
• 容器样式

在以下示例中，窗口和三个单选按钮都使用紫色突出显示颜色以在深色主题中显示

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 控件配置文件。

环境变量

有关支持的环境变量完整列表，请参阅Qt Quick 控件支持的环境变量。

依赖

必须单独导入材质样式，才能访问材质样式特有的属性。请注意，无论对材质样式的引用如何，相同的应用程序代码都可以与任何其他样式一起运行。材质特定的属性仅当应用程序以材质样式运行时才有作用。

如果材质样式导入了一个始终加载的QML文件，则必须与应用程序一起部署材质样式，以便能够在使用任何样式的情况下运行应用程序。通过使用文件选择器，可以为特定样式应用调整，而无需创建对样式的硬依赖。

预定义的材质颜色

尽管主色和强调色可以是任何颜色，但建议使用专为与材质样式调色板中的其他颜色搭配设计的预定义颜色之一。

可用的预定义颜色

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

预定义色调

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

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

变体

Material样式也支持紧凑变体，其中控件（如按钮和委派）在高度上更小，并使用更小的字体大小。建议在桌面平台上使用紧凑变体，因为鼠标和键盘允许更精确和灵活的用户交互。

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

以下图片展示了使用正常和紧凑变体时，一些控件之间的差异

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

特定于控件说明

文本区域

文本区域支持两种容器样式：填充和轮廓。轮廓文本区域有浮动的占位符文本，位于控件的顶部。这要求占位符文本超出控件的边界，这可能导致它在文本区域或其子控件设置剪切为true时被剪切。为了避免这种情况，在这些情况下应将topInset设置为适当的值。

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

文本字段

上文中解释的与裁剪相关的问题< samp translate="no">（TextArea的裁剪问题）也可能会出现在< a href="qml-qtquick-controls-textfield.html" translate="no">TextField中。为了避免这种情况，当< a href="qml-qtquick-controls-textfield.html" translate="no">TextField设置clip为< code translate="no">true时，会设置一个适当的< a href="qml-qtquick-controls-control.html#topInset-prop" translate="no">topInset值。

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

附加属性文档< a class="plink" href="#attached-property-documentation" title="直接链接到此标题">

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

默认值是< code translate="no">Material.Pink。

在以下示例中，突出按钮的强调色被更改为< code translate="no">Material.Orange

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

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

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

在以下示例中，将按钮的背景色更改为了< code translate="no">Material.Teal

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

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

默认值是控件特定的。

在以下示例中，将面板的层次设置为< code translate="no">6以达到< a href="https://m3.material.io/components/cards/overview" translate="no">悬浮卡的效果

Pane {
    width: 120
    height: 120

    Material.elevation: 6

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

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

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

在以下示例中，将按钮的前景色设置为< code translate="no">Material.Pink

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

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

默认情况下，主颜色用作< a href="qml-qtquick-controls-toolbar.html" translate="no">工具栏的背景颜色。

默认值是< code translate="no">Material.Indigo。

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

可用主题

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

在以下示例中，面板和按钮的主题都被设置为< code translate="no">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控件的样式