ทําความเข้าใจและใช้งานพื้นฐาน

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

สถานะการนำทางในการประมาณ

วิธีที่สะดวกในการจำลองลักษณะการทำงานนี้คือการใช้กองเนื้อหา เมื่อผู้ใช้ไปยังเนื้อหาใหม่ข้างหน้า ระบบจะพุชเนื้อหานั้นไว้ที่ด้านบนของสแต็ก เมื่อผู้ใช้ย้อนกลับจากเนื้อหานั้น ระบบจะนำเนื้อหาออกจากสแต็กและแสดงเนื้อหาก่อนหน้า ในแง่ของการนำทาง สแต็กนี้มักเรียกว่า Back Stack เนื่องจากแสดงถึงเนื้อหาที่ผู้ใช้ย้อนกลับไปดูได้

ปุ่มดำเนินการของแป้นพิมพ์เสมือน (ไอคอนเครื่องหมายถูก) ที่วงกลมสีแดงไว้
รูปที่ 1 แผนภาพแสดงการเปลี่ยนแปลงของ Back Stack ตามเหตุการณ์การนำทางของผู้ใช้

สร้าง Back Stack

ใน Navigation 3 Back Stack ไม่มีเนื้อหาจริงๆ แต่จะมีการอ้างอิงถึงเนื้อหาที่เรียกว่าคีย์แทน คีย์อาจเป็นประเภทใดก็ได้ แต่โดยปกติแล้วจะเป็นคลาสข้อมูลที่เรียบง่ายและจัดเรียงได้ การใช้ข้อมูลอ้างอิงแทนเนื้อหามีประโยชน์ดังนี้

  • การไปยังส่วนต่างๆ ทำได้ง่ายๆ โดยการพุชคีย์ไปยัง Back Stack
  • ตราบใดที่คีย์สามารถจัดลำดับได้ Back Stack จะบันทึกลงในพื้นที่เก็บข้อมูลถาวรได้ ซึ่งจะช่วยให้คีย์ยังคงอยู่แม้จะมีการเปลี่ยนแปลงการกำหนดค่าและการสิ้นสุดการประมวลผล ซึ่งเป็นสิ่งสำคัญเนื่องจากผู้ใช้คาดหวังว่าจะออกจากแอป กลับมาใช้แอปในภายหลัง และกลับมาใช้งานต่อจากที่ค้างไว้โดยแสดงเนื้อหาเดียวกัน ดูข้อมูลเพิ่มเติมได้ที่บันทึก Back Stack

แนวคิดหลักใน Navigation 3 API คือคุณเป็นเจ้าของ Back Stack ไลบรารี

  • คาดว่า Back Stack ของคุณจะเป็น List<T> ที่รองรับสถานะสแนปชอต โดยที่ T คือประเภทของ keys ของ Back Stack คุณสามารถใช้ Any หรือจะระบุคีย์ที่มีประเภทที่เข้มงวดกว่าของคุณเองก็ได้ เมื่อเห็นคำว่า "push" หรือ "pop" การใช้งานเบื้องหลังคือการเพิ่มหรือนำรายการออกจากท้ายรายการ
  • สังเกต Back Stack และแสดงสถานะใน UI โดยใช้ NavDisplay

ตัวอย่างต่อไปนี้แสดงวิธีสร้างคีย์และ Back Stack รวมถึงแก้ไข Back Stack เพื่อตอบสนองต่อเหตุการณ์การนำทางของผู้ใช้

// Define keys that will identify content
data object ProductList
data class ProductDetail(val id: String)

@Composable
fun MyApp() {

    // Create a back stack, specifying the key the app should start with
    val backStack = remember { mutableStateListOf<Any>(ProductList) }

    // Supply your back stack to a NavDisplay so it can reflect changes in the UI
    // ...more on this below...

    // Push a key onto the back stack (navigate forward), the navigation library will reflect the change in state
    backStack.add(ProductDetail(id = "ABC"))

    // Pop a key off the back stack (navigate back), the navigation library will reflect the change in state
    backStack.removeLastOrNull()
}

