ใช้ตรรกะหรือ Wrapper กับปลายทาง

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

สร้างเดคอเรเตอร์ที่กำหนดเอง

หากต้องการสร้างเดคอเรเตอร์ ให้ขยายคลาส NavEntryDecorator และลบล้างเมธอดต่อไปนี้

  • decorate - แลมบ์ดาที่ประกอบกันได้ซึ่งเรียกใช้สำหรับ NavEntry แต่ละรายการใน Back Stack โดยจะได้รับ NavEntry เป็นพารามิเตอร์ ซึ่งจะช่วยให้คุณสร้างออบเจ็กต์สถานะที่เชื่อมโยงกับ contentKey ของรายการได้ คุณสามารถใช้ CompositionLocalProvider เพื่อระบุทรัพยากร Dependency ให้กับเนื้อหาของรายการได้ นอกจากนี้ คุณยังล้อมรอบเนื้อหาด้วยฟังก์ชันที่ประกอบกันได้หรือทริกเกอร์ผลข้างเคียงได้ด้วย คุณควรเรียกใช้ entry.Content() ภายในเมธอดนี้เสมอ
  • onPop - Callback ที่เรียกใช้เมื่อนำ NavEntry ออกจาก Back Stack และออกจาก Composition โดยจะได้รับ contentKey ของรายการที่นำออก ใช้ contentKey เพื่อระบุและล้างสถานะที่เชื่อมโยงกับรายการนั้น

ตัวอย่างต่อไปนี้จะขยายคลาส NavEntryDecorator เพื่อสร้างเดคอเรเตอร์ที่กำหนดเอง

// import androidx.navigation3.runtime.NavEntryDecorator
class CustomNavEntryDecorator<T : Any> : NavEntryDecorator<T>(
    decorate = { entry ->
        Log.d("CustomNavEntryDecorator", "entry with ${entry.contentKey} entered composition and was decorated")
        entry.Content()
    },
    onPop = { contentKey -> Log.d("CustomNavEntryDecorator", "entry with $contentKey was popped") }
)

หากเดโคเรเตอร์ต้องการเข้าถึงสถานะ ให้สร้างฟังก์ชันที่ประกอบกันได้ซึ่งสร้างสถานะนั้น แล้วใช้ฟังก์ชันดังกล่าวเพื่อสร้างเดโคเรเตอร์ ดูตัวอย่างการติดตั้งใช้งานได้ที่ซอร์สโค้ดของ rememberSaveableStateHolderNavEntryDecorator ซึ่งจะสร้างสถานะ SaveableStateHolder และใช้สถานะดังกล่าวเพื่อสร้างเดคอเรเตอร์

ตกแต่ง Back Stack

เมื่อสร้าง NavEntryDecorator แล้ว ให้ตกแต่งรายการใน Back Stack ด้วยวิธีใดวิธีหนึ่งจาก 2 วิธีต่อไปนี้

  • ใช้ rememberDecoratedNavEntries ฟังก์ชันนี้มีประโยชน์เมื่อคุณมี Back Stack หลายรายการ โดยแต่ละรายการมีชุดเดคอเรเตอร์ของตัวเอง (ดูรายละเอียดเพิ่มเติมได้ที่สูตรโค้ดนี้) ฟังก์ชันจะแสดงผลรายการ NavEntry ที่ตกแต่งแล้วซึ่งคุณใช้กับ NavDisplay ได้
  • ระบุเดคอเรเตอร์ของคุณไปยัง NavDisplay โดยตรงโดยใช้พารามิเตอร์ entryDecorators NavDisplay เรียกใช้ rememberDecoratedNavEntries เบื้องหลังและแสดงรายการที่ตกแต่งแล้ว

รวมเดคอเรเตอร์เริ่มต้น

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

คุณควรใส่ SaveableStateHolderNavEntryDecorator เป็นเดคอเรเตอร์แรกในรายการเดคอเรเตอร์ที่ระบุ เว้นแต่ว่าเดคอเรเตอร์จะระบุ SaveableStateProvider ซึ่งสร้างขึ้นโดยใช้ rememberSaveableStateHolderNavEntryDecorator

เช่น

// import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
NavDisplay(
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        remember { CustomNavEntryDecorator() }
    ),
    // ...
)

ส่งผลลัพธ์โดยใช้ ResultEventBusNavEntryDecorator

ตั้งแต่ Navigation 3 1.2.0 เป็นต้นไป คุณสามารถใช้ ResultEventBusNavEntryDecorator เพื่อระบุ ResultEventBus ให้กับ NavEntry แต่ละรายการโดยใช้ LocalResultEventBus Composition Local

โดยค่าเริ่มต้น rememberResultEventBusNavEntryDecorator จะสร้างและจดจำอินสแตนซ์ ResultEventBus ของ ตัวเองภายในโดยใช้ rememberResultEventBus หากต้องการเข้าถึงบัสเหตุการณ์นอกลำดับชั้นของเดคอเรเตอร์ (เช่น ที่โครงสร้างแอปในระดับบนสุด) คุณสามารถยก ResultEventBus ขึ้นโดยเรียกใช้ rememberResultEventBus และส่งไปยัง rememberResultEventBusNavEntryDecorator(resultEventBus) ดังนี้

val resultEventBus = rememberResultEventBus()

NavDisplay(
    /* ... */
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberResultEventBusNavEntryDecorator(resultEventBus = resultEventBus)
    )
)

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการส่งและสังเกตผลลัพธ์ได้ที่แสดงผลลัพธ์

กรณีที่ควรใช้เดคอเรเตอร์

ใช้เดคอเรเตอร์เพื่อทำสิ่งต่อไปนี้

  • สร้างทรัพยากร Dependency สำหรับทุก NavEntry ใน Back Stack ตัวอย่างเช่น ViewModelStoreNavEntryDecorator จะสร้าง ViewModelStore สำหรับทุกๆ NavEntry
  • ส่งผลลัพธ์และสื่อสารระหว่างปลายทาง เช่น ResultEventBusNavEntryDecorator จะมี ResultEventBus ไปยังปลายทางใน Back Stack
  • กำหนดขอบเขตออบเจ็กต์ให้กับ NavEntry หลายรายการ เช่น หากต้องการแชร์ ViewModel ระหว่างหลายรายการ
  • ดำเนินการเดียวกันกับ NavEntry หลายรายการ เช่น เพื่อดำเนินการบันทึก การแก้ไขข้อบกพร่อง หรือการติดตามสำหรับแต่ละรายการ
  • รวม NavEntry ไว้ในฟังก์ชันที่ประกอบกันได้เดียวกัน
  • ล้างสถานะที่เชื่อมโยงกับ NavEntry รายการ ตัวอย่างเช่น เมื่อนำรายการออกจาก Back Stack ViewModelStoreNavEntryDecorator จะล้าง ViewModelStore ที่เชื่อมโยง

อย่าใช้เดคอเรเตอร์เพื่อทำสิ่งต่อไปนี้

  • ส่งทรัพยากร Dependency ไปยัง NavEntry รายการเดียว
  • ระบุทรัพยากร Dependency ที่มีขอบเขตกว้างกว่า Back Stack

ในทั้ง 2 กรณีนี้ ให้ส่งทรัพยากร Dependency โดยตรงเมื่อสร้าง NavEntry แทน

ดูตัวอย่างโค้ดเพิ่มเติมได้ที่ NavEntryDecorator