Compose Material 3

Compose Material 3

使用手冊  程式碼範例

API 參考資料
androidx.compose.material3
(請參閱所有撰寫套件的 API 參考說明文件)

運用新一代的質感設計 3 元件，建構 Jetpack Compose UI。Material 3 具有新的主題設定和元件，另外還提供了動態色彩等 Material You 個人化功能，與全新的 Android 12 視覺風格及系統 UI 相互呼應。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2022 年 9 月 7 日	-	-	1.0.0-beta02	-

結構

Compose 是由 androidx 中的 7 個 Maven 群組 ID 所組成。每個群組都包含一個指定功能子集，且各有一組專屬的版本資訊。

下表提供各群組的說明和每組版本資訊的連結。

群組	說明
compose.animation	在其 Jetpack Compose 應用程式中建構動畫，以提供豐富的使用者體驗。
compose.compiler	透過 Kotlin 編譯器外掛程式轉換 @Composable 函式，並啟用最佳化功能。
compose.foundation	透過現成可用的建構區塊編寫 Jetpack Compose 應用程式，並擴充基礎以建構您自己的設計系統元件。
compose.material	運用現成可用的質感設計元件建構 Jetpack Compose UI。這是更高層級的 Compose 進入點，用意是確保提供的元件與 www.material.io 上所述元件相符。
compose.material3	運用新一代的質感設計 3 元件，建構 Jetpack Compose UI。質感設計 3 內有新的主題設定和元件，以及動態色彩等 Material You 個人化功能，與全新的 Android 12 視覺風格及系統 UI 呼應。
compose.runtime	Compose 的程式設計模型和狀態管理的基礎建構區塊，以及 Compose Compiler 外掛程式指定的核心執行階段。
compose.ui	與裝置互動所需的 Compose UI 基礎元件，包括版面配置、繪圖及輸入。

宣告依附元件

如要新增 Compose 的依附元件，必須將 Google Maven 存放區新增至您的專案。詳情請參閱「Google 的 Maven 存放區」一節。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

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

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

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

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.2.0-alpha08"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。發現新的問題或有改善這個程式庫的想法時，請告訴我們。建立新的問題之前，請先查看這個程式庫中的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.0 版

1.0.0-beta02 版本

2022 年 9 月 7 日

發布 androidx.compose.material3:material3:1.0.0-beta02 和 androidx.compose.material3:material3-window-size-class:1.0.0-beta02。1.0.0-beta02 版本包含以下修訂項目。

API 變更

• 在 beta01 版中，m3 元件引入的預設元件插邊不再納入 IME 插邊。
• Material3 Scaffold 元件現在擁有 contentWindowInsets 參數，可指定要為內容版面處理的插邊數量。(Icf11a、b/243713323)
• 淘汰實驗性 Material 3 SmallTopAppBar 函式，並引入同等 TopAppBar 函式。請將使用方式遷移至新的函式。(I74404、b/226918634)
• 新增對頂端應用程式列快速滑過和貼齊行為的控制項。(I15c81)
• 從 Divider 中移除 startIndent，將顏色移至最後一個參數。(If7be2)

修正錯誤

• 讓對話方塊在顯示時通知字詞 Dialog，便於 TalkBack 使用者辨識對話方塊。(I857ef)

1.0.0-beta01 版本

2022 年 8 月 24 日

發布 androidx.compose.material3:material3:1.0.0-beta01 和 androidx.compose.material3:material3-window-size-class:1.0.0-beta01。1.0.0-beta01 版本包含以下修訂項目。

API 參考資料

如要查看最新的主題設定、元件和其他可用的可組合項，請參閱 Compose Material 3 API 參考資料總覽。

API 變更

