此页面由 Cloud Translation API 翻译。

Compose 中的 Material Design 3

Jetpack Compose 提供了 Material Design 3 的实现，新一代 Material DesignMaterial 3 包含更新后的主题设置，组件和 Material You 个性化功能（例如动态配色），旨在与 Android 12 的全新视觉风格和系统界面相得益彰及更高级别。

下面，我们将演示 Material Design 3 的实现以 Reply 示例应用为例。Reply 示例为完全基于 Material Design 3

**图 1**.使用 Material Design 3 的 Reply 示例应用

依赖项

如需在 Compose 应用中开始使用 Material 3，请添加 Compose Material 3 依赖项添加到 build.gradle 文件中：

implementation "androidx.compose.material3:material3:$material3_version"

添加依赖项后，您就可以开始添加 Material Design 系统了，包括颜色、排版和形状。

实验性 API

某些 M3 API 被视为实验性 API。在这种情况下，您需要使用 ExperimentalMaterial3Api 注解在函数或文件级别指定 OptIn：

// import androidx.compose.material3.ExperimentalMaterial3Api
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppComposable() {
    // M3 composables
}
Material3Snippets.kt

Material 主题设置

M3 主题包含以下子系统：配色方案、排版和形状。自定义时那么您所做的更改会自动反映在构建应用

Jetpack Compose 使用 M3 MaterialTheme 实现这些概念。可组合项：

