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 ข้อดังนี้
- ฉันจะสร้าง
Sceneจากรายการเหล่านี้ได้ไหม หากSceneStrategyพิจารณาแล้วว่าสามารถจัดการNavEntryที่ระบุและสร้างSceneที่มีความหมายได้ (เช่น กล่องโต้ตอบหรือเลย์เอาต์แบบหลายแผง) ก็จะดำเนินการต่อ ไม่เช่นนั้น ระบบจะแสดงผลเป็นnullซึ่งจะเปิดโอกาสให้กลยุทธ์อื่นๆ สร้างScene - หากเป็นเช่นนั้น ฉันควรจัดเรียงรายการเหล่านั้นใน
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 ข้อต่อไปนี้
- ความกว้างของหน้าต่างกว้างพอที่จะรองรับ 2 แผง (เช่น อย่างน้อย
WIDTH_DP_MEDIUM_LOWER_BOUND) - 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 ให้ทำตามขั้นตอนต่อไปนี้
- เพิ่มทรัพยากร Dependency: รวม
androidx.compose.material3.adaptive:adaptive-navigation3ไว้ในไฟล์build.gradle.ktsของโปรเจ็กต์ - กำหนดรายการด้วยข้อมูลเมตา
ListDetailSceneStrategy: ใช้listPane(), detailPane()และextraPane()เพื่อทำเครื่องหมายNavEntrysสำหรับการแสดงผลในแผงที่เหมาะสม นอกจากนี้ ตัวช่วยlistPane()ยังช่วยให้คุณระบุdetailPlaceholderเมื่อไม่ได้เลือกรายการใดๆ - ใช้
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") } } ) } } } }