แปลงคีย์เป็นเนื้อหา

เนื้อหาจะได้รับการจำลองในการนำทาง 3 โดยใช้ NavEntry ซึ่งเป็นคลาสที่มีฟังก์ชันที่ประกอบกันได้ ซึ่งแสดงถึงปลายทาง ซึ่งเป็นเนื้อหาชิ้นเดียวที่ผู้ใช้สามารถไปยังข้างหน้าและย้อนกลับได้

NavEntry ยังมีข้อมูลเมตา ซึ่งเป็นข้อมูลเกี่ยวกับเนื้อหาได้ด้วย ออบเจ็กต์คอนเทนเนอร์ เช่น NavDisplay สามารถอ่านข้อมูลเมตานี้เพื่อช่วยตัดสินใจว่าจะแสดงเนื้อหาของ NavEntry อย่างไร เช่น คุณสามารถใช้ข้อมูลเมตาเพื่อลบล้างภาพเคลื่อนไหวเริ่มต้นสำหรับ NavEntry ที่เฉพาะเจาะจงได้ NavEntry metadata คือแผนที่ของคีย์ String ไปยังค่า Any ซึ่งให้พื้นที่เก็บข้อมูลอเนกประสงค์

หากต้องการแปลง key เป็น NavEntry ให้สร้างผู้ให้บริการรายการ ซึ่งเป็นฟังก์ชันที่ยอมรับ key และแสดงผล NavEntry สำหรับ key นั้น โดยปกติแล้วจะกำหนดเป็นพารามิเตอร์ Lambda เมื่อสร้าง NavDisplay

คุณสร้าง Entry Provider ได้ 2 วิธี ไม่ว่าจะสร้างฟังก์ชัน Lambda โดยตรง หรือใช้ DSL entryProvider

สร้างฟังก์ชัน Entry Provider โดยตรง

โดยปกติแล้ว คุณจะสร้างฟังก์ชัน Entry Provider โดยใช้คำสั่ง when โดยมีสาขาสำหรับแต่ละคีย์

entryProvider = { key ->
    when (key) {
        is ProductList -> NavEntry(key) { Text("Product List") }
        is ProductDetail -> NavEntry(
            key,
            metadata = mapOf("extraDataKey" to "extraDataValue")
        ) { Text("Product ${key.id} ") }

        else -> {
            NavEntry(Unit) { Text(text = "Invalid Key: $it") }
        }
    }
}

ใช้ DSL entryProvider

DSL ของ entryProvider ช่วยให้ฟังก์ชัน Lambda ง่ายขึ้นได้โดยไม่จำเป็นต้องทดสอบกับคีย์แต่ละประเภท และสร้าง NavEntry สำหรับคีย์แต่ละประเภท ใช้ฟังก์ชันเครื่องมือสร้าง entryProvider เพื่อดำเนินการนี้ นอกจากนี้ยังมีลักษณะการทำงานสำรองเริ่มต้น (แสดงข้อผิดพลาด) หากไม่พบคีย์

entryProvider = entryProvider {
    entry<ProductList> { Text("Product List") }
    entry<ProductDetail>(
        metadata = mapOf("extraDataKey" to "extraDataValue")
    ) { key -> Text("Product ${key.id} ") }
}

โปรดสังเกตสิ่งต่อไปนี้จากข้อมูลโค้ด

  • entry ใช้เพื่อกำหนด NavEntry ด้วยประเภทและเนื้อหาที่ประกอบกันได้ที่ระบุ
  • entry ยอมรับพารามิเตอร์ metadata เพื่อตั้งค่า NavEntry.metadata

แสดง Back Stack