• 更新 Material 3 頂端應用程式列，以呈現完全收合狀態至完全展開狀態。此外，將 TopAppBarDefaults 行為函式更新為 Composables，並針對其頂端應用程式列狀態和動畫規格提供預設值 (I642b3)。
• 更新懸浮動作按鈕 (FAB) 元件簽章以符合介面 API (I3afaa)
• 新增適用於頂端應用程式列、導覽匣、導覽列和邊欄的插邊內建支援機制。無論是單獨使用或與 Scaffold 搭配使用，這些元件都會為開發人員自動處理插邊。注意事項：這項變更不會自動處理狀態列圖示以及狀態列和導覽列的透明度。請繼續手動處理，確保提供最佳的無邊框體驗。(I7e4e6、b/183161866)
• 更新元件預設值以減少 API 介面，藉此提升日後的彈性與效能。(I31820)
• 重新安排方塊和導覽匣工作表參數的順序，藉此在 API 內維持一致性 (I45d0b)
• 將 startIndent 從 Divider 中移除，並將顏色移到最後一個參數 (If7be2)。

1.0.0-alpha16 版本

2022 年 8 月 10 日

發布 androidx.compose.material3:material3:1.0.0-alpha16 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha16。1.0.0-alpha16 版本包含以下修訂項目。

新功能

• 支援在導覽匣中指定自訂寬度。(Ia7f10)

API 變更

• 重新安排 Tab 和 Leading 圖示分頁參數的順序，藉此在 API 內維持一致性 (Ie2637)
• 將 BadgeDefaults 標示為實驗性質。(I98ef3)
• 移除已淘汰的導覽匣函式。(I4f2db)
• 重新安排 Material 3 中 Slider 參數的順序，藉此在 API 內維持一致性 (I0aee7)
• 重新安排 NavigationBar 和 NavigationRail 參數的順序，藉此在 API 內維持一致性 (I51cda)
• 重新安排 Material 3 中的參數順序，藉此在 API 內維持一致性。(If4ae1)
• 重新安排 Material 3 中 Slider 參數的順序，藉此在 API 內維持一致性 (I62673)
• 將 icons 參數重新命名為 actions，藉此與頂端應用程式列保持一致 (Id75be)
• 將 Badge 和 BadgedBox 標示為實驗性質，因為目前仍可大量使用錨點對齊。(I1712e, b/236524516)
• 將圖示按鈕變化版本的 @ExperimentalMaterial3Api 註解變更為 @OptIn (I070b5)
• 將導覽匣的內容與自身的可組合項區隔開來，以便支援指定自訂寬度。(Ia7f10)
• 從 MenuDefaults 和 TabDefaults 移除 Divider (I4e33c)

1.0.0-alpha15 版本

2022 年 7 月 27 日

發布 androidx.compose.material3:material3:1.0.0-alpha15 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha15。1.0.0-alpha15 版本包含以下修訂項目。

新功能

• 允許從頂端應用程式列本身拖曳該列。(I65c00, b/205873416)

API 變更

• 更新 FilterChip 和 ElevatedFilterChip API 以移除 selectedIcon 運算單元，並推廣重複使用 leadingIcon 以顯示所選狀態。(Ie5dc2)
• 新增紗罩遮擋和外框變化版本的顏色角色。(Id6d54)
• 修正可組合預設值的命名慣例。(I62b27)
• 將 ListItemDefaults 和 ListItemColors 標示為實驗性質。(I1f3ec)
• 變更頂端應用程式列 API，以更準確地反映其狀態屬性的意義。此外，請將頂端應用程式列 API 標示為實驗功能。(Ic0ad8)
• 文字選取顏色現已新增至 TextFieldColors，以提高曝光度。(Iba1b8)
• 新增 ButtonDefault.ButtonWithIconContentPadding 以與包含圖示的按鈕搭配使用。(I2bf9c)
• 文字欄位已標示為實驗性質，讓日後的 API 變更更具彈性。(I127b5)
• 已從 Checkbox 函式中移除 @ExperimentalMaterial3Api 註解。(I5eefc)
• 已從 RadioButton 函式中移除 @ExperimentalMaterial3Api 註解。(I17e2a)
• 已從非互動式資訊卡中移除 @ExperimentalMaterial3Api 註解。(I9bd49)
• 更新各種元件預設物件，包括顏色、形狀等。(I96e11)

