Xây dựng bố cục danh sách-chi tiết

Danh sách-chi tiết là mẫu giao diện người dùng bao gồm bố cục hai ngăn, trong đó một ngăn trình bày danh sách các mục, còn một ngăn khác hiển thị thông tin chi tiết về các mục được chọn trong danh sách.

Mẫu này đặc biệt hữu ích cho các ứng dụng cung cấp thông tin chuyên sâu về các thành phần trong các tập hợp lớn, chẳng hạn như ứng dụng email có danh sách email và nội dung chi tiết của từng email. Bạn cũng có thể dùng danh sách-chi tiết cho các đường dẫn ít quan trọng hơn, chẳng hạn như chia các lựa chọn ưu tiên về ứng dụng thành một danh sách các danh mục có lựa chọn ưu tiên cho từng danh mục trong ngăn chi tiết.

Triển khai mẫu giao diện người dùng bằng ListDetailPaneScaffold

ListDetailPaneScaffold là một thành phần kết hợp giúp đơn giản hoá việc triển khai mẫu danh sách-chi tiết trong ứng dụng. Scaffold danh sách-chi tiết có thể bao gồm tối đa 3 ngăn: một ngăn danh sách, một ngăn chi tiết và một ngăn bổ sung không bắt buộc. Scaffold xử lý các phép tính không gian màn hình. Khi có đủ kích thước màn hình, ngăn chi tiết sẽ xuất hiện cùng với ngăn danh sách. Trên các kích thước màn hình nhỏ, Scaffold sẽ tự động chuyển sang hiển thị toàn màn hình danh sách hoặc ngăn chi tiết.

Khai báo phần phụ thuộc

ListDetailPaneScaffold là một phần của Thư viện bố cục thích ứng Material 3.

Ứng dụng của bạn phải có các phần phụ thuộc cho 3 thư viện Material 3 có liên quan:

• thích ứng – Các thành phần cấp thấp như HingeInfo và Posture
• adaptive-layout – Bố cục thích ứng, chẳng hạn như ListDetailPaneScaffold và SupportingPaneScaffold
  • adaptive-navigation – Các thành phần kết hợp để di chuyển trong và giữa các ngăn

Thêm các phần phụ thuộc vào tệp build.gradle của ứng dụng hoặc mô-đun:

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")

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'

Cách sử dụng cơ bản

Triển khai ListDetailPaneScaffold như sau:

1. Sử dụng một lớp đại diện cho nội dung cần chọn. Lớp này phải là Parcelable để hỗ trợ việc lưu và khôi phục mục danh sách đã chọn. Hãy sử dụng trình bổ trợ kotlin-parcelize để tạo mã cho bạn.

   @Parcelize
   class MyItem(val id: Int) : Parcelable
   SampleListDetailPaneScaffold.kt

2. Tạo một ThreePaneScaffoldNavigator bằng rememberListDetailPaneScaffoldNavigator và thêm một BackHandler. Trình điều hướng này dùng để di chuyển giữa các ngăn danh sách, ngăn thông tin chi tiết và các ngăn bổ sung. Bằng cách khai báo một loại chung, trình điều hướng cũng theo dõi trạng thái của Scaffold (tức là MyItem đang được hiển thị). Vì loại này có thể đóng gói, nên trình điều hướng có thể lưu và khôi phục trạng thái để tự động xử lý các thay đổi về cấu hình. BackHandler hỗ trợ bạn quay lại bằng cách sử dụng nút hoặc cử chỉ quay lại của hệ thống. Hành vi dự kiến của nút quay lại cho ListDetailPaneScaffold phụ thuộc vào kích thước cửa sổ và giá trị Scaffold hiện tại. Nếu ListDetailPaneScaffold có thể hỗ trợ quay lại trạng thái hiện tại, thì canNavigateBack() là true, hãy bật BackHandler.

   val navigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
   
   BackHandler(navigator.canNavigateBack()) {
       navigator.navigateBack()
   }
   SampleListDetailPaneScaffold.kt

3. Truyền scaffoldState từ navigator sang thành phần kết hợp ListDetailPaneScaffold.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       // ...
   )
   SampleListDetailPaneScaffold.kt

4. Cung cấp cách triển khai ngăn danh sách cho ListDetailPaneScaffold. Sử dụng AnimatedPane để áp dụng ảnh động của ngăn mặc định trong khi điều hướng. Sau đó, sử dụng ThreePaneScaffoldNavigator để chuyển đến ngăn chi tiết ListDetailPaneScaffoldRole.Detail và hiển thị mục đã chuyển.

   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)
                   }
               )
           }
       },
       // ...
   )
   SampleListDetailPaneScaffold.kt

5. Thêm cách triển khai ngăn chi tiết trong ListDetailPaneScaffold. Khi quá trình điều hướng hoàn tất, currentDestination sẽ chứa ngăn mà ứng dụng của bạn đã điều hướng đến, bao gồm cả nội dung hiển thị trong ngăn đó. Thuộc tính content cùng loại được chỉ định trong lệnh gọi ghi nhớ ban đầu (trong ví dụ này là MyItem), nên bạn cũng có thể truy cập vào thuộc tính này cho mọi dữ liệu mà bạn cần hiển thị.

   ListDetailPaneScaffold(
       directive = navigator.scaffoldDirective,
       value = navigator.scaffoldValue,
       listPane =
       // ...
       detailPane = {
           AnimatedPane {
               navigator.currentDestination?.content?.let {
                   MyDetails(it)
               }
           }
       },
   )
   SampleListDetailPaneScaffold.kt

Sau khi triển khai các bước trên, mã của bạn sẽ có dạng như sau:

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)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt