Material 3 Expressive 是新一代 Material Design。它包括更新后的主题和组件，以及动态配色等个性化功能。

本指南重点介绍如何针对应用从 Wear Compose Material 2.5 (androidx.wear.compose) Jetpack 库迁移到 Wear Compose Material 3 (androidx.wear.compose.material3) Jetpack 库。

方法

如需将应用代码从 M2.5 迁移到 M3，请遵循 Compose Material 迁移手机指南中所述的方法，具体而言：

• 您不应长期在一个应用中同时使用 M2.5 和 M3
• 采用分阶段方法

依赖项

M3 有单独的 M2.5 软件包和版本：

implementation("androidx.wear.compose:compose-material:1.4.0")

implementation("androidx.wear.compose:compose-material3:1.5.0-beta01")

如需了解最新版本，请参阅 Wear Compose Material 3 版本页面。

Wear Compose Foundation 库版本 1.5.0-beta01 引入了一些旨在与 Material 3 组件搭配使用的新组件。同样，在 Wear OS 6（API 级别 36）或更高版本上运行时，Wear Compose Navigation 库中的 SwipeDismissableNavHost 具有更新后的动画。更新到 Wear Compose Material 3 版本时，我们建议您同时更新 Wear Compose Foundation 和 Navigation 库：

implementation("androidx.wear.compose:compose-foundation:1.5.0-beta01")
implementation("androidx.wear.compose:compose-navigation:1.5.0-beta01")

主题

在 M2.5 和 M3 中，主题可组合项的名称均为 MaterialTheme，但导入软件包和参数各不相同。在 M3 中，Colors 参数已重命名为 ColorScheme，并引入了 MotionScheme 以实现转换。

import androidx.wear.compose.material.MaterialTheme

MaterialTheme(
        colors = AppColors,
        typography = AppTypography,
        shapes = AppShapes,
        content = content
)

import androidx.wear.compose.material3.MaterialTheme

MaterialTheme(
        colorScheme = AppColorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        motionScheme = AppMotionScheme,
        content = content
)

颜色

M3 中的颜色系统与 M2.5 有显著的差异。颜色参数的数量有所增加，使用不同的名称，而且与 M3 组件的映射方式也不同。在 Compose 中，这适用于 M2.5 Colors 类、M3 ColorScheme 类和相关函数：

import androidx.wear.compose.material.Colors

val appColorScheme: Colors = Colors(
   // M2.5 Color parameters
)

import androidx.wear.compose.material3.ColorScheme

val appColorScheme: ColorScheme = ColorScheme(
   // M3 ColorScheme parameters
)

下表介绍了 M2.5 和 M3 之间的主要区别：

动态配色主题

动态配色主题是 M3 中的一项新功能。如果用户更改表盘颜色，界面中的颜色也会随之更改。

使用 dynamicColorScheme 函数实现动态配色方案，并提供 defaultColorScheme 作为后备方案，以防动态配色方案不可用。

@Composable
fun myApp() {
  val myColorScheme = myBrandColors()
  val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
  MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {...}
}

排版

M3 采用与 M2 不同的排版系统，其中包含以下功能：

• 九种新的文本样式
• Flex 字体，可针对不同的粗细、宽度和圆度自定义类型比例

• AnimatedText，使用 flex 字体

import androidx.wear.compose.material.Typography

val Typography = Typography(
   // M2.5 TextStyle parameters
)

import androidx.wear.compose.material3.Typography

val Typography = Typography(
   // M3 TextStyle parameters
)

Flex 字体

借助 Flex 字体，设计师可以为特定大小指定类型宽度和粗细。

文本样式

M3 中提供以下 TextStyles。M3 的各种组件默认采用这些配置。

形状

M3 采用与 M2 不同的形状系统。形状参数数量有所增加，其命名方式有所不同，而且它们与 M3 组件的映射方式也不同。可用的形状尺寸如下：

• 超小
• 小
• 中号
• 大
• 超大

在 Compose 中，这适用于 M2 Shapes 类和 M3 Shapes 类：

import androidx.wear.compose.material.Shapes

val Shapes = Shapes(
   // M2.5 Shapes parameters
)

import androidx.wear.compose.material3.Shapes

val Shapes = Shapes(
   // M3 Shapes parameters
)

从在 Compose 中从 Material 2 迁移至 Material 3 中使用形状参数映射作为起点。

形状变形

M3 引入了形状变形：形状现在会根据互动而变形。

形状变形行为可作为许多圆形按钮的变体使用，如下所示：

组件和布局

M2.5 中的大多数组件和布局在 M3 中均具有可用性。不过，M2.5 中不存在某些 M3 组件和布局。此外，M3 中的一些组件的变体也比 M2.5 中的变体更多。

尽管某些组件需要特别加以注意，但建议从以下函数映射入手：

以下是所有 Material 3 组件的完整列表：

最后，下面列出了 Wear Compose Foundation 库版本 1.5.0-beta01 中的部分相关组件：

按钮

M3 中的按钮不同于 M2.5。M2.5 条状标签已被按钮取代。Button 实现会为 Text maxLines 和 textAlign 提供默认值。这些默认值可以在 Text 元素中替换。

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

import androidx.wear.compose.material3.Button

//M3 Buttons
Button(...)
CompactButton(...)
IconButton(...)
TextButton(...)

M3 还包含新的按钮变体。请查看 Compose Material 3 API 参考文档概览。

M3 引入了一个新按钮：EdgeButton。EdgeButton 有 4 种不同的尺寸：超小号、小号、中号和大号。EdgeButton 实现会根据可自定义的大小为 maxLines 提供默认值。