MaterialTheme(
    colorScheme = /* ...
    typography = /* ...
    shapes = /* ...
) {
    // M3 app content
}Material3Snippets.kt

要为应用内容设置主题，请定义配色方案、排版和形状。

配色方案

配色方案的基础是五种主要颜色。以上每一个颜色与由 Material 3 使用的 13 种色调相关组件。例如，以下就是回复：

详细了解配色方案和颜色角色。

生成配色方案

虽然您可以手动创建自定义 ColorScheme，但使用品牌中的源颜色通常更容易生成配色方案。Material 主题 Builder 工具可让您执行此操作。 Compose 主题代码。生成以下文件：

Color.kt 包含主题的颜色以及为以下角色定义的所有角色：浅色主题和深色主题的颜色

val md_theme_light_primary = Color(0xFF476810)
val md_theme_light_onPrimary = Color(0xFFFFFFFF)
val md_theme_light_primaryContainer = Color(0xFFC7F089)
// ..
// ..

val md_theme_dark_primary = Color(0xFFACD370)
val md_theme_dark_onPrimary = Color(0xFF213600)
val md_theme_dark_primaryContainer = Color(0xFF324F00)
// ..
// ..Material3Snippets.kt

Theme.kt 包含浅色和深色配色方案以及应用的设置主题。

private val LightColorScheme = lightColorScheme(
    primary = md_theme_light_primary,
    onPrimary = md_theme_light_onPrimary,
    primaryContainer = md_theme_light_primaryContainer,
    // ..
)
private val DarkColorScheme = darkColorScheme(
    primary = md_theme_dark_primary,
    onPrimary = md_theme_dark_onPrimary,
    primaryContainer = md_theme_dark_primaryContainer,
    // ..
)

@Composable
fun ReplyTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    val colorScheme =
        if (!darkTheme) {
            LightColorScheme
        } else {
            DarkColorScheme
        }
    MaterialTheme(
        colorScheme = colorScheme,
        content = content
    )
}Material3Snippets.kt

如需支持浅色主题和深色主题，请使用 isSystemInDarkTheme()。基于系统设置，定义要使用的配色方案：浅色或深色。

动态配色方案

动态配色是 Material You 的关键部分，其中算法会从用户的壁纸中派生自定义颜色，并将其应用到用户的壁纸中。和系统界面此调色板可作为基础来生成浅色和深色配色方案

**图 4**. 通过壁纸设置回复示例应用动态主题（左）和默认应用主题设置（右）

动态颜色适用于 Android 12 及更高版本。如果动态颜色可用，您可以设置动态 ColorScheme。否则，您应回退自定义浅色或深色 ColorScheme。

ColorScheme 提供了构建器函数来创建动态光照或深色配色方案：

// Dynamic color is available on Android 12+
val dynamicColor = Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
val colors = when {
    dynamicColor && darkTheme -> dynamicDarkColorScheme(LocalContext.current)
    dynamicColor && !darkTheme -> dynamicLightColorScheme(LocalContext.current)
    darkTheme -> DarkColorScheme
    else -> LightColorScheme
}Material3Snippets.kt

颜色的使用

您可以通过以下方式在应用中获取 Material 主题颜色： MaterialTheme.colorScheme:

Text(
    text = "Hello theming",
    color = MaterialTheme.colorScheme.primary
)Material3Snippets.kt

每种颜色角色都可在各种位置使用，具体取决于组件的状态、显眼程度和强调效果

主色是基础颜色，用于醒目位置等主要组件按钮、活动状态以及凸起表面的色调。
辅助键颜色用于界面中不太显眼的组件，例如以过滤组件的形式呈现，扩展了表达色彩的机会。
第三色用于推导对比强调色可用于平衡主色和辅色，一个元素。

Reply 示例应用设计使用 on-primary-container 颜色，位于 primary-container，用于强调所选内容。

具有主容器颜色的主要容器和文本字段。 — **图 5**.主要容器和文本字段采用主容器颜色。

Card(
    colors = CardDefaults.cardColors(
        containerColor =
        if (isSelected) MaterialTheme.colorScheme.primaryContainer
        else
            MaterialTheme.colorScheme.surfaceVariant
    )
) {
    Text(
        text = "Dinner club",
        style = MaterialTheme.typography.bodyLarge,
        color =
        if (isSelected) MaterialTheme.colorScheme.onPrimaryContainer
        else MaterialTheme.colorScheme.onSurface,
    )
}
Material3Snippets.kt

在这里，您可以在回复抽屉式导航栏中了解辅助和第三使用对比容器颜色来形成强调效果和强调效果。

排版

Material Design 3 定义了字型比例，包括文本样式根据 Material Design 2 调整而来命名和分组已简化为：显示、大标题、标题、正文和标签，每个都有大号、中号和小号。

M3	默认字体大小/行高
`displayLarge`	`Roboto 57/64`
`displayMedium`	`Roboto 45/52`
`displaySmall`	`Roboto 36/44`
`headlineLarge`	`Roboto 32/40`
`headlineMedium`	`Roboto 28/36`
`headlineSmall`	`Roboto 24/32`
`titleLarge`	`New- Roboto Medium 22/28`
`titleMedium`	`Roboto Medium 16/24`
`titleSmall`	`Roboto Medium 14/20`
`bodyLarge`	`Roboto 16/24`
`bodyMedium`	`Roboto 14/20`
`bodySmall`	`Roboto 12/16`
`labelLarge`	`Roboto Medium 14/20`
`labelMedium`	`Roboto Medium 12/16`
`labelSmall`	`New Roboto Medium, 11/16`

定义排版

Compose 提供了 M3 Typography 类，以及现有的 TextStyle 和与字体相关的类，用于为 Material 3 类型建模。Typography 构造函数提供了每种样式的默认值，因此可以省略您不想自定义的任何参数：

val replyTypography = Typography(
    titleLarge = TextStyle(
        fontWeight = FontWeight.SemiBold,
        fontSize = 22.sp,
        lineHeight = 28.sp,
        letterSpacing = 0.sp
    ),
    titleMedium = TextStyle(
        fontWeight = FontWeight.SemiBold,
        fontSize = 16.sp,
        lineHeight = 24.sp,
        letterSpacing = 0.15.sp
    ),
    // ..
)
// ..Material3Snippets.kt

“body Large”（正文）、“body”（中等）和“label medium”（标签中等），用于不同排版用途。 — **图 8**.“Body Large”（正文大）、“body medium”（正文中等）和“label medium”（标签中等），用于不同排版用途。

您的产品可能并不需要 Material Design 中的所有 15 种默认样式字体比例。在本示例中，为缩减集合选择了五个尺寸，而其余部分被省略。

您可以通过更改 TextStyle 的默认值来自定义排版以及 fontFamily 和 letterSpacing 等字体相关属性。

bodyLarge = TextStyle(
    fontWeight = FontWeight.Normal,
    fontFamily = FontFamily.SansSerif,
    fontStyle = FontStyle.Italic,
    fontSize = 16.sp,
    lineHeight = 24.sp,
    letterSpacing = 0.15.sp,
    baselineShift = BaselineShift.Subscript
),Material3Snippets.kt

定义 Typography 后，请将其传递给 M3 MaterialTheme：

MaterialTheme(
    typography = replyTypography,
) {
    // M3 app Content
}Material3Snippets.kt

使用文本样式

您可以通过以下方式检索提供给 M3 MaterialTheme 可组合项的排版：使用 MaterialTheme.typography：

Text(
    text = "Hello M3 theming",
    style = MaterialTheme.typography.titleLarge
)
Text(
    text = "you are learning typography",
    style = MaterialTheme.typography.bodyMedium
)Material3Snippets.kt

您可以在应用排版。

形状

Material Surface 可以用不同的形状显示。形状能够引导用户注意力识别组件、传达状态以及表达品牌。

形状比例定义了容器角的样式，提供一系列从正方形变为完全圆形

定义形状

Compose 提供了带有扩展参数的 M3 Shapes 类来支持新的 M3 形状M3 形状比例更像是字体比例，从而在整个界面中呈现丰富多样的形状

形状有不同大小：

较小
小
中号
大
超大

默认情况下，每个形状都有一个默认值，但是您可以替换这些值：

val replyShapes = Shapes(
    extraSmall = RoundedCornerShape(4.dp),
    small = RoundedCornerShape(8.dp),
    medium = RoundedCornerShape(12.dp),
    large = RoundedCornerShape(16.dp),
    extraLarge = RoundedCornerShape(24.dp)
)Material3Snippets.kt

定义 Shapes 后，您可以将其传递给 M3 MaterialTheme：

MaterialTheme(
    shapes = replyShapes,
) {
    // M3 app Content
}Material3Snippets.kt

使用形状

您可以为 MaterialTheme 中的所有组件自定义形状缩放，或者也可以按组件创建

使用默认值应用大中型形状：

Card(shape = MaterialTheme.shapes.medium) { /* card content */ }
FloatingActionButton(
    shape = MaterialTheme.shapes.large,
    onClick = {
    }
) {
    /* fab content */
}Material3Snippets.kt

