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，請按照這篇指南所述的相同方法操作，特別是：
依附元件
M3 的套件和版本與 M2.5 不同：
M2.5
implementation("androidx.wear.compose:compose-material:1.4.0")
M3
implementation("androidx.wear.compose:compose-material3:1.6.0-alpha03")
請前往 Wear Compose 質感設計 3 版本頁面查看 M3 的最新版本。
Wear Compose Foundation 程式庫 1.6.0-alpha03 版導入了一些新元件，這些元件專為搭配 Material 3 元件使用而設計。同樣地，在 Wear OS 6 (API 級別 36) 以上版本上執行時，SwipeDismissableNavHost Wear Compose Navigation 程式庫也會更新動畫。更新至 Wear Compose Material 3 版本時，建議一併更新 Wear Compose Foundation 和 Navigation 程式庫：
implementation("androidx.wear.compose:compose-foundation:1.6.0-alpha03")
implementation("androidx.wear.compose:compose-navigation:1.6.0-alpha03")
主題
在 M2.5 和 M3 中，主題可組合項的名稱都是 MaterialTheme，但匯入套件和參數並不相同。在 M3 中，Colors 參數已重新命名為 ColorScheme，並導入 MotionScheme 來實作轉場效果。
M2.5
import androidx.wear.compose.material.MaterialTheme
MaterialTheme(
colors = AppColors,
typography = AppTypography,
shapes = AppShapes,
content = content
)
M3
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 類別和相關函式：
M2.5
import androidx.wear.compose.material.Colors
val appColorScheme: Colors = Colors(
// M2.5 Color parameters
)
M3
import androidx.wear.compose.material3.ColorScheme
val appColorScheme: ColorScheme = ColorScheme(
// M3 ColorScheme parameters
)
下表說明 M2.5 和 M3 的主要差異：
M2.5 |
M3 |
|---|---|
|
已重新命名為「 |
13 種顏色 |
28 種顏色 |
無 |
全新的動態色彩主題設定 |
無 |
全新第三種顏色，可呈現更多樣的風格 |
動態色彩主題
M3 的其中一項新功能是動態色彩主題。如果使用者變更錶面顏色，UI 中的顏色也會隨之變更。
使用 dynamicColorScheme 函式實作動態色彩配置，並在動態色彩配置無法使用時，提供 defaultColorScheme 做為備用選項。
@Composable
fun myApp() {
val myColorScheme = myBrandColors()
val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {...}
}
字體排版
M3 的字體排版系統與 M2 不同，且包含下列功能：
- 九種全新文字樣式
- 彈性字型，可自訂不同粗細、寬度和圓度的字體比例
AnimatedText，其中使用彈性字型
M2.5
import androidx.wear.compose.material.Typography
val Typography = Typography(
// M2.5 TextStyle parameters
)
M3
import androidx.wear.compose.material3.Typography
val Typography = Typography(
// M3 TextStyle parameters
)
Flex 字型
設計人員可使用彈性字型，為特定大小指定字型寬度和粗細。
文字樣式
M3 提供下列 TextStyle。M3 各種元件預設會採用這些顏色。
字體排版 |
TextStyle |
|---|---|
螢幕 |
displayLarge、displayMedium、displaySmall |
標題 |
titleLarge、titleMedium、titleSmall |
標籤 |
labelLarge、labelMedium、labelSmall |
內文 |
bodyLarge、bodyMedium、bodySmall、bodyExtraSmall |
數字 |
numeralExtraLarge、numeralLarge、numeralMedium、numeralSmall、numeralExtraSmall |
弧形 |
arcLarge、arcMedium、arcSmall |
形狀
M3 的形狀系統與 M2 不同。形狀參數的數量有所增加，名稱也不同，且分別對應至 M3 元件。可用的形狀大小如下：
- 特小
- 小
- 中
- 大
- 特大
在 Compose 中，這適用於 M2 Shapes 類別和 M3 Shapes 類別：
M2.5
import androidx.wear.compose.material.Shapes
val Shapes = Shapes(
// M2.5 Shapes parameters
)
M3
import androidx.wear.compose.material3.Shapes
val Shapes = Shapes(
// M3 Shapes parameters
)
以「在 Compose 中從 Material 2 遷移至 Material 3」一文中的「形狀」參數對應做為起點。
形狀漸變
M3 推出形狀變形功能：形狀現在會因應互動而變形。
形狀漸變行為適用於多種圓形按鈕，請參閱下列支援形狀漸變的按鈕清單：
按鈕 |
形狀漸變功能 |
|---|---|
|
IconButtonDefaults.animatedShape() 會在按下時為圖示按鈕加上動畫效果 |
|
IconToggleButtonDefaults.animatedShape() 會在按下時為圖示切換按鈕加上動畫，並 IconToggleButtonDefaults.variantAnimatedShapes() 會在按下及勾選/取消勾選時，為圖示切換按鈕加上動畫效果 |
|
TextButtonDefaults.animatedShape() 會在按下時為文字按鈕加上動畫效果 |
|
TextToggleButtonDefaults.animatedShapes() 會在按下時為文字切換按鈕加上動畫效果，而 TextToggleButtonDefaults.variantAnimatedShapes() 則會在按下時為文字切換按鈕加上動畫效果，並檢查/取消檢查 |
元件和版面配置
M3 支援 M2.5 的大多數元件和版面配置。不過，部分 M3 元件和版面配置在 M2.5 中並不存在。此外，部分 M3 元件的變化版本比 M2.5 的同等元件還多。
雖然部分元件需要特別注意，但建議您以下列函式對應做為起點：
以下列出所有 Material 3 元件：
Material 3 |
Material 2.5 同等元件 (如果不是 M3 的新元件) |
|---|---|
新增 |
|
新增 |
|
android.wear.compose.material.Scaffold (搭配 androidx.wear.compose.material3.ScreenScaffold ) |
|
新增 |
|
具有核取方塊切換控制項的 androidx.wear.compose.material.ToggleChip |
|
androidx.wear.compose.material.Chip (僅在不需要背景時) |
|
新增 |
|
新增 |
|
新增 |
|
需要色調按鈕背景時，請使用 androidx.wear.compose.material.Chip |
|
新增 |
|
新增 |
|
新增 |
|
新增 |
|
新增 |
|
具有圓形按鈕切換控制項的 androidx.wear.compose.material.ToggleChip |
|
android.wear.compose.material.Scaffold (搭配 androidx.wear.compose material3.AppScaffold) |
|
androidx.wear.compose.material3.SegmentedCircularProgressIndicator |
新增 |
androidx.wear.compose.material.SwipeToRevealCard 和 androidx.wear.compose.material.SwipeToRevealChip |
|
具有切換開關控制項的 androidx.wear.compose.material.ToggleChip |
|
新增 |
最後，我們列出 Wear Compose Foundation 程式庫中一些相關元件，這些元件首次在 1.6.0-alpha03 版中推出：
Wear Compose Foundation 1.6.0-alpha03 |
|
|---|---|
用於在應用程式中為可組合項加註，追蹤組合的有效部分並協調焦點。 |
|
以 Compose Foundation 元件為基礎建構的水平捲動分頁檢視區塊，並針對 Wear 進行強化，以提升效能並符合 Wear OS 指南。 |
|
垂直捲動分頁器，以 Compose Foundation 元件為基礎建構，並針對 Wear 進行強化，以提升效能並符合 Wear OS 指南。 |
|
可用於取代 |
|
按鈕
M3 的按鈕與 M2.5 不同。M2.5 晶片已由按鈕取代。Button 實作會為 Text、maxLines 和 textAlign 提供預設值。您可以在 Text 元素中覆寫這些預設值。
M2.5
import androidx.wear.compose.material.Chip
//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)
M3
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。
M2.5
import androidx.wear.compose.material.Scaffold
Scaffold {...}
M3
AppScaffold { val navController = rememberSwipeDismissableNavController() SwipeDismissableNavHost( navController = navController, startDestination = "message_list" ) { composable("message_list") { MessageList(onMessageClick = { id -> navController.navigate("message_detail/$id") }) } composable("message_detail/{id}") { MessageDetail(id = it.arguments?.getString("id")!!) } } } } // Implementation of one of the screens in the navigation @Composable fun MessageDetail(id: String) { // .. Screen level content goes here val scrollState = rememberTransformingLazyColumnState() val padding = rememberResponsiveColumnPadding( first = ColumnItemType.BodyText ) ScreenScaffold( scrollState = scrollState, contentPadding = padding ) { scaffoldPaddingValues -> // Screen content goes here // ...
如果您使用 HorizontalPager 和 HorizontalPagerIndicator，可以遷移至 HorizontalPagerScaffold。HorizontalPagerScaffold放置在 AppScaffold 內。AppScaffold 和 HorizontalPagerScaffold 會配置 Pager 的結構，並協調 HorizontalPageIndicator 和 TimeText 元件的轉場效果。
HorizontalPagerScaffold 預設會在畫面中央邊緣顯示 HorizontalPageIndicator，並根據 Pager 是否正在分頁，協調顯示和隱藏 TimeText 和 HorizontalPageIndicator，這取決於 PagerState。
此外，還有新的 AnimatedPage 元件，可根據頁面在 Pager 中的位置，以縮放和半透明效果為頁面加上動畫。
AppScaffold { val pagerState = rememberPagerState(pageCount = { 10 }) val columnState = rememberTransformingLazyColumnState() val contentPadding = rememberResponsiveColumnPadding( first = ColumnItemType.ListHeader, last = ColumnItemType.BodyText, ) HorizontalPagerScaffold(pagerState = pagerState) { HorizontalPager( state = pagerState, ) { page -> AnimatedPage(pageIndex = page, pagerState = pagerState) { ScreenScaffold( scrollState = columnState, contentPadding = contentPadding ) { contentPadding -> TransformingLazyColumn( state = columnState, contentPadding = contentPadding ) { item { ListHeader( modifier = Modifier.fillMaxWidth() ) { Text(text = "Pager sample") } } item { if (page == 0) { Text(text = "Page #$page. Swipe right") } else{ Text(text = "Page #$page. Swipe left and right") } } } } } } } }
最後，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 元件的其他變更，請參閱下表。
M2.5 |
M3 |
|---|---|
|
已移除 |
|
已移除 |
|
已重新命名為「 |
|
已移除 |
|
已移除 |
|
已移除 |
|
已移除 |
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
val columnState = rememberTransformingLazyColumnState() val contentPadding = rememberResponsiveColumnPadding( first = ColumnItemType.ListHeader, last = ColumnItemType.Button, ) val transformationSpec = rememberTransformationSpec() ScreenScaffold( scrollState = columnState, contentPadding = contentPadding ) { contentPadding -> TransformingLazyColumn( state = columnState, contentPadding = contentPadding ) { item { ListHeader( modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec), transformation = SurfaceTransformation(transformationSpec) ) { Text(text = "Header") } } // ... other items item { Button( modifier = Modifier.fillMaxWidth().transformedHeight(this, transformationSpec), transformation = SurfaceTransformation(transformationSpec), onClick = { /* ... */ }, icon = { Icon( imageVector = Icons.Default.Build, contentDescription = "build", ) }, ) { Text( text = "Build", maxLines = 1, overflow = TextOverflow.Ellipsis, ) } } } }
實用連結
如要進一步瞭解如何在 Compose 中從 M2.5 遷移至 M3，請參閱下列其他資源。