Back Stack แสดงสถานะการนําทางของแอป เมื่อใดก็ตามที่ Back Stack มีการเปลี่ยนแปลง UI ของแอปควรแสดงสถานะ Back Stack ใหม่ ใน Navigation 3, NavDisplay จะสังเกต Back Stack ของคุณและอัปเดต UI ตามนั้น สร้างโดยใช้พารามิเตอร์ต่อไปนี้

  • Back Stack ของคุณ - ควรเป็นประเภท SnapshotStateList<T> โดยที่ T คือประเภทของคีย์ Back Stack ซึ่งเป็น List ที่สังเกตได้เพื่อให้ทริกเกอร์การจัดองค์ประกอบใหม่ของ NavDisplay เมื่อมีการเปลี่ยนแปลง
  • entryProvider เพื่อแปลงคีย์ใน Back Stack เป็นออบเจ็กต์ NavEntry
  • คุณสามารถระบุ Lambda ให้กับพารามิเตอร์ onBack ได้ (ไม่บังคับ) ระบบจะเรียกใช้เมธอดนี้เมื่อผู้ใช้ทริกเกอร์เหตุการณ์ย้อนกลับ

ตัวอย่างต่อไปนี้แสดงวิธีสร้าง NavDisplay

data object Home
data class Product(val id: String)

@Composable
fun NavExample() {

    val backStack = remember { mutableStateListOf<Any>(Home) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = { key ->
            when (key) {
                is Home -> NavEntry(key) {
                    ContentGreen("Welcome to Nav3") {
                        Button(onClick = {
                            backStack.add(Product("123"))
                        }) {
                            Text("Click to navigate")
                        }
                    }
                }

                is Product -> NavEntry(key) {
                    ContentBlue("Product ${key.id} ")
                }

                else -> NavEntry(Unit) { Text("Unknown route") }
            }
        }
    )
}

โดยค่าเริ่มต้น NavDisplay จะแสดง NavEntry บนสุดใน Back Stack ในเลย์เอาต์แผงเดียว ไฟล์บันทึกต่อไปนี้แสดงให้เห็นว่าแอปนี้ทำงานอยู่

ลักษณะการทำงานเริ่มต้นของ `NavDisplay` ที่มีจุดหมาย 2 แห่ง
รูปที่ 2 NavDisplayลักษณะการทำงานเริ่มต้นที่มีปลายทาง 2 แห่ง

วงจรปลายทาง

NavDisplay ใช้ LifecycleOwner ที่กำหนดเองเพื่อจำกัดสถานะวงจรของ NavEntry โดยอิงตามทั้งข้อจำกัดระดับฉากและข้อจำกัดระดับรายการ

ดูข้อมูลเพิ่มเติมเกี่ยวกับวงจรใน Compose ได้ที่วงจรใน Jetpack Compose

ข้อจำกัดของวงจรระดับฉาก

NavDisplay จะจัดการวงจรของ Scene ที่ใช้งานอยู่ ขีดจำกัดระดับฉากจะกำหนดดังนี้

สำหรับฉากที่ไม่มีการวางซ้อน ให้ทำดังนี้

  • RESUMED: อนุญาตเฉพาะเมื่อการเปลี่ยนฉากเสร็จสิ้นแล้วและไม่มีฉากซ้อนทับที่ใช้งานอยู่แสดงอยู่ด้านบน
  • STARTED: จำกัดไว้ที่ STARTED ขณะเปลี่ยนฉาก เช่น เมื่อไปยังหน้าถัดไปหรือย้อนกลับ หรือเมื่อมีภาพซ้อนทับบังอยู่

สำหรับฉากซ้อนทับ เช่น กล่องโต้ตอบหรือ Bottom Sheet ให้ทำดังนี้

  • RESUMED: อนุญาตเฉพาะฉากซ้อนทับที่อยู่ด้านบนสุดและทำงานอยู่ในปัจจุบันเท่านั้น
  • STARTED: จำกัดไว้ที่ STARTED สำหรับฉากซ้อนทับที่อยู่ด้านล่างซึ่งถูกทับด้วยการซ้อนทับที่ใหม่กว่า

