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-beta05")

請前往 Wear Compose 質感設計 3 版本頁面查看 M3 的最新版本。

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-beta05")
implementation("androidx.wear.compose:compose-navigation:1.5.0-beta05")

主題設定

在 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 的其中一項新功能是動態色彩主題。如果使用者變更錶面顏色，UI 中的顏色也會隨之變更。

使用 dynamicColorScheme 函式實作動態色彩配置，並在動態色彩配置無法使用時，提供 defaultColorScheme 做為備用選項。

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

字體排版

M3 的字體排版系統與 M2 不同，且包含下列功能：

• 九種全新文字樣式
• 彈性字型，可自訂不同粗細、寬度和圓度的字體比例

• AnimatedText，其中使用彈性字型

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 字型

設計人員可使用彈性字型，為特定大小指定字型寬度和粗細。

文字樣式

M3 提供下列 TextStyle。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 推出形狀變形功能：形狀現在會因應互動而變形。

形狀變形行為適用於多個圓形按鈕的變體，詳情請參閱下文：

元件和版面配置

M3 支援 M2.5 的大多數元件和版面配置。不過，部分 M3 元件和版面配置在 M2.5 中並不存在。此外，部分 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 種尺寸：XS、S、M 和 L。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 和 TimeText 元件的轉場效果。

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，並在組合中保留該 TransformingLazyColumnState。

如要新增縮放和變形動畫，請在每個清單項目中加入下列項目：

• Modifier.transformedHeight，讓您使用 TransformationSpec 計算項目的轉換高度，除非需要進一步自訂，否則可以使用 rememberTransformationSpec()。
• A 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 程式碼研究室
• Jetcaster 範例

API 參考資料和原始碼

• Compose Material 3 API 參考資料
• 原始碼中的 Compose 質感設計 3 範例

設計

• 設計指南