本頁面由 Cloud Translation API 翻譯而成。

Compose Material 3 自動調整式

API 參考資料
androidx.compose.material3.adaptive

使用 Material 3 自動調整式程式庫建立自動調整式 UI，根據目前的視窗設定 (例如視窗大小類別或裝置姿勢) 自動調整。這個程式庫提供預設的架構實作項目，以及建立自訂體驗所需的建構模塊可組合項。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2025 年 7 月 2 日	1.1.0	-	-	1.2.0-alpha08

宣告依附元件

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

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

Groovy

dependencies {
    implementation "androidx.compose.material3.adaptive:adaptive:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-layout:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-navigation:1.2.0-alpha08"
}

Kotlin

dependencies {
    implementation("androidx.compose.material3.adaptive:adaptive:1.2.0-alpha08")
    implementation "androidx.compose.material3.adaptive:adaptive-layout:1.2.0-alpha08"
    implementation "androidx.compose.material3.adaptive:adaptive-navigation:1.2.0-alpha08"
}

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

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

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

Compose Material3 自動調整式版面配置 1.2 版

1.2.0-alpha08 版

2025 年 7 月 2 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha08。1.2.0-alpha08 版包含這些修訂項目。

1.2.0-alpha07 版

2025 年 6 月 18 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha07。1.2.0-alpha07 版包含這些修訂項目。

API 變更

讓 currentWindowAdaptiveInfo() 函式支援大型和特大型視窗寬度大小類別，並將 calculatePosture() 和 currentWindowDpSize() 函式升級為穩定版。(I92e97)

1.2.0-alpha06 版本

2025 年 5 月 20 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha06。1.2.0-alpha06 版包含這些修訂項目。

新功能

預設窗格架構指令計算函式現在支援 L 和 XL 視窗寬度大小類別。

API 變更

讓 Modifier.paneExpansionDraggable 提供預設無障礙語意，並將相關 API 升級為穩定版。(Idb818)
支援使用懸浮窗格拖曳調整大小 (Idadd3)
支援懸浮窗格的半透明遮罩 (I9b091)

1.2.0-alpha05 版本

2025 年 5 月 7 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha05。1.2.0-alpha05 版包含這些修訂項目。

新功能

Material3 適應性版面配置現在支援 Levitated 適應策略，可將窗格變成浮動彈出式視窗。

API 變更

讓目前的視窗大小函式支援多平台 (Ie4172)
為懸浮窗格導入窗格動作 (Ic9dc3)
導入適應性升降策略 (I1ba7c)

修正錯誤

修正自適應範例中的協同程式範圍用法 (7631016)

1.2.0-alpha04 版本

2025 年 4 月 23 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha04。1.2.0-alpha04 版包含這些修訂項目。

新功能

現在可透過 ListDetailPaneScaffold 和 SupportingPaneScaffold 使用重排策略，在單一窗格版面配置設定下重排相關聯的窗格。

API 變更

在 PaneScaffoldScope 中新增可儲存的狀態持有者 (Id9299)
導入適應性重排策略 (I75c6a)

修正錯誤

修正窗格在第一次轉場時不會產生動畫的錯誤。(Ib0415)
修正首選高度無法運作的問題。(I1913b)
修正支架指令未正確更新的錯誤。(0403ab)

1.2.0-alpha03 版本

2025 年 4 月 9 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha03。1.2.0-alpha03 版包含這些修訂項目。

修正錯誤

修正單一窗格版面配置中顯示的拖曳控點不正確的問題。(806e443 )

依附元件更新

這個程式庫現在指定 Kotlin 2.0 語言層級，且需要 KGP 2.0.0 以上版本。(Idb6b5)

1.2.0-alpha02 版本

2025 年 3 月 26 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha02。1.2.0-alpha02 版包含這些修訂項目。

1.2.0-alpha01 版本

2025 年 3 月 12 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.2.0-alpha01。1.2.0-alpha01 版包含這些修訂項目。

API 變更

為開發人員導入 PaneScaffoldScope.preferredHeight 修飾符，提供窗格偏好的高度，並套用我們即將推出的新調整策略。(I957dd、b/220960090)
將 ComponentOverride 類型重新命名為 Override，並將 ComponentOverrideContext 類型重新命名為 OverrideScope。(Id973c)
重新命名部分元件覆寫方法。(I222b3)