สถานะวงจรระดับเริ่มต้น

ไลบรารีจะจัดการสถานะวงจรสูงสุดของ NavEntry แต่ละรายการโดยอิงตามการมีอยู่ของรายการนั้นใน Back Stack ดังนี้

  • RESUMED: หากมีรายการอยู่ใน Back Stack ปัจจุบัน ระบบจะอนุญาตให้วงจรของรายการเพิ่มขึ้นเป็น RESUMED (ขึ้นอยู่กับขีดจำกัดระดับฉาก)
  • CREATED: หากรายการไม่อยู่ใน Back Stack อีกต่อไป เช่น เมื่อรายการถูกนำออกแต่ยังคงแสดงผลบนหน้าจอขณะแสดงภาพเคลื่อนไหวออก ไลบรารีจะจำกัดวงจรของรายการไว้ที่ CREATED อย่างเคร่งครัด ขีดจำกัดนี้ช่วยให้มั่นใจได้ว่ารายการที่อยู่เบื้องหลังหรือรายการที่ออกจะหยุดทำงานที่กำลังดำเนินอยู่ เช่น การรวบรวมโฟลว์หรือการเปิด Coroutine ที่เชื่อมโยงกับสถานะ RESUMED หรือ STARTED ขณะที่รายการเหล่านั้นเปลี่ยนสถานะออกจนเสร็จสิ้น

วิธีการรวม

ตัวอย่างเช่น สถานะวงจรสุดท้ายของ NavEntry จะได้รับการแก้ไขดังนี้

สถานการณ์ ขีดจำกัดระดับฉาก หมวกระดับเริ่มต้น ราคาเสนอสูงสุดที่มีผล
รายการที่ใช้งานอยู่ หน้าจอที่นิ่ง (ไม่มีการเปลี่ยนภาพหรือการวางซ้อน) RESUMED RESUMED RESUMED
รายการที่ใช้งานอยู่ ระหว่างการเปลี่ยนผ่าน (การไปยังหรือจาก) STARTED RESUMED STARTED
รายการที่ใช้งานอยู่ซึ่งถูกวางซ้อนทับ (เช่น กล่องโต้ตอบเปิดอยู่) STARTED RESUMED STARTED
รายการที่แสดงขึ้นมา ภาพเคลื่อนไหวออก STARTED หรือ RESUMED CREATED CREATED

สรุปข้อมูลทั้งหมด

แผนภาพต่อไปนี้แสดงวิธีที่ข้อมูลไหลระหว่างออบเจ็กต์ต่างๆ ใน Navigation 3

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

  2. การเปลี่ยนแปลงสถานะ Back Stack จะทริกเกอร์การดึงข้อมูลเนื้อหา NavDisplay (Composable ที่แสดงผล Back Stack) จะสังเกต Back Stack ในการกำหนดค่าเริ่มต้น ระบบจะแสดงรายการ Back Stack บนสุดในเลย์เอาต์แผงเดียว เมื่อคีย์ด้านบนใน Back Stack มีการเปลี่ยนแปลง NavDisplay จะใช้คีย์นี้เพื่อขอเนื้อหาที่เกี่ยวข้องจากผู้ให้บริการรายการ

  3. ผู้ให้บริการรายการจะจัดหาเนื้อหา ผู้ให้บริการรายการคือฟังก์ชันที่แปลงคีย์เป็น NavEntry เมื่อได้รับคีย์จาก NavDisplay ผู้ให้บริการรายการจะให้ NavEntry ที่เชื่อมโยง ซึ่งมีทั้งคีย์และเนื้อหา

  4. เนื้อหาจะแสดง NavDisplay จะได้รับ NavEntry และแสดงเนื้อหา