สร้างเลย์เอาต์ที่กำหนดเองโดยใช้ฉาก

Navigation 3 เปิดตัวระบบที่มีประสิทธิภาพและยืดหยุ่นสำหรับการจัดการโฟลว์ UI ของแอปผ่านฉาก ฉากช่วยให้คุณสร้างเลย์เอาต์ที่ปรับแต่งได้สูง ปรับให้เข้ากับขนาดหน้าจอต่างๆ และจัดการประสบการณ์การใช้งานหลายแผงที่ซับซ้อนได้อย่างราบรื่น

ทำความเข้าใจฉาก

ใน Navigation 3 Scene เป็นหน่วยพื้นฐานที่แสดงผลอินสแตนซ์ NavEntry อย่างน้อย 1 รายการ ให้คิดว่า Scene เป็นสถานะภาพหรือส่วนที่แตกต่างกันของ UI ซึ่งสามารถมีและจัดการการแสดงเนื้อหาจาก Back Stack ได้

อินสแตนซ์ Scene แต่ละรายการจะระบุโดย key และคลาสของ Scene เองโดยไม่ซ้ำกัน ตัวระบุที่ไม่ซ้ำกันนี้มีความสำคัญอย่างยิ่งเนื่องจากเป็นตัวขับเคลื่อนภาพเคลื่อนไหวระดับบนสุดเมื่อ Scene มีการเปลี่ยนแปลง

อินเทอร์เฟซ Scene มีพร็อพเพอร์ตี้ต่อไปนี้

  • key: Any: ตัวระบุที่ไม่ซ้ำกันสำหรับอินสแตนซ์ Scene ที่เฉพาะเจาะจงนี้ คีย์นี้เมื่อรวมกับคลาสของ Scene จะช่วยให้มั่นใจได้ถึงความแตกต่าง โดยมีวัตถุประสงค์เพื่อการสร้างภาพเคลื่อนไหวเป็นหลัก
  • entries: List<NavEntry<T>>: นี่คือรายการออบเจ็กต์ NavEntry ที่ Scene มีหน้าที่แสดง สิ่งสำคัญคือ หากมีการแสดง NavEntry เดียวกันใน Scenes หลายรายการระหว่างการเปลี่ยนผ่าน (เช่น ในการเปลี่ยนผ่านองค์ประกอบที่แชร์) ระบบจะแสดงผลเนื้อหาขององค์ประกอบดังกล่าวโดย Scene เป้าหมายล่าสุดที่แสดงองค์ประกอบนั้นเท่านั้น
  • previousEntries: List<NavEntry<T>>: พร็อพเพอร์ตี้นี้กำหนด NavEntry ที่จะเกิดขึ้นหากมีการดำเนินการ "ย้อนกลับ" จาก Scene ปัจจุบัน ซึ่งจำเป็นต่อการคำนวณสถานะการย้อนกลับที่คาดการณ์ได้อย่างเหมาะสม ช่วยให้ NavDisplay คาดการณ์และเปลี่ยนสถานะเป็นสถานะก่อนหน้าที่ถูกต้องได้ ซึ่งอาจเป็น Scene ที่มีคลาส คีย์ หรือทั้ง 2 อย่างที่แตกต่างกัน
  • content: @Composable () -> Unit: ฟังก์ชันที่ประกอบกันได้ซึ่งคุณกำหนดวิธีที่ Scene แสดงผล entries และองค์ประกอบ UI โดยรอบที่เฉพาะเจาะจงสำหรับ Scene นั้น
  • metadata: Map<String, Any>: ให้ข้อมูลเฉพาะฉากแก่คอมโพเนนต์อื่นๆ ของไลบรารี เช่น NavDisplay โดยค่าเริ่มต้น ระบบจะแสดง metadata ของ NavEntry ล่าสุดใน entries

ใช้ equals และ hashCode ในฉากที่กำหนดเอง

การติดตั้งใช้งาน Scene ที่กำหนดเองต้องติดตั้งใช้งาน equals และ hashCode อย่างถูกต้องเพื่อรองรับสิ่งต่อไปนี้

  • การเปลี่ยนสถานะฉาก: ทุกครั้งที่มีการคำนวณฉากตามรายการกลยุทธ์ฉาก NavDisplay จะตรวจสอบความเท่ากันของฉากใหม่และฉากก่อนหน้า หากตรวจพบการเปลี่ยนแปลง ระบบจะอัปเดต SeekableTransition ที่ใช้ในการเปลี่ยนฉากระหว่างฉากต่างๆ ซึ่งจะส่งผลต่อสถานะวงจรของฉาก
  • การจัดการการวางซ้อน: สำหรับ OverlayScene (เช่น กล่องโต้ตอบ) NavDisplay จะใช้ออบเจ็กต์ฉากเป็น key เพื่อติดตามวงจรการวางซ้อนและภาพเคลื่อนไหวเมื่อออก

