Compose Material 3

Compose Material 3

用户指南  代码示例

API 参考文档
androidx.compose.material3
（如需查看所有 Compose 软件包，请参阅 API 参考文档）

使用 Material Design 3（下一代 Material Design）组件构建 Jetpack Compose 界面。Material 3 包括更新后的主题和组件，以及动态配色等 Material You 个性化功能，旨在与新的 Android 12 视觉风格和系统界面相得益彰。

最近更新时间	稳定版	候选版本	Beta 版	Alpha 版
2022 年 6 月 1 日	-	-	-	1.0.0-alpha13

结构

Compose 由 androidx 中的 7 个 Maven 组 ID 构成。每个组都包含一套特定用途的功能，并各有专属的版本说明。

下表介绍了各个组及指向其版本说明的链接。

组	说明
compose.animation	在 Jetpack Compose 应用中构建动画，丰富用户的体验。
compose.compiler	借助 Kotlin 编译器插件，转换 @Composable functions（可组合函数）并启用优化功能。
compose.foundation	使用现成可用的构建块编写 Jetpack Compose 应用，还可扩展 Foundation 以构建您自己的设计系统元素。
compose.material	使用现成可用的 Material Design 组件构建 Jetpack Compose UI。这是更高层级的 Compose 入口点，旨在提供与 www.material.io 上描述的组件一致的组件。
compose.material3	使用 Material Design 3（下一代 Material Design）组件构建 Jetpack Compose 界面。Material 3 包括更新后的主题和组件，以及动态配色等 Material You 个性化功能，旨在与新的 Android 12 视觉风格和系统界面相得益彰。
compose.runtime	Compose 的编程模型和状态管理的基本构建块，以及 Compose 编译器插件针对的核心运行时。
compose.ui	与设备互动所需的 Compose UI 的基本组件，包括布局、绘图和输入。

声明依赖项

如需添加 Compose 的依赖项，您必须将 Google Maven 代码库添加到项目中。如需了解详情，请参阅 Google 的 Maven 代码库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.compose.material3:material3:1.0.0-alpha13"
    implementation "androidx.compose.material3:material3-window-size-class:1.0.0-alpha13"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material3:material3:1.0.0-alpha13")
    implementation("androidx.compose.material3:material3-window-size-class:1.0.0-alpha13")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库的改进有自己的见解，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

1.0 版

注意：androidx.compose.material3 目前为 Alpha 版。此 API 随时可能发生变化，因此不应视为最终版本。

版本 1.0.0-alpha13

2022 年 6 月 1 日

发布了 androidx.compose.material3:material3:1.0.0-alpha13 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha13。版本 1.0.0-alpha13 中包含这些提交内容。

API 变更

• 支持在配置更改时保持顶部应用栏的位置。（I10459、b/216160958）

版本 1.0.0-alpha12

2022 年 5 月 18 日

发布了 androidx.compose.material3:material3:1.0.0-alpha12 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha12。版本 1.0.0-alpha12 中包含这些提交内容。

bug 修复

• 滑块父项的宽度现在可以为 0。(b/231707291)

版本 1.0.0-alpha11

2022 年 5 月 11 日

发布了 androidx.compose.material3:material3:1.0.0-alpha11 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha11。版本 1.0.0-alpha11 中包含这些提交内容。

新功能

• 向 Material 3 添加了 RangeSlider (I18e38)
• 添加了对 Material3 AssistChip 和 InputChip 的支持 (I0d25a)
• 添加了对 Material3 FilterChip 和 SuggestionChip 的支持 (I9fdf3)

API 变更

• 将 TextFieldDefaults.BorderStroke 可组合项（用于在 OutlinedTextField 中绘制边框描边）重命名为 TextFieldDefaults.BorderBox。(I5f295)
• 切换 m3 视觉变化 (Iab30e)
• 允许将颜色传递给标准图标按钮。(Ia2445)

bug 修复

• 向 material3/Scaffold 添加了 lint 检查，以确保使用了内部内边距（I72293、b/226951418）

版本 1.0.0-alpha10

2022 年 4 月 20 日

发布了 androidx.compose.material3:material3:1.0.0-alpha10 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha10。版本 1.0.0-alpha10 中包含这些提交内容。

新功能

• material3-window-size-class 是一个为窗口大小类别提供支持的新库：一组主观的视口划分点，您可以根据它们设计、开发和测试可调整大小的应用布局。您可以使用 calculateWindowSizeClass 检索窗口大小类别实例，该实例可用于确定界面的显示方式，例如针对较大的窗口显示导航栏（而非底部导航栏）。如需了解详情并查看用法示例，请参阅 WindowSizeClass 的 API 参考文档。如需详细了解窗口大小类别的定义，请参阅有关支持不同屏幕尺寸的公开指南。

API 变更