如果您使用的是 TransformingLazyColumn 和 ScalingLazyColumn，请将 EdgeButton 传递给 ScreenScaffold，以便它发生变形，随着滚动而改变形状。请参阅以下代码，了解如何将 EdgeButton 与 ScreenScaffold 和 TransformingLazyColumn 搭配使用。

import androidx.wear.compose.material3.EdgeButton
import androidx.wear.compose.material3.ScreenScaffold

ScreenScaffold(
   scrollState = state,
   contentPadding = contentPadding,
   edgeButton = {
      EdgeButton(...)
   }
){ contentPadding ->
   TransformingLazyColumn(state = state, contentPadding = contentPadding,){
   // additional code here
   }
}

Scaffold

M3 中的 Scaffold 不同于 M2.5。在 M3 中，AppScaffold 和新的 ScreenScaffold 可组合项取代了 Scaffold。AppScaffold 和 ScreenScaffold 用于布局界面结构，并协调 ScrollIndicator 和 TimeText 组件的转换。

AppScaffold 允许静态屏幕元素（例如 TimeText）在应用内转换（例如滑动关闭）期间保持可见。它为主要应用内容提供了一个槽位，该内容通常由导航组件（例如 SwipeDismissableNavHost）提供

您可以为 activity 声明一个 AppScaffold，并为每个界面使用一个 ScreenScaffold。

import androidx.wear.compose.material.Scaffold

Scaffold {...}

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold

AppScaffold {
   // Define the navigation hierarchy within the AppScaffold,
   // such as using SwipeDismissableNavHost.
   SwipeDismissableNavHost(...) {
      composable("home") {
         HomeScreen()
      }
      //other screens
   }
}
fun HomeScreen() {
    val scrollState = rememberScrollState()
    ScreenScaffold(scrollState = scrollState) {
    //rest of the screen code
    }
}

如果您将 HorizontalPager 与 HorizontalPagerIndicator 搭配使用，则可以迁移到 HorizontalPagerScaffold。HorizontalPagerScaffold 放置在 AppScaffold 中。AppScaffold 和 HorizontalPagerScaffold 用于布局 Pager 的结构，并协调 HorizontalPageIndicator 和 vTimeText 组件的转换。

默认情况下，HorizontalPagerScaffold 会在屏幕中心显示 HorizontalPageIndicator，并根据 Pager 是否正在分页来协调显示/隐藏 TimeText 和 HorizontalPageIndicator，这由 PagerState 决定。

还有一个新的 AnimatedPage 组件，可根据页面的位置，为其在 Pager 中添加缩放和半透明效果动画。

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.HorizontalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })

    HorizontalPagerScaffold(pagerState = pagerState) {
       HorizontalPager(
          state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold {
…
   }
}

最后，M3 引入了 VerticalPagerScaffold，其遵循与 HorizontalPagerScaffold 相同的模式：

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.VerticalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

AppScaffold {
   val pagerState = rememberPagerState(pageCount = { 10 })

   VerticalPagerScaffold(pagerState = pagerState) {
      VerticalPager(
         state = pagerState
      ) { page ->
             AnimatedPage(pageIndex = page, pagerState = pagerState){
                ScreenScaffold {
        …
   }
}

占位符

M2.5 和 M3 之间有一些 API 变更。Placeholder.PlaceholderDefaults 现在提供两个修饰符：

• Modifier.placeholder，系统会绘制此图标，而不是绘制尚未加载的内容
• 占位符闪烁效果 Modifier.placeholderShimmer，用于提供占位符闪烁效果，该效果会在等待数据加载时在动画循环中运行。

如需了解对 Placeholder 组件进行的其他更改，请参阅下文。

SwipeDismissableNavHost

SwipeDismissableNavHost 是 wear.compose.navigation 的一部分。将此组件与 M3 搭配使用时，M3 MaterialTheme 会更新 LocalSwipeToDismissBackgroundScrimColor 和 LocalSwipeToDismissContentScrimColor。

TransformingLazyColumn

TransformingLazyColumn 是 wear.compose.lazy.foundation 的一部分，它支持在滚动过程中对列表项进行缩放和变形动画，从而提升用户体验。

与 ScalingLazyColumn 类似，它提供 rememberTransformingLazyColumnState() 来创建在各种组合中记住的 TransformingLazyColumnState。

如需添加缩放和变形动画，请在每个列表项中添加以下代码：

• Modifier.transformedHeight，可让您使用 TransformationSpec 计算项的转换高度，除非您需要进一步自定义，否则可以使用 rememberTransformationSpec()。
• 一个 SurfaceTransformation

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.material3.SurfaceTransformation
import androidx.wear.compose.material3.lazy.rememberTransformationSpec
import androidx.wear.compose.material3.lazy.transformedHeight
import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
import androidx.wear.compose.foundation.lazy.TransformingLazyColumn

val state = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
AppScaffold {
   ScreenScaffold(state) { contentPadding ->
      TransformingLazyColumn(state = state, contentPadding = contentPadding) {
         items(count = 50) {
            Button(
               onClick = {},
               modifier =
                        Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                        transformation = SurfaceTransformation(transformationSpec),
                    ) {
                        Text("Item $it")
                    }
                }
            }
        }
    }

实用链接

如需详细了解如何在 Compose 中从 M2.5 迁移至 M3，请参阅下面列出的其他资源。

示例

GitHub 上 Material3 分支中的 Wear OS 示例

Compose for Wear OS Codelab

API 参考文档和源代码

• Compose Material 3 API 参考文档
• 源代码中的 Compose Material 3 示例

设计

• 设计指南