修正錯誤

• 已從輸入方塊範例中移除無法運作的結尾圖示，以免在目錄應用程式中混淆使用者 (I9846a)。

1.0.0-alpha14 版本

2022 年 6 月 29 日

發布 androidx.compose.material3:material3:1.0.0-alpha14 和 androidx.compose.material3:material3-window-size-class:1.0.0-alpha14。1.0.0-alpha14 版本包含以下修訂項目。

新功能

• 新增 M3 清單實作，請查看說明文件中的使用範例 (Id7a20)

API 變更

• 將參數名稱從值變更為 RangeSlider 中的值 (I3b79a)
• API 變更為 InputChip 實作，以根據質感設計規格支援可選取狀態 針對特定停用的狀態於 FilterChip 提供額外支援。(I55244、b/235792432)
• 新增 BottomAppBar 預設 FAB (Ida4c8)
• 已新增 ColorScheme.surfaceColorAtElevation (Id41af)
• Compose 程式庫中的介面現為使用 jdk8 預設介面方法建構 (I5bcf1)
• WindowWidthSizeClass 和 WindowHeightSizeClass 現在實作 Comparable，使其得以使用運算子 (<、<=、>=、>) 和其他 API 比較。(I747d0)

修正錯誤

• 更新標記範例以提供更多實質的內容說明。(I10b9d)
• 在 Material 3 目錄的主題挑選工具中加入使用系統字型大小的選項。(I10605)
• 加入標記的程式碼範例和不確定進度指標。(I8fbe0)

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 版本包含以下修訂項目。

修正錯誤

• 滑桿父項現可設定 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 版本包含以下修訂項目。

新功能

• 將 RangeSlider 新增至 Material 3 (I18e38)
• 新增 Material3 AssistChip 和 InputChip 支援 (I0d25a)
• 新增 Material3 FilterChip 和 SuggestionChip 支援 (I9fdf3)

API 變更

• 已重新命名 TextFieldDefaults.BorderStroke 可組合項，該組合項用於繪製 OutlinedTextField 至 TextFieldDefaults.BorderBox 的框線。(I5f295)。
• 切換 m3 視覺效果 (Iab30e)
• 允許將顏色傳遞至標準圖示按鈕 (Ia2445)。

修正錯誤

• 將 Lint 檢查項目新增至 material3/Scaffold，以確保使用內部邊框間距 (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 高度，從 BottomAppBar 移除 FAB 結尾的 lambda。(I92c47)
• 新增 Material3 FilledIconButton、FilledTonalIconButton 和 OutlinedIconButton。(Ib2bda)
• 更新 Material 3 Snackbar API，接受選擇性動作和關閉動作的顏色值。(Ibe4b4)
• 已從 PointerInputChange 淘汰部分使用功能 (向下或定位)。可使用 consume() 徹底使用變更。可使用 isConsumed 判斷其他使用者是否曾經使用過該變更。
• PointerInputChange::copy() 現在會一律建立淺層複本。這表示只要使用一份複本，系統就會使用 PointerInputChange 的複本。如要建立未繫結的 PointerInputChange，請改用建構函式。(Ie6be4、b/225669674)
• 變更 Cards API，透過 CardColors 介面接收容器和內容顏色，並支援已停用的可點擊資訊卡狀態。(I927df)
• 將 Material 3 文字欄位中的 backgroundColor 參數重新命名為 containerColor，以便改善與其他元件的一致性。(I6fbd9)

修正錯誤

• 更新標準 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)
• 將 surfaceTint 色彩參數新增至 ColorScheme 類別。(I2f558)

修正錯誤