• 为 BottomAppBar 添加了默认的 FAB 高度，从带有 FAB 的 BottomAppBar 中移除了尾随 lambda。(I92c47)
• 添加了 Material3 FilledIconButton、FilledTonalIconButton 和 OutlinedIconButton。(Ib2bda)
• 更新了 Material 3 Snackbar API，以接受可选操作和关闭操作的颜色值。(Ibe4b4)
• PointerInputChange 中已废弃部分使用操作（down OR 位置）。您可以借助 consume() 完全使用此更改。您可以使用 isConsumed 来确定其他人之前是否使用过此更改。
• PointerInputChange::copy() 现在始终会创建浅层副本。这意味着，在使用完其中一个副本后，将会使用 PointerInputChange 的副本。如需创建未绑定的 PointerInputChange，请改用构造函数。（Ie6be4、b/225669674）
• 更改了 Cards API，以通过 CardColors 接口接收容器颜色和内容颜色，并支持可点击卡片的停用状态。(I927df)
• Material 3 文本字段中的参数 backgroundColor 已重命名为 containerColor，以提高与其他组件的一致性。(I6fbd9)

bug 修复

• 更新了标准 IconButton，使其符合 Material3 规范。(I09eab)
• 将 Material3 Scaffold 的顶部栏高度移动到传递给内容的内边距，使内容能够在顶部应用栏下方呈现。如果 PaddingValues 被忽略，顶部栏可能会遮盖内容。（I83cbc、b/217776202）

版本 1.0.0-alpha09

2022 年 4 月 6 日

发布了 androidx.compose.material3:material3:1.0.0-alpha09。版本 1.0.0-alpha09 中包含这些提交内容。

新功能

• 添加了 Material 3 Switch API (I2c3ad)

API 变更

• 新增了对包含文本字段的下拉菜单（即“公开下拉菜单”或“组合框”）的支持。(I1b832)
• 向 MaterialTheme 和 Shape 子系统添加了形状参数。(I37426)
• 向 ExtendedFloatingActionButton 添加了一个扩展参数，用于控制 FAB 处于展开状态还是收起状态，并在每种状态之间添加了动画效果。针对处于扩展状态的 FAB 添加了 Extended FAB 过载，并为不带图标的 ExtendedFAB 添加了尾随文本。(Iba7f1)

版本 1.0.0-alpha08

2022 年 3 月 23 日

发布了 androidx.compose.material3:material3:1.0.0-alpha08。版本 1.0.0-alpha08 中包含这些提交内容。

新功能

• 新增了对 Material 3 文本字段的支持。（I795cc、b/199377790）

API 变更

• 为菜单添加了默认分隔线 (I01374)
• 向 ColorScheme 类添加了 surfaceTint 颜色参数。(I2f558)

bug 修复

• 修复了 Material3 按钮，以从 MaterialTheme 读取其默认文本样式值。(Ie62fc)

版本 1.0.0-alpha07

2022 年 3 月 9 日

发布了 androidx.compose.material3:material3:1.0.0-alpha07。版本 1.0.0-alpha07 中包含这些提交内容。

API 变更

• 更新了用于恢复可点击 Surface 的重载函数的 Material 3 Surface API，并添加了一个函数来支持可选择和可切换的 Surface。(I4bf18)
• LazyVerticalGrid 和 LazyHorizontalGrid 现已稳定。(I307c0)
• LazyVerticalGrid/LazyHorizontalGrid 和所有相关 API 已移至 .grid 子软件包。请将您的导入从 androidx.compose.foundation.lazy 更新为 androidx.compose.foundation.lazy.grid。(I2d446)
• 恢复了之前仅依赖于 WindowInsetsControllerCompat 的 View 的变更，再次需要一个 Window，这对于管理某些窗口标记是必需的。废弃了 ViewCompat.getWindowInsetsController，改为使用 WindowCompat.getInsetsController，以确保使用正确的 Window（例如，如果 View 位于对话框中）。（I660ae、b/219572936）
• 新增了 LazyVerticalGrid API，用于定义交叉轴的大小 (I17723)

bug 修复

• 更新了 Card API，以跟踪 Surface API 的更改 (I3c8b9)

版本 1.0.0-alpha06

2022 年 2 月 23 日

发布了 androidx.compose.material3:material3:1.0.0-alpha06。版本 1.0.0-alpha06 中包含这些提交内容。

API 变更

• 添加了表示抽屉式导航栏中单个目的地的 NavigationDrawerItem（Ic396f、b/218286829）
• 以实验性 API 的形式添加了 PermanentNavigationDrawer 和 DismissibleNavigationDrawer。这些抽屉式导航栏非常适合大屏幕设备。（I5f8ab、b/218286829）
• 添加了 Material 3 底部应用栏支持 (Ic432a)
• NavigationDrawer 已重命名为 ModalNavigationDrawer（I1807d、b/218286829）
• 添加了 Material 3 滑块类和令牌 (I1ccee)
• 添加了 Tab 实现，请参阅用法示例文档 (Ie0146)

