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

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

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

字體排版

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

• 九種新的文字樣式
• Flex 字型，可根據不同的粗細、寬度和圓弧度自訂字型比例

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

Flex 字型可讓設計人員為特定大小指定字型寬度和粗細。

文字樣式

以下 TextStyles 可在 M3 中使用。這些預設會由 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 的大多數元件和版面配置。不過，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 種尺寸：XS、S、M 和 L。EdgeButton 實作會根據可自訂的大小，為 maxLines 提供預設值。

如果您使用 TransformingLazyColumn 和 ScalingLazyColumn，請將 EdgeButton 傳遞至 ScreenScaffold，以便進行變形，並隨著捲動變更形狀。請參閱下方程式碼，瞭解如何搭配 ScreenScaffold 和 TransformingLazyColumn 使用 EdgeButton。

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，並為每個 Screen 使用 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
    }
}

如果您使用的是搭配 HorizontalPagerIndicator 的 HorizontalPager，可以遷移至 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，並在組合中記住該 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 程式碼研究室

API 參考資料和原始碼

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

設計

• 設計指南