清單詳細資料是一種 UI 模式,由雙窗格版面配置組成,其中一個窗格用於顯示項目清單,另一個窗格會顯示清單中所選項目的詳細資料。
如果應用程式需要提供大型集合元素的深度資訊,這種模式特別實用,例如具有電子郵件清單和每封電子郵件詳細內容的電子郵件用戶端。較不重要的路徑也可使用清單/詳細資料,例如將應用程式偏好設定區分為一組類別清單,以及詳細資料窗格中每個類別的偏好設定。
使用 ListDetailPaneScaffold
實作 UI 模式
ListDetailPaneScaffold
這個可組合項可簡化應用程式中的清單/詳細資料模式實作方式。清單/詳細資料 Scaffold 可包含最多三個窗格:清單窗格、詳細資料窗格,以及選用的額外窗格。Scaffold 會處理螢幕空間計算。當螢幕大小足夠時,詳細資料窗格會與清單窗格一起顯示。在小螢幕上,scaffold 會自動切換為以全螢幕模式顯示清單或詳細資料窗格。
宣告依附元件
ListDetailPaneScaffold
是 Material 3 自動調整式版面配置程式庫的一部分。
應用程式必須包含三個相關 Material 3 程式庫的依附元件:
- 自動調整 - 低階建構模塊,例如
HingeInfo
和Posture
- 自動調整版面配置 - 自動調整式版面配置,例如
ListDetailPaneScaffold
和SupportingPaneScaffold
- 自動調整導覽 - 用於在窗格內及之間導覽的可組合函式
將依附元件新增至應用程式或模組的 build.gradle
檔案:
Kotlin
implementation("androidx.compose.material3.adaptive:adaptive:1.0.0-alpha12") implementation("androidx.compose.material3.adaptive:adaptive-layout:1.0.0-alpha12") implementation("androidx.compose.material3.adaptive:adaptive-navigation:1.0.0-alpha12")
Groovy
implementation 'androidx.compose.material3.adaptive:adaptive:1.0.0-alpha12' implementation 'androidx.compose.material3.adaptive:adaptive-layout:1.0.0-alpha12' implementation 'androidx.compose.material3.adaptive:adaptive-navigation:1.0.0-alpha12'
基本用法
實作 ListDetailPaneScaffold
,如下所示:
使用代表要選取內容的類別。這個類別應為
Parcelable
,可支援儲存及還原選取的清單項目。使用 kotlin-parcelize 外掛程式產生程式碼。@Parcelize class MyItem(val id: Int) : Parcelable
使用
rememberListDetailPaneScaffoldNavigator
建立ThreePaneScaffoldNavigator
,並新增BackHandler
。這個導覽工具可用於在清單、詳細資料和其他窗格之間移動。宣告一般類型後,導覽器也會追蹤 Scaffold 的狀態 (也就是目前顯示的MyItem
)。由於這個類型是可包裝的,導覽器可儲存及還原狀態,自動處理設定變更。BackHandler
支援使用系統返回手勢或按鈕返回返回。ListDetailPaneScaffold
返回按鈕的預期行為取決於視窗大小和目前的 Scaffold 值。如果ListDetailPaneScaffold
支援以目前狀態返回,則canNavigateBack()
為true
,即可啟用BackHandler
。val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>() BackHandler(navigator.canNavigateBack()) { navigator.navigateBack() }
將
scaffoldState
從navigator
傳遞至ListDetailPaneScaffold
可組合項。ListDetailPaneScaffold( directive = navigator.scaffoldDirective, value = navigator.scaffoldValue, // ... )
將清單窗格實作項目導入
ListDetailPaneScaffold
。請使用AnimatedPane
在導覽期間套用預設窗格動畫。接著,使用ThreePaneScaffoldNavigator
前往詳細資料窗格ListDetailPaneScaffoldRole.Detail
,並顯示傳遞的項目。ListDetailPaneScaffold( directive = navigator.scaffoldDirective, value = navigator.scaffoldValue, listPane = { AnimatedPane { MyList( onItemClick = { item -> // Navigate to the detail pane with the passed item navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item) } ) } }, // ... )
在
ListDetailPaneScaffold
中加入詳細資料窗格實作。導覽完成後,currentDestination
包含應用程式要前往的窗格,包括在窗格中顯示的內容。content
屬性與原始 remember 呼叫中指定的類型相同 (在此範例中為MyItem
),因此您也可以針對需要顯示的任何資料存取屬性。ListDetailPaneScaffold( directive = navigator.scaffoldDirective, value = navigator.scaffoldValue, listPane = // ... detailPane = { AnimatedPane { navigator.currentDestination?.content?.let { MyDetails(it) } } }, )
實作上述步驟後,程式碼應如下所示:
val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>() BackHandler(navigator.canNavigateBack()) { navigator.navigateBack() } ListDetailPaneScaffold( directive = navigator.scaffoldDirective, value = navigator.scaffoldValue, listPane = { AnimatedPane { MyList( onItemClick = { item -> // Navigate to the detail pane with the passed item navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, item) }, ) } }, detailPane = { AnimatedPane { // Show the detail pane content if selected item is available navigator.currentDestination?.content?.let { MyDetails(it) } } }, )