bug 修复

• 修复了 TalkBack 屏幕阅读器线性导航选择空白的顶部应用栏标题的问题。(Id4690)
• 为 FloatingActionButtonDefaults 添加了 IconSize。(Ia71cf)
• 修复了在使用 LazyColumn 添加长文本时隐藏 AlertDialog 按钮的bug。（Ib2cc9、b/216663029）

版本 1.0.0-alpha05

2022 年 2 月 9 日

发布了 androidx.compose.material3:material3:1.0.0-alpha05。版本 1.0.0-alpha05 中包含这些提交内容。

新功能

添加了 Material Design 3 组件

• 下拉菜单
  • DropdownMenu、DropdownMenuItem
• 卡片
  • Card、OutlinedCard、ElevatedCard

API 变更

• 弃用了使用 onClick 回调的 Surface 函数。应使用 InteractionSource 和 Modifier.clickable() 创建可点击界面。(I211c6)
• 为悬浮操作按钮添加了按下和聚焦高程支持。(Ibb584)
• 将 Surface API 更改为接收 InteractionSource，允许控制其在不同状态下的外观。(Iafbc8)

bug 修复

• 在动态配色方案中添加了缺失的第三色（I456c4、b/214588434）

版本 1.0.0-alpha04

2022 年 1 月 26 日

发布了 androidx.compose.material3:material3:1.0.0-alpha04。版本 1.0.0-alpha04 中包含这些提交内容。

API 变更

• 向作为现有方法的无复杂逻辑重载的方法添加了 NonRestartableComposable。这会减少编译器针对在调用的内部函数中重复的所有参数生成的 memoization 检查 (equals)。(I90490)
• 添加了 Material 3 分隔线。(Ica5fc)
• 使用实验性 API 注解标记了 Checkbox 和 RadioButton。(Ie44bb)
• 添加了对 Material 3 进度指示器的支持。（Iff232、b/205023841）

bug 修复

• 将已停用的 TextButton's 容器颜色更新为透明（I6b248、b/213339737）

版本 1.0.0-alpha03

2022 年 1 月 12 日

发布了 androidx.compose.material3:material3:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

bug 修复

• 向 Material 3 的 MaterialTheme 中添加了 LocalIndication。(I7ce4e)
• 修复了向复选框应用的圆角半径存在的问题（I38b03、b/175198975、b/202309440）

依赖项更新

• 现在依赖于 Kotlin 1.6.10。

版本 1.0.0-alpha02

2021 年 12 月 1 日

发布了 androidx.compose.material3:material3:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

新功能

• 添加了对复选框和单选按钮的支持。
• 进行了更新，现在与 Kotlin 1.6.0 兼容

API 变更

• 从 Material 3 的 scaffold 中移除了抽屉式导航栏。(I04f51)
• 添加了 Material 3 Checkbox 支持。(Id5542)
• 添加了 Material 3 RadioButton 支持。(I20334)

bug 修复

• 将 IconButton 涟漪效果半径从 40dp 缩减到了 20dp。（I68bbe、b/206674345）
• 移植了 compose.material 中的“Text 字符串快速路径”更改 (I30b03)
• 修复了硬编码按钮始终处于启用状态的 bug。（Iea832、b/205335456）

版本 1.0.0-alpha01

2021 年 10 月 27 日

发布了 androidx.compose.material3:material3:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

Material Design 3 主题和 Material You 动态配色

• MaterialTheme
• 颜色
  • ColorScheme
  • lightColorScheme、darkColorScheme
• 动态配色
  • dynamicLightColorScheme、dynamicDarkColorScheme
• 排版
  • Typography

Material Design 3 组件

• 按钮
  • Button、ElevatedButton、FilledTonalButton、OutlinedButton、TextButton
• FAB 和扩展型 FAB
  • SmallFloatingActionButton、FloatingActionButton、LargeFloatingActionButton、ExtendedFloatingActionButton
• 对话框
  • AlertDialog
• 导航栏
  • NavigationBar
• 抽屉式导航栏
  • NavigationDrawer
• 导航栏
  • NavigationRail
• 顶部应用栏
  • SmallTopAppBar、CenterAlignedTopAppBar、MediumTopAppBar、LargeTopAppBar
• 标记
  • Badge、BadgedBox
• 图标
  • Icon、IconButton
• 文字
  • Text
• 界面
  • Surface
• 布局
  • Scaffold
• 内容颜色
  • LocalContentColor

如需了解详情，请参阅《Compose 中的 Material 主题设置》指南中的“Material Design 3 和 Material You”部分。