Compose Material3 自動調整式版面配置 1.1 版

1.1.0 版本

2025 年 3 月 12 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0。1.1.0 版包含這些修訂項目。

自 1.0.0 版以來的重要變更

ListDetailPaneScaffold 和 SupportingPaneScaffold 現在支援窗格擴展功能，使用者可以拖曳變更雙窗格版面配置的預設窗格分割，開發人員也可以透過變更新推出的 PaneExpansionState，在執行階段變更窗格分割。
現在可透過 NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 預設支援預測返回功能。您也可以使用 ThreePaneScaffoldPredictiveBackHandler，透過自己的三窗格架構實作提供預測返回支援。
您現在可以提供不同的 EnterTransition 和 ExitTransition 給 AnimatedPane，在窗格切換期間自訂窗格動作。

1.1.0-rc01 版本

2025 年 2 月 26 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-rc01。1.1.0-rc01 版包含這些修訂項目。

修正錯誤

停用三窗格支架預測返回比例 (ab6fd0b)

1.1.0-beta02 版

2025 年 2 月 12 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-beta02。1.1.0-beta02 版包含這些修訂項目。

API 變更

變更 MutableThreePaneScaffoldState 動畫函式中 isPredictiveBackInProgress 的設定方式，以維持狀態一致性。(Idc97f)

修正錯誤

為與程式庫的其餘部分保持一致，NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 的預設返回行為已變更為 PopUntilScaffoldValueChange。(I873f0)
設定窗格支架的正確無障礙遍歷順序。(67d030)
修正窗格內容狀態未儲存的問題。(88b0ff)
支援替代的無障礙動作，取代拖曳動作。(28266d)
在窗格分割畫面變更後，朗讀目前的分割畫面。(0c3a80)

1.1.0-beta01 版本

2025 年 1 月 29 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-beta01。1.1.0-beta01 版包含這些修訂項目。

API 變更

導入工廠函式，分別從開頭和結尾建立偏移類型的窗格擴展錨點。(I2eb21)
密封 PaneMotion 介面並移除預設轉場方法。(Ifc4c7)
推出 API，用於取得目前的錨點並動畫化至錨點。(Icf95d)
導入窗格擴展功能的無障礙功能 API (Icc669)
將 PaneScaffoldParentData.preferredWidth 的類型變更為 DP。(Id98ee)

1.1.0-alpha09 版本

2025 年 1 月 15 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha09。1.1.0-alpha09 版包含這些修訂項目。

API 變更

新增及使用新的實驗性註解 ExperimentalMaterial3AdaptiveComponentOverrideApi。(Id45aa)
隱藏「ThreePaneScaffoldHorizontalOrder.toLtrOrder」。(I6f8d2)
「ThreePaneScaffoldPredictiveBackHandler」已設為公開。(I1a995、b/370543873)
已將 isPredictiveBackInProgress 屬性新增至 ThreePaneScaffoldState。(I1a995、b/370543873)
建立 AnimatedPane 的覆寫機制，支援不同板型規格的側載實作。(Id7622)

修正錯誤

修正結算方向沒有錨點時的問題。(df8257d)

1.1.0-alpha08 版本

2024 年 12 月 12 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha08。1.1.0-alpha08 版包含這些修訂項目。

API 變更

介紹 currentWindowDpSize 函式。(I99125、b/296300441)
公開 PaneScaffoldParentData 和 ThreePaneScaffoldHorizontalOrder.toLtrOrder() (I2d6b7)
移除 PaneScaffoldMotionScope，並將其轉換為 PaneScaffoldTransitionScope 下方的欄位。同時將其重新命名為 PaneScaffoldMotionDataProvider，並移除對 PaneMotionData 底層資料結構的存取權，改為提供 getter 和迴圈方法來存取資料。(Id8884)
建立 ThreePaneScaffold 的覆寫機制，支援不同板型規格的側載實作。(I5280f)
預設將窗格展開狀態設為空值 (Ia65f8、b/376394520)

1.1.0-alpha07 版本

2024 年 11 月 13 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha07。1.1.0-alpha07 版包含這些修訂項目。

API 變更

