Công thức Danh sách-Chi tiết của Material

Công thức này minh hoạ cách tạo bố cục danh sách-chi tiết thích ứng bằng cách sử dụng ListDetailSceneStrategy trong thư viện Thích ứng Material 3. Bố cục này tự động điều chỉnh để hiện một, hai hoặc ba ngăn tuỳ thuộc vào chiều rộng màn hình có sẵn.

Cách hoạt động

Ví dụ này có 3 điểm đến: ConversationList, ConversationDetail và Profile.

ListDetailSceneStrategy

Điểm mấu chốt của công thức này là rememberListDetailSceneStrategy, cung cấp logic cho bố cục thích ứng.

  • Vai trò của ngăn: Mỗi đích đến được chỉ định một vai trò bằng cách sử dụng siêu dữ liệu:

    • ListDetailSceneStrategy.listPane(): Đối với nội dung chính (danh sách). Ngăn này luôn hiển thị. Bạn có thể cung cấp một phần giữ chỗ để hiển thị trong vùng ngăn chi tiết khi không có nội dung chi tiết nào được chọn.
    • ListDetailSceneStrategy.detailPane(): Đối với nội dung phụ (chi tiết).
    • ListDetailSceneStrategy.extraPane(): Đối với nội dung bậc 3.

  • Bố cục thích ứng: ListDetailSceneStrategy sẽ tự động xử lý bố cục. Trên màn hình nhỏ, mỗi lần chỉ có một ngăn xuất hiện. Trên màn hình rộng hơn, danh sách và ngăn chi tiết sẽ xuất hiện cạnh nhau. Trên màn hình rất rộng, thành phần này có thể hiển thị cả 3 ngăn: danh sách, chi tiết và ngăn bổ sung.

  • Điều hướng: Hoạt động điều hướng giữa các ngăn được xử lý bằng cách thêm và xoá đích đến khỏi ngăn xếp lui như bình thường. ListDetailSceneStrategy sẽ theo dõi ngăn xếp lui và điều chỉnh bố cục cho phù hợp.

package com.example.nav3recipes.material.listdetail

/*
 * Copyright 2025 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.material3.adaptive.ExperimentalMaterial3AdaptiveApi
import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
import androidx.compose.material3.adaptive.layout.calculatePaneScaffoldDirective
import androidx.compose.material3.adaptive.navigation3.ListDetailSceneStrategy
import androidx.compose.material3.adaptive.navigation3.rememberListDetailSceneStrategy
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.unit.dp
import androidx.lifecycle.compose.dropUnlessResumed
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.ui.NavDisplay
import com.example.nav3recipes.content.ContentBlue
import com.example.nav3recipes.content.ContentGreen
import com.example.nav3recipes.content.ContentRed
import com.example.nav3recipes.content.ContentYellow
import com.example.nav3recipes.ui.setEdgeToEdgeConfig
import kotlinx.serialization.Serializable

@Serializable
private object ConversationList : NavKey

@Serializable
private data class ConversationDetail(val id: String) : NavKey

@Serializable
private data object Profile : NavKey

class MaterialListDetailActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3AdaptiveApi::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        setEdgeToEdgeConfig()
        super.onCreate(savedInstanceState)

        setContent {

            val backStack = rememberNavBackStack(ConversationList)

            // Override the defaults so that there isn't a horizontal space between the panes.
            // See b/418201867
            val windowAdaptiveInfo = currentWindowAdaptiveInfoV2()
            val directive = remember(windowAdaptiveInfo) {
                calculatePaneScaffoldDirective(windowAdaptiveInfo)
                    .copy(horizontalPartitionSpacerSize = 0.dp)
            }
            val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>(directive = directive)

            NavDisplay(
                backStack = backStack,
                onBack = { backStack.removeLastOrNull() },
                sceneStrategies = listOf(listDetailStrategy),
                entryProvider = entryProvider {
                    entry<ConversationList>(
                        metadata = ListDetailSceneStrategy.listPane(
                            detailPlaceholder = {
                                ContentYellow("Choose a conversation from the list")
                            }
                        )
                    ) {
                        ContentRed("Welcome to Nav3") {
                            Button(onClick = dropUnlessResumed {
                                backStack.add(ConversationDetail("ABC"))
                            }) {
                                Text("View conversation")
                            }
                        }
                    }
                    entry<ConversationDetail>(
                        metadata = ListDetailSceneStrategy.detailPane()
                    ) { conversation ->
                        ContentBlue("Conversation ${conversation.id} ") {
                            Column(horizontalAlignment = Alignment.CenterHorizontally) {
                                Button(onClick = dropUnlessResumed {
                                    backStack.add(Profile)
                                }) {
                                    Text("View profile")
                                }
                            }
                        }
                    }
                    entry<Profile>(
                        metadata = ListDetailSceneStrategy.extraPane()
                    ) {
                        ContentGreen("Profile")
                    }
                }
            )
        }
    }
}