ตรวจสอบว่าพร็อพเพอร์ตี้ทั้งหมดที่กำหนดเนื้อหาของฉาก เช่น key, entries และ previousEntries รวมอยู่ในการติดตั้งใช้งาน equals และ hashCode โดยทั่วไปแล้ว ให้หลีกเลี่ยงการรวม Callback (เช่น onBack) ในการติดตั้งใช้งานเมธอดเหล่านี้ เนื่องจากอาจเปลี่ยนอินสแตนซ์ได้โดยไม่ต้องเปลี่ยนสถานะเชิงตรรกะของฉาก

ทำความเข้าใจกลยุทธ์ฉาก

SceneStrategy คือกลไกที่กำหนดวิธีจัดเรียงและเปลี่ยนรายการ NavEntry ที่ระบุจาก Back Stack ให้เป็น Scene โดยพื้นฐานแล้ว เมื่อแสดงรายการ Back Stack ปัจจุบัน SceneStrategy จะถามตัวเองด้วยคำถามสำคัญ 2 ข้อดังนี้

  1. ฉันจะสร้าง Scene จากรายการเหล่านี้ได้ไหม หาก SceneStrategy พิจารณาแล้วว่าสามารถจัดการ NavEntry ที่ระบุและสร้าง Scene ที่มีความหมายได้ (เช่น กล่องโต้ตอบหรือเลย์เอาต์แบบหลายแผง) ก็จะดำเนินการต่อ ไม่เช่นนั้น ระบบจะแสดงผลเป็น null ซึ่งจะเปิดโอกาสให้กลยุทธ์อื่นๆ สร้าง Scene
  2. หากเป็นเช่นนั้น ฉันควรจัดเรียงรายการเหล่านั้นใน Scene? อย่างไร เมื่อ SceneStrategy มุ่งมั่นที่จะจัดการรายการเหล่านั้น ก็จะรับผิดชอบในการสร้าง Scene และกำหนดวิธีแสดง NavEntry ที่ระบุภายใน Scene นั้น

หัวใจสำคัญของ SceneStrategy คือเมธอด calculateScene ดังนี้

@Composable
public fun calculateScene(
    entries: List<NavEntry<T>>,
    onBack: (count: Int) -> Unit,
): Scene<T>?

เมธอดนี้เป็นฟังก์ชันส่วนขยายใน SceneStrategyScope ที่ใช้ List<NavEntry<T>> ปัจจุบันจาก Back Stack โดยควรแสดงผลเป็น Scene<T> หากสร้างได้สำเร็จจากรายการที่ระบุ หรือ null หากสร้างไม่ได้

SceneStrategyScope มีหน้าที่รับผิดชอบในการรักษาอาร์กิวเมนต์ที่ไม่บังคับซึ่ง SceneStrategy อาจต้องใช้ เช่น Callback ของ onBack

วิธีการทำงานร่วมกันของฉากและกลยุทธ์ฉาก

NavDisplay เป็น Composable ส่วนกลางที่สังเกต Back Stack และใช้ SceneStrategy อย่างน้อย 1 รายการเพื่อกำหนดและแสดงผล Scene ที่เหมาะสม

พารามิเตอร์ sceneStrategies ของ NavDisplay คาดหวังรายการอินสแตนซ์ SceneStrategy ที่รับผิดชอบในการคำนวณ Scene ที่จะแสดง หากกลยุทธ์ที่ระบุไม่คำนวณ Scene ระบบจะใช้ SinglePaneSceneStrategy โดยค่าเริ่มต้นโดยอัตโนมัติใน NavDisplay

รายละเอียดการโต้ตอบมีดังนี้

  • เมื่อคุณเพิ่มหรือนำคีย์ออกจาก Back Stack (เช่น การใช้ backStack.add() หรือ backStack.removeLastOrNull()) NavDisplay จะสังเกตเห็นการเปลี่ยนแปลงเหล่านี้
  • NavDisplay จะส่งรายการ NavEntry ปัจจุบัน (ที่ได้มาจากคีย์ Back Stack) ไปยัง sceneStrategies ที่กำหนดค่าไว้ตามลำดับ โดยเรียกใช้ calculateScene ในแต่ละรายการจนกว่าจะมีการแสดงผล Scene
  • เมื่อ SceneStrategy แสดงผล Scene สำเร็จ NavDisplay จะแสดงผล content ของ Scene นั้น นอกจากนี้ NavDisplay ยังจัดการภาพเคลื่อนไหวและการย้อนกลับที่คาดการณ์ได้ตามพร็อพเพอร์ตี้ของ Scene ด้วย

ตัวอย่าง: เลย์เอาต์แผงเดียว (ลักษณะการทำงานเริ่มต้น)