Reply 示例应用中针对卡片的中等形状和针对悬浮操作按钮的大形状。 — **图 9**.Reply 示例应用中适用于卡片的中号形状和悬浮操作按钮的大号形状

此外，还有另外两种形状：RectangleShape 和 CircleShape，它们是功能。矩形没有边框半径，圆形显示完整带圆圈的边：

Card(shape = RectangleShape) { /* card content */ }
Card(shape = CircleShape) { /* card content */ }Material3Snippets.kt

以下示例展示了使用默认形状值的一些组件已应用于：

您可以在应用形状。

强调效果

M3 中的强调效果是使用颜色变体及其组合。在 M3 中，可以通过两种方式为界面添加强调效果：

将 Surface、surface-variant 和背景与 on-surface 结合使用，扩展 M3 颜色系统中的 on-surface-variants 颜色。例如： Surface 可与 on-surface-variant 一起使用，surface-variant 可用于以提供不同级别的强调效果

为文本使用不同粗细的字体。如上所示，您可以自定义粗细到我们的字体比例，以提供不同的强调效果。

bodyLarge = TextStyle(
    fontWeight = FontWeight.Bold
),
bodyMedium = TextStyle(
    fontWeight = FontWeight.Normal
)Material3Snippets.kt

Z 轴高度

Material 3 主要使用色调颜色叠加叠加层来表示高度。这是一个新的区分容器和 Surface 的方法 - 增加色调高度除了使用阴影外，还使用了更突出的色调。