移除自適應程式庫中的拖曳控點實作，並鼓勵使用者採用 M3 版本。同時導入修飾符，為提供的拖曳控點可組合函式提供窗格擴展拖曳功能。此外，也請隱藏 DraggableState 做為實作詳細資料，以便日後視需要變更。(Ib50cd)
根據 UXR 回饋，將窗格動作自訂的進入點從 scaffold 函式移至 AnimatedPane。(I10f72)
導入快速滑動支援，以及窗格展開的自訂動畫規格。(Ie207d、b/362584341)

修正錯誤

修正取消時的預測返回手勢問題。(36a3e0a)、(b/369899645)

1.1.0-alpha06 版本

2024 年 10 月 30 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha06。1.1.0-alpha06 版包含這些修訂項目。

API 變更

在 PaneScaffoldTransitionScope.motionProgress 中新增 FloatRange。(Iac0dd)
將可導覽 Scaffold 中的導覽器參數類型變更為泛型。(I1da6e)

1.1.0-alpha05 版本

2024 年 10 月 16 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha05。1.1.0-alpha05 版包含這些修訂項目。

API 變更

導入動畫規格類別，確保動作行為更加一致，並提升未來擴充性。(I2d3cc)
提供動作類型，並將 PaneMotionData 中的 currentXXXXX 重新命名為 originXXXX。(I7c61a)

1.1.0-alpha04 版本

2024 年 10 月 2 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha04。1.1.0-alpha04 版包含這些修訂項目。

新功能

在 NavigableListDetailPaneScaffold 和 NavigableSupportingPaneScaffold 中新增預測返回支援功能。(I4dc21、b/359616816)

API 變更

將 ThreePaneScaffoldState 新增至 ThreePaneScaffoldNavigator 導覽方法已設為 suspend，可支援動畫導覽。新增 seekBack，支援部分導覽狀態 (例如預測返回)。(I5a651、b/359616816)
新增 MutableThreePaneScaffoldState，可控制 scaffold 值之間的轉場效果。現有 ThreePaneScaffoldState 已設為唯讀。(Idb3c6)
公開預設窗格動作實作 (I95a7b)
啟用窗格擴展狀態的初始錨點設定 (Ie41b3、b/362350560)

修正錯誤

強制將拖曳控點的最小觸控目標大小設為 48x48dp (7ce6635、b/366018217)
在設定變更後還原錨定位置 (3c9fc6b、b/362353672)

1.1.0-alpha03 版本

2024 年 9 月 18 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha03。1.1.0-alpha03 版包含這些修訂項目。

1.1.0-alpha02 版本

2024 年 9 月 4 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha02。1.1.0-alpha02 版包含這些修訂版本。

新功能

製作人員可自訂動態效果 (I0bf9c)、(I80e66)，在自動調整式 Scaffold 狀態變更期間變更預設動態效果。製作人員可以從一組預設的進入和退出轉場效果中選擇，也可以使用透過新動態範圍提供的資訊，實作純自訂轉場效果。
實作窗格擴展拖曳控點的淡出動畫 (46e3c69)
讓系統記住的 PaneExpansionState 可儲存 (61ff76f)

API 變更

在架構中新增遺漏的窗格擴充 API (Ic5bc0)
ThreePaneScaffoldDestinationItem.content 已重新命名為 contentKey。rememberListDetailPaneScaffoldNavigator 和 rememberSupportingPaneScaffoldNavigator 的預設型別引數已從 Nothing 變更為 Any。(I58749)
將 ThreePaneScaffoldState 標示為穩定版 (I64aec)
將拖曳控點參數設為範圍 (Ic0aa2)

1.1.0-alpha01 版本

2024 年 8 月 21 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.1.0-alpha01。1.1.0-alpha01 版包含這些修訂版本。

新功能

介紹自動調整式支架的窗格擴展支援功能。

API 變更

向大眾推出窗格擴展 API (I301d6)
導入 ThreePaneScaffoldState，以控制窗格值轉換。新增接受此狀態的 ListDetailPaneScaffold 和 SupportingPaneScaffold 多載。(I5db3b)
導入窗格擴展鍵和鍵盤供應器介面 (Id621f)

修正錯誤

修正排除鉸鏈時的分區計算錯誤。(9dfd483)

Compose Material3 Adaptive 1.0 版

1.0.0 版本