เลย์เอาต์ที่กำหนดเองที่เรียบง่ายที่สุดคือการแสดงผลแบบแผงเดียว ซึ่งเป็นลักษณะการทำงานเริ่มต้นหากไม่มี SceneStrategy อื่นที่มีลำดับความสำคัญสูงกว่า

data class SinglePaneScene<T : Any>(
    override val key: Any,
    val entry: NavEntry<T>,
    override val previousEntries: List<NavEntry<T>>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(entry)
    override val content: @Composable () -> Unit = { entry.Content() }
}

/**
 * A [SceneStrategy] that always creates a 1-entry [Scene] simply displaying the last entry in the
 * list.
 */
public class SinglePaneSceneStrategy<T : Any> : SceneStrategy<T> {
    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? =
        SinglePaneScene(
            key = entries.last().contentKey,
            entry = entries.last(),
            previousEntries = entries.dropLast(1)
        )
}

ตัวอย่าง: เลย์เอาต์รายละเอียดรายการพื้นฐาน (Scene และกลยุทธ์ที่กำหนดเอง)

ตัวอย่างนี้แสดงวิธีสร้างเลย์เอาต์แบบรายละเอียดรายการที่เปิดใช้งานตามเงื่อนไข 2 ข้อต่อไปนี้

  1. ความกว้างของหน้าต่างกว้างพอที่จะรองรับ 2 แผง (เช่น อย่างน้อย WIDTH_DP_MEDIUM_LOWER_BOUND)
  2. Back Stack มีรายการที่ประกาศการรองรับการแสดงผลในเลย์เอาต์แบบรายละเอียดรายการโดยใช้ข้อมูลเมตาที่เฉพาะเจาะจง

ข้อมูลโค้ดต่อไปนี้คือซอร์สโค้ดสำหรับ ListDetailScene.kt และมีทั้ง ListDetailScene และ ListDetailSceneStrategy

// --- ListDetailScene ---
/**
 * A [Scene] that displays a list and a detail [NavEntry] side-by-side in a 40/60 split.
 *
 */
data class ListDetailScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    val listEntry: NavEntry<T>,
    val detailEntry: NavEntry<T>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(listEntry, detailEntry)
    override val content: @Composable (() -> Unit) = {
        Row(modifier = Modifier.fillMaxSize()) {
            Column(modifier = Modifier.weight(0.4f)) {
                listEntry.Content()
            }
            Column(modifier = Modifier.weight(0.6f)) {
                detailEntry.Content()
            }
        }
    }
}

@Composable
fun <T : Any> rememberListDetailSceneStrategy(): ListDetailSceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass

    return remember(windowSizeClass) {
        ListDetailSceneStrategy(windowSizeClass)
    }
}

// --- ListDetailSceneStrategy ---
/**
 * A [SceneStrategy] that returns a [ListDetailScene] if the window is wide enough, the last item
 * is the backstack is a detail, and before it, at any point in the backstack is a list.
 */
class ListDetailSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {

    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {

        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
            return null
        }

        val detailEntry =
            entries.lastOrNull()?.takeIf { it.metadata.contains(DetailKey) } ?: return null
        val listEntry = entries.findLast { it.metadata.contains(ListKey) } ?: return null

        // We use the list's contentKey to uniquely identify the scene.
        // This allows the detail panes to be displayed instantly through recomposition, rather than
        // having NavDisplay animate the whole scene out when the selected detail item changes.
        val sceneKey = listEntry.contentKey

        return ListDetailScene(
            key = sceneKey,
            previousEntries = entries.dropLast(1),
            listEntry = listEntry,
            detailEntry = detailEntry
        )
    }

    object ListKey : NavMetadataKey<Boolean>
    object DetailKey : NavMetadataKey<Boolean>
    companion object {

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun listPane() = metadata {
            put(ListKey, true)
        }

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun detailPane() = metadata {
            put(DetailKey, true)
        }
    }
}

หากต้องการใช้ ListDetailSceneStrategy นี้ใน NavDisplay ให้แก้ไขการเรียก entryProvider เพื่อรวมข้อมูลเมตา ListDetailScene.listPane() สำหรับรายการที่คุณต้องการแสดงเป็นเลย์เอาต์รายการ และ ListDetailScene.detailPane() สำหรับรายการที่คุณต้องการแสดงเป็นเลย์เอาต์รายละเอียด จากนั้นระบุ ListDetailSceneStrategy() เป็น sceneStrategy โดยใช้ค่าสำรองเริ่มต้นสำหรับสถานการณ์แบบแผงเดียว

// Define your navigation keys
@Serializable
data object ConversationList : NavKey

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