色调高度搭配阴影高度 — **图 12**.色调高度搭配阴影 ElevationE

深色主题中的高度叠加层在 Material 3。叠加层颜色来自主要颜色槽。

M3 Surface 是大多数 M3 组件的后备可组合项。同时支持色调和阴影高度：

Surface(
    modifier = Modifier,
    tonalElevation = /*...
    shadowElevation = /*...
) {
    Column(content = content)
}Material3Snippets.kt

Material 组件

Material Design 提供了一组丰富的 Material 组件（例如按钮、条状标签、卡片、导航栏）且已遵循 Material 规范设置主题并帮助您构建精美的 Material Design 应用。您可以开始使用具有默认属性。

Button(onClick = { /*..*/ }) {
    Text(text = "My Button")
}Material3Snippets.kt

M3 提供了同一组件的多个版本，供不同角色使用根据强调效果和注意力进行调整

按钮强调效果从 FAB 变为“主要向下”按钮 — **图 14**.按钮强调效果从 FAB 变为“主要”按钮，改为“文本”按钮

用于进行最高强调度操作的扩展悬浮操作按钮：

ExtendedFloatingActionButton(
    onClick = { /*..*/ },
    modifier = Modifier
) {
    Icon(
        imageVector = Icons.Default.Edit,
        contentDescription = stringResource(id = R.string.edit),
    )
    Text(
        text = stringResource(id = R.string.add_entry),
    )
}Material3Snippets.kt

高强调度操作的实心按钮：

Button(onClick = { /*..*/ }) {
    Text(text = stringResource(id = R.string.view_entry))
}Material3Snippets.kt

用于低强调度操作的文本按钮：

TextButton(onClick = { /*..*/ }) {
    Text(text = stringResource(id = R.string.replated_articles))
}Material3Snippets.kt

您可以详细了解 Material 按钮和其他组件。 Material 3 提供了各种组件套件，例如按钮、应用栏、专门为不同用途设计的导航组件手机壳和屏幕尺寸

Material 还提供了多个导航组件，可帮助您实现具体取决于不同的屏幕尺寸和状态。

当您想要定位到 5 个或更少版本时，NavigationBar 用于紧凑型设备目的地：

NavigationBar(modifier = Modifier.fillMaxWidth()) {
    Destinations.entries.forEach { replyDestination ->
        NavigationBarItem(
            selected = selectedDestination == replyDestination,
            onClick = { },
            icon = { }
        )
    }
}Material3Snippets.kt

NavigationRail 适用于中小型平板电脑或手机，横向模式。既能为用户提供工效学设计，又能改善用户体验。

NavigationRail(
    modifier = Modifier.fillMaxHeight(),
) {
    Destinations.entries.forEach { replyDestination ->
        NavigationRailItem(
            selected = selectedDestination == replyDestination,
            onClick = { },
            icon = { }
        )
    }
}Material3Snippets.kt

底部导航栏（左侧）和侧边导航栏（右侧）的回复展示 — **图 15**.`BottomNavigationBar`（左）和`NavigationRail`（右）的回复展示

在默认主题中同时使用两种样式来回复，为所有用户提供沉浸式用户体验设备尺寸

NavigationDrawer 适用于空间足够显示细节您可以使用 PermanentNavigationDrawer 或 ModalNavigationDrawer以及NavigationRail。

PermanentNavigationDrawer(modifier = Modifier.fillMaxHeight(), drawerContent = {
    Destinations.entries.forEach { replyDestination ->
        NavigationRailItem(
            selected = selectedDestination == replyDestination,
            onClick = { },
            icon = { },
            label = { }
        )
    }
}) {
}Material3Snippets.kt

导航选项可提升用户体验、人体工学设计和单手操作性。如需详细了解 Material 导航组件，请参阅 Compose 自适应 Codelab。

自定义组件的主题设置

M3 鼓励个性化和灵活性。所有组件都有默认值但如果有的话，您可以使用灵活的 API 自定义其颜色，必填字段。