• 修正 Material3 按鈕，以便從 MaterialTheme 讀取其預設文字樣式值。(Ie62fc)

1.0.0-alpha07 版本

2022 年 3 月 9 日

發布 androidx.compose.material3:material3:1.0.0-alpha07。1.0.0-alpha07 版本包含以下修訂項目。

API 變更

• 更新 Material 3 Surface API，為可點擊式 Surface 復原超載函式，以及新增了函式，以便支援可選取和可切換的 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)

修正錯誤

• 更新 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)
• 已將 PermanentNavigationDrawer 和 DismissibleNavigationDrawer 新增為實驗性 API。這些導覽匣非常適合大螢幕裝置使用。(I5f8ab、b/218286829)
• 新增了 Material 3 底部應用程式列支援 (Ic432a)
• NavigationDrawer 已重新命名為 ModalNavigationDrawer (I1807d、b/218286829)
• 已新增 Material 3 Slider 類別和權杖 (I1ccee)
• 已新增 Tab 實作，請查看說明文件中的使用範例 (Ie0146)

修正錯誤

• 修正了一個問題，即 TalkBack 螢幕閱讀器線性導覽選取了空白應用程式列標題。(Id4690)
• 已將 IconSize 新增至 FloatingActionButtonDefaults。(Ia71cf)
• 修正了當新增帶有 LazyColumn 的長文字時隱藏 AlertDialog 按鈕的問題。(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
• 資訊卡
  • 資訊卡、OutlinedCard、ElevatedCard

API 變更

• 已淘汰 Surface 函式，該函式會接收 onClick 回呼。應使用 InteractionSource 和 Modifier.clickable() 來建立可點擊途徑。(I211c6)
• 新增了支援 FAB 的點按式和聚焦式提升權限。(Ibb584)
• 變更了 Surface API，以便接收 InteractionSource，這可以控制其在不同狀態下的外觀。(Iafbc8)

修正錯誤

• 在動態顏色配置中新增了缺少的第三級顏色 (I456c4、b/214588434)

1.0.0-alpha04 版本

2022 年 1 月 26 日

發布 androidx.compose.material3:material3:1.0.0-alpha04。1.0.0-alpha04 版本包含以下修訂項目。

API 變更

• 將 NonRestartableComposable 新增至屬於現有方法超載且無複雜邏輯的方法。如此一來，對於呼叫內部函式中重複的所有參數，可減少編譯器產生的記憶檢查 (等於)。(I90490)
• 已新增 Material 3 分割線。(Ica5fc)
• 使用實驗性 API 註解標記 Checkbox 和 RadioButton。(Ie44bb)
• 已新增對 Material 3 進度指標的支援。(Iff232、b/205023841)

修正錯誤

• 將已停用的 TextButton's 容器顏色更新為透明 (I6b248，b/213339737)

1.0.0-alpha03 版本

2022 年 1 月 12 日

發布 androidx.compose.material3:material3:1.0.0-alpha03。1.0.0-alpha03 版本包含以下修訂項目。

修正錯誤

• 將 LocalIndication 新增至 Material 3 的 MaterialTheme。(I7ce4e)
• 修正適用於 Checkbox 的圓角半徑 (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 版本包含以下修訂項目。

新功能

• 新增對 Checkbox 和 Radiobutton 的支援。
• 已更新為可與 Kotlin 1.6.0 相容

API 變更

• 從 Material 3 的鷹架中移除導覽匣。(I04f51)
• 新增 Material 3 Checkbox 支援。(Id5542)
• 新增 Material 3 RadioButton 支援。(I20334)

修正錯誤

• 將 IconButton 漣漪半徑從 40 dp 降到 20 dp。(I68bbe、b/206674345)
• Text 的通訊埠字串快速路徑從 compose.material 中進行變更 (I30b03)
• 已修正，但是系統總是啟用硬式編碼按鈕。(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 一節。