@Composable
fun MyAppContent() {
    val backStack = rememberNavBackStack(ConversationList)
    val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        sceneStrategies = listOf(listDetailStrategy),
        entryProvider = entryProvider {
            entry<ConversationList>(
                metadata = ListDetailSceneStrategy.listPane()
            ) {
                Column(modifier = Modifier.fillMaxSize()) {
                    Text(text = "I'm a Conversation List")
                    Button(onClick = { backStack.addDetail(ConversationDetail("123")) }) {
                        Text(text = "Open detail")
                    }
                }
            }
            entry<ConversationDetail>(
                metadata = ListDetailSceneStrategy.detailPane()
            ) {
                Text(text = "I'm a Conversation Detail")
            }
        }
    )
}

private fun NavBackStack<NavKey>.addDetail(detailRoute: ConversationDetail) {

    // Remove any existing detail routes, then add the new detail route
    removeIf { it is ConversationDetail }
    add(detailRoute)
}

หากไม่ต้องการสร้างฉากรายละเอียดรายการของคุณเอง คุณสามารถใช้ฉากรายละเอียดรายการ Material ซึ่งมาพร้อมกับรายละเอียดที่เหมาะสมและการรองรับตัวยึดตำแหน่ง ดังที่แสดงในส่วนถัดไป

แสดงเนื้อหารายละเอียดรายการในฉากแบบปรับอัตโนมัติของ Material

สำหรับกรณีการใช้งานแบบรายละเอียดรายการ อาร์ติแฟกต์ androidx.compose.material3.adaptive:adaptive-navigation3 จะมี ListDetailSceneStrategy ที่สร้าง Scene แบบรายละเอียดรายการ Scene นี้จะจัดการการจัดเรียงหลายแผงที่ซับซ้อน (รายการ รายละเอียด และแผงเพิ่มเติม) โดยอัตโนมัติ และปรับเปลี่ยนตามขนาดหน้าต่างและสถานะอุปกรณ์

หากต้องการสร้างรายละเอียดรายการของ Material Scene ให้ทำตามขั้นตอนต่อไปนี้

  1. เพิ่มทรัพยากร Dependency: รวม androidx.compose.material3.adaptive:adaptive-navigation3 ไว้ในไฟล์ build.gradle.kts ของโปรเจ็กต์
  2. กำหนดรายการด้วยข้อมูลเมตา ListDetailSceneStrategy: ใช้ listPane(), detailPane() และ extraPane() เพื่อทำเครื่องหมาย NavEntrys สำหรับการแสดงผลในแผงที่เหมาะสม นอกจากนี้ ตัวช่วย listPane() ยังช่วยให้คุณระบุ detailPlaceholder เมื่อไม่ได้เลือกรายการใดๆ
  3. ใช้ rememberListDetailSceneStrategy(): ฟังก์ชันที่ประกอบกันได้นี้มี ListDetailSceneStrategy ที่กำหนดค่าไว้ล่วงหน้าซึ่ง NavDisplay สามารถใช้ได้

ข้อมูลโค้ดต่อไปนี้เป็นตัวอย่าง Activity ที่แสดงการใช้งาน ListDetailSceneStrategy

@Serializable
object ProductList : NavKey

@Serializable
data class ProductDetail(val id: String) : NavKey

@Serializable
data object Profile : NavKey

class MaterialListDetailActivity : ComponentActivity() {

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

        setContent {
            Scaffold { paddingValues ->
                val backStack = rememberNavBackStack(ProductList)
                val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

                NavDisplay(
                    backStack = backStack,
                    modifier = Modifier.padding(paddingValues),
                    onBack = { backStack.removeLastOrNull() },
                    sceneStrategies = listOf(listDetailStrategy),
                    entryProvider = entryProvider {
                        entry<ProductList>(
                            metadata = ListDetailSceneStrategy.listPane(
                                detailPlaceholder = {
                                    ContentYellow("Choose a product from the list")
                                }
                            )
                        ) {
                            ContentRed("Welcome to Nav3") {
                                Button(onClick = {
                                    backStack.add(ProductDetail("ABC"))
                                }) {
                                    Text("View product")
                                }
                            }
                        }
                        entry<ProductDetail>(
                            metadata = ListDetailSceneStrategy.detailPane()
                        ) { product ->
                            ContentBlue("Product ${product.id} ", Modifier.background(PastelBlue)) {
                                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                                    Button(onClick = {
                                        backStack.add(Profile)
                                    }) {
                                        Text("View profile")
                                    }
                                }
                            }
                        }
                        entry<Profile>(
                            metadata = ListDetailSceneStrategy.extraPane()
                        ) {
                            ContentGreen("Profile")
                        }
                    }
                )
            }
        }
    }
}

รูปที่ 1 ตัวอย่างเนื้อหาที่แสดงในฉากรายการ-รายละเอียดของ Material