大多数组件（例如卡片和按钮）都会提供默认对象公开颜色以及可通过修改来自定义组件的高度接口：

val customCardColors = CardDefaults.cardColors(
    contentColor = MaterialTheme.colorScheme.primary,
    containerColor = MaterialTheme.colorScheme.primaryContainer,
    disabledContentColor = MaterialTheme.colorScheme.surface,
    disabledContainerColor = MaterialTheme.colorScheme.onSurface,
)
val customCardElevation = CardDefaults.cardElevation(
    defaultElevation = 8.dp,
    pressedElevation = 2.dp,
    focusedElevation = 4.dp
)
Card(
    colors = customCardColors,
    elevation = customCardElevation
) {
    // m3 card content
}Material3Snippets.kt

您可以详细了解如何自定义 Material 3。

系统界面

Material You 的某些方面来自于上的新视觉样式和系统界面， Android 12 及更高版本。效果变化的两个主要方面是涟漪效果和滚动。您无需执行任何额外操作即可实施这些更改。

涟漪

现在，按下时，涟漪会使用微小的火花照射表面。Compose Material Ripple 在后台使用 RippleDrawable 平台 Android，因此 Android 12 及更高版本支持所有 Material 设备上的火花涟漪组件。

滚动

滚动现在会在滚动容器的边缘使用拉伸效果。对于滚动容器可组合项，拉伸滚动回弹默认处于开启状态。例如，LazyColumn、LazyRow 和 LazyVerticalGrid - Compose Foundation 1.1.0 及更高版本（无论 API 级别如何）。

无障碍

Material 组件中内置的无障碍功能标准旨在提供为产品设计包容性奠定了基础。了解您产品的无障碍功能可增强对所有用户的易用性，包括那些视觉, 失明, 听力障碍, 认知障碍, 运动残疾或情境性残疾（例如手臂骨折）。

颜色无障碍功能

动态配色旨在满足色彩对比度的无障碍功能标准。色调调色板系统对于确保任何配色方案的易用性至关重要默认情况。

Material 的颜色系统提供标准色调值和测量值，以满足易于使用的对比度。

Reply 示例应用：主要、次要和第三色调面板（从上到下） — **图 19**.Reply 示例应用：主要、次要和第三色调调色板（从上到下）

所有 Material 组件和动态主题均已使用上述颜色角色从一组色调调色板中选出，以符合无障碍功能要求要求。但是，如果您要自定义组件，请务必使用适当的颜色角色，并避免不匹配。

在主实例之上使用 on-primary，在主实例之上使用 on-primary-container 而对于其他强调色和中性色也是如此能形成鲜明对比

在主要容器之上使用第三容器会导致用户体验不佳， “对比度”按钮：

// ✅ Button with sufficient contrast ratio
Button(
    onClick = { },
    colors = ButtonDefaults.buttonColors(
        containerColor = MaterialTheme.colorScheme.primary,
        contentColor = MaterialTheme.colorScheme.onPrimary
    )
) {
}

// ❌ Button with poor contrast ratio
Button(
    onClick = { },
    colors = ButtonDefaults.buttonColors(
        containerColor = MaterialTheme.colorScheme.tertiaryContainer,
        contentColor = MaterialTheme.colorScheme.primaryContainer
    )
) {
}Material3Snippets.kt

对比度足够高（左侧）与对比度低（右侧） — **图 20**.鲜明对比（左侧）与低对比度（右侧）

排版无障碍功能

M3 字体比例更新了静态字体斜坡和值，以简化而是动态的规模类别框架，可以跨设备进行扩展。

例如，在 M3 中，可以根据例如手机或平板电脑

大屏设备

Material 提供了有关自适应布局和可折叠设备的指南，以便您构建应用并改善持有大型设备的用户的工效学设计。

Material 提供不同类型的导航来帮助您为大型设备提供更好的用户体验。

您可以详细了解 Android 大屏设备应用质量指南以及请参阅我们的 Reply 示例，了解自适应和无障碍设计。

了解详情

如需详细了解 Compose 中的 Material 主题设置，请查看以下内容资源：