2024 年 9 月 4 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0。1.0.0 版包含這些修訂項目。

1.0.0 的主要功能

可組合函式 currentWindowSize()、collectFoldingFeaturesAsState() 和 currentWindowAdaptiveInfo() 可取得必要視窗資訊，以便調整應用程式，例如視窗大小和摺疊功能。
ListDetailPaneScaffold 和 SupportingPaneScaffold，提供兩種 Material 3 標準版面配置，可根據不同的視窗設定自動調整。這兩個支架也完全可自訂，以滿足創作者的不同需求。
ThreePaneScaffoldNavigator 和相關的記憶函式 rememberListDetailPaneScaffoldNavigator() 和 rememberSupportingPaneScaffoldNavigator()，可在自適應 Scaffold 中提供導覽解決方案，與非自適應世界中常見的單一目的地設定相比，可同時顯示多個導覽目的地。
變更適應性 Scaffold 狀態時，預設的內建 Material 3 動畫。

1.0.0-rc01 版

2024 年 8 月 21 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-rc01。1.0.0-rc01 版包含這些修訂項目。

修正錯誤

修正排除鉸鏈時的分區計算錯誤。(9dfd483)

1.0.0-beta04 版

2024 年 6 月 26 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta04。1.0.0-beta04 版包含這些修訂版本。

修正錯誤

修正問題：當鉸鏈邊界更新時，版面配置不會隨之更新。(71e9cf1)

1.0.0-beta03 版

2024 年 6 月 12 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta03。1.0.0-beta03 版包含這些修訂項目。

修正錯誤

修正 beta02 中因依附元件解析錯誤而導致的當機問題。

1.0.0-beta02 版

2024 年 5 月 29 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta02。1.0.0-beta02 版包含這些修訂項目。

1.0.0-beta01 版

2024 年 5 月 14 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-beta01。1.0.0-beta01 版包含這些修訂項目。

1.0.0-alpha12 版

2024 年 5 月 1 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha12。1.0.0-alpha12 版包含這些修訂項目。

API 變更

將 isFlat 資訊新增至 HingeInfo (Ie0516、b/333784198)
將自適應 API 設為非實驗性 (I1d038)
將自適應版面配置 API 設為非實驗性 (Id23df)
已將 BackNavigationBehavior 從列舉變更為值類別 (Id8757)

修正錯誤

將轉場分數變更為 lambda (I6f5a9)
修正 SizeTracker 的初始狀態問題 (18326a9)
在 Posture 相等檢查中加入鉸鏈清單 (6687137)

1.0.0-alpha11 版本

2024 年 4 月 17 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha11。1.0.0-alpha11 版包含這些修訂項目。

API 變更

將範圍介面密封。(Iefa57)
介紹 AnimatedPaneScope。(I62d73、b/332750742)
確保 AdaptStrategy 密封且穩固。(Ia28b2)
介紹 PaneScaffoldDirective 的複製方法。(I9291f)
將 ThreePaneScaffoldScope 標示為實驗性質。(I9d527)
提供支援導覽功能的易用架構 API。(I263f0、b/321010778)

1.0.0-alpha10 版本

2024 年 4 月 3 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha10。1.0.0-alpha10 版包含這些修訂項目。

API 變更

將預設偏好寬度設為自動調整且可自訂。(Ic3abc)
重新命名支架指令計算函式。(I10855)
從 Scaffold API 中移除邊框間距和插邊。(I786f8)
新增不含泛型型別的導覽器記憶方法。(I607c3)

1.0.0-alpha09 版本

March 20, 2024

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha09。1.0.0-alpha09 版包含這些修訂項目。

API 變更

將狀態轉換欄位新增至 ThreePaneScaffoldScope。(I3d917)
重新排序架構參數。(I4dff5)
提供 AnimatedPane 修飾符參數的預設值。(I77dd7)

修正錯誤

將間隔大小納入窗格動作。(a3174ca)

1.0.0-alpha08 版本

2024 年 3 月 6 日

發布 androidx.compose.material3.adaptive:adaptive-*:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

新功能

切換窗格時，實作延遲滑動。(I1a38e)

API 變更

已移除 ThreePaneScaffoldState 介面。(I63f23)

1.0.0-alpha07 版本

2024 年 2 月 21 日