बुनियादी बातों को समझना और उन्हें लागू करना

संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

नेविगेशन से पता चलता है कि उपयोगकर्ता आपके ऐप्लिकेशन में किस तरह से एक से दूसरी जगह जाते हैं. आम तौर पर, उपयोगकर्ता यूज़र इंटरफ़ेस (यूआई) के एलिमेंट पर टैप या क्लिक करके इंटरैक्ट करते हैं. इसके बाद, ऐप्लिकेशन नया कॉन्टेंट दिखाकर जवाब देता है. अगर उपयोगकर्ता को पिछले कॉन्टेंट पर वापस जाना है, तो वह 'वापस जाएं' जेस्चर का इस्तेमाल करता है या 'वापस जाएं' बटन पर टैप करता है.

नेविगेशन की स्थिति को मॉडल करना

इस व्यवहार का मॉडल बनाने का आसान तरीका, कॉन्टेंट के स्टैक का इस्तेमाल करना है. जब उपयोगकर्ता नए कॉन्टेंट पर आगे बढ़ता है, तो उसे स्टैक में सबसे ऊपर ले जाया जाता है. जब उपयोगकर्ता उस कॉन्टेंट से वापस जाते हैं, तो वह स्टैक से हट जाता है और पिछला कॉन्टेंट दिखने लगता है. नेविगेशन के हिसाब से, इस स्टैक को आम तौर पर बैक स्टैक कहा जाता है. ऐसा इसलिए, क्योंकि यह उस कॉन्टेंट को दिखाता है जिस पर उपयोगकर्ता वापस जा सकता है.

बैक स्टैक बनाना

नेविगेशन 3 में, बैक स्टैक में कोई कॉन्टेंट नहीं होता. इसके बजाय, इसमें कॉन्टेंट के रेफ़रंस होते हैं. इन्हें कुंजियां कहा जाता है. कुंजियां किसी भी तरह की हो सकती हैं, लेकिन आम तौर पर ये आसान और सीरियलाइज़ की जा सकने वाली डेटा क्लास होती हैं. कॉन्टेंट के बजाय रेफ़रंस का इस्तेमाल करने के ये फ़ायदे हैं:

• बैक स्टैक पर बटन दबाकर, नेविगेट करना आसान है.
• जब तक कुंजियों को सीरियल किया जा सकता है, तब तक बैक स्टैक को स्टोरेज में सेव किया जा सकता है. इससे, कॉन्फ़िगरेशन में हुए बदलावों और प्रोसेस के बंद होने के बाद भी, बैक स्टैक को सेव रखा जा सकता है. यह ज़रूरी है, क्योंकि उपयोगकर्ता आपके ऐप्लिकेशन को छोड़कर, बाद में उस पर वापस आ सकते हैं. साथ ही, वे उसी कॉन्टेंट को देखना चाहते हैं जिसे उन्होंने आखिरी बार देखा था. ज़्यादा जानकारी के लिए, अपना बैक स्टैक सेव करना लेख पढ़ें.

Navigation 3 API का एक मुख्य कॉन्सेप्ट यह है कि बैक स्टैक पर आपका मालिकाना हक होता है. लाइब्रेरी:

• यह उम्मीद की जाती है कि आपका बैक स्टैक, स्नैपशॉट की स्थिति का बैक अप लेने वाला List<T> होगा. यहां T, आपके बैक स्टैक keys का टाइप है. Any का इस्तेमाल किया जा सकता है या अपनी ज़्यादा सटीक टाइप की कुंजियां दी जा सकती हैं. जब आपको "पुश" या "पॉप" शब्द दिखते हैं, तो इसका मतलब है कि सूची के आखिर में आइटम जोड़े या हटाए जा रहे हैं.
• यह आपके बैक स्टैक को मॉनिटर करता है और NavDisplay का इस्तेमाल करके, यूज़र इंटरफ़ेस (यूआई) में इसकी स्थिति दिखाता है.

नीचे दिए गए उदाहरण में, बटन और बैक स्टैक बनाने का तरीका बताया गया है. साथ ही, उपयोगकर्ता के नेविगेशन इवेंट के जवाब में बैक स्टैक में बदलाव करने का तरीका भी बताया गया है:

// 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()
}
BasicSnippets.kt

कॉन्टेंट के लिए कुंजियां हल करना

नेविगेशन 3 में कॉन्टेंट को NavEntry का इस्तेमाल करके मॉडल किया जाता है. यह एक ऐसी क्लास है जिसमें कॉम्पोज़ेबल फ़ंक्शन होता है. यह किसी डेस्टिनेशन को दिखाता है. यह एक ऐसा कॉन्टेंट होता है जिस पर उपयोगकर्ता आगे और पीछे जा सकता है.

NavEntry में मेटाडेटा भी शामिल हो सकता है - कॉन्टेंट के बारे में जानकारी. इस मेटाडेटा को NavDisplay जैसे कंटेनर ऑब्जेक्ट पढ़ सकते हैं, ताकि वे यह तय कर सकें कि NavEntry के कॉन्टेंट को कैसे दिखाया जाए. उदाहरण के लिए, किसी खास NavEntry के लिए डिफ़ॉल्ट ऐनिमेशन को बदलने के लिए, मेटाडेटा का इस्तेमाल किया जा सकता है. NavEntrymetadata, String कुंजियों से Any वैल्यू का मैप है. यह कई तरह का डेटा स्टोरेज उपलब्ध कराता है.

key को NavEntry में बदलने के लिए, entryProvider बनाएं. यह एक ऐसा फ़ंक्शन है जो key को स्वीकार करता है और उस key के लिए NavEntry दिखाता है. आम तौर पर, NavDisplay बनाते समय इसे लैम्ब्डा पैरामीटर के तौर पर तय किया जाता है.

entryProvider बनाने के दो तरीके हैं. पहला, सीधे तौर पर कोई लैम्ब्डा फ़ंक्शन बनाना और दूसरा, entryProvider DSL का इस्तेमाल करना.

सीधे entryProvider फ़ंक्शन बनाना

आम तौर पर, when स्टेटमेंट का इस्तेमाल करके entryProvider फ़ंक्शन बनाया जाता है. इसमें, हर बटन के लिए एक शाखा होती है.

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") }
        }
    }
}
BasicSnippets.kt

entryProvider डीएसएल का इस्तेमाल करना

entryProvider DSL, आपके हर की-टाइप की जांच करने की ज़रूरत को कम करके, आपके लैम्ब्डा फ़ंक्शन को आसान बना सकता है. साथ ही, हर एक के लिए NavEntry बना सकता है. इसके लिए, entryProvider बिल्डर फ़ंक्शन का इस्तेमाल करें. इसमें, कुंजी न मिलने पर डिफ़ॉल्ट फ़ॉलबैक व्यवहार (गड़बड़ी का मैसेज दिखाना) भी शामिल है.

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

स्निपेट में इन बातों का ध्यान रखें:

• entry का इस्तेमाल, दिए गए टाइप और कॉम्पोज़ किए जा सकने वाले कॉन्टेंट के साथ NavEntry तय करने के लिए किया जाता है
• entry, NavEntry.metadata सेट करने के लिए metadata पैरामीटर स्वीकार करता है

बैक स्टैक दिखाना

बैक स्टैक, आपके ऐप्लिकेशन के नेविगेशन स्टेटस को दिखाता है. जब भी बैक स्टैक में बदलाव होता है, तो ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में बैक स्टैक की नई स्थिति दिखनी चाहिए. नेविगेशन 3 में, NavDisplay आपके बैक स्टैक को मॉनिटर करता है और उसके हिसाब से अपना यूज़र इंटरफ़ेस (यूआई) अपडेट करता है. इसे इन पैरामीटर के साथ बनाएं:

• आपका बैक स्टैक - यह SnapshotStateList<T> टाइप का होना चाहिए, जहां T आपके बैक स्टैक बटन का टाइप है. यह एक ऐसा List है जिसे ऑब्ज़र्व किया जा सकता है, ताकि बदलाव होने पर यह NavDisplay के फिर से कॉम्पोज़ होने को ट्रिगर कर सके.
• आपके बैक स्टैक में मौजूद बटन को NavEntry में बदलने के लिए entryProvider.
• इसके अलावा, 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") }
            }
        }
    )
}
BasicSnippets.kt

डिफ़ॉल्ट रूप से, NavDisplay एक पैनल वाले लेआउट में, बैक स्टैक में सबसे ऊपर मौजूद NavEntry दिखाता है. इस रिकॉर्डिंग में, यह ऐप्लिकेशन चलता हुआ दिख रहा है:

यह रही पूरी जानकारी

नीचे दिए गए डायग्राम में दिखाया गया है कि नेविगेशन 3 में, अलग-अलग ऑब्जेक्ट के बीच डेटा कैसे फ़्लो करता है:

1. नेविगेशन इवेंट, बदलावों को शुरू करते हैं. उपयोगकर्ता के इंटरैक्शन के जवाब में, बटन को बैक स्टैक में जोड़ा या हटाया जाता है.

2. बैक स्टैक के स्टेटस में बदलाव होने पर, कॉन्टेंट वापस पाने की प्रोसेस शुरू हो जाती है. NavDisplay (बैक स्टैक को रेंडर करने वाला कॉम्पोज़ेबल), बैक स्टैक को देखता है. डिफ़ॉल्ट कॉन्फ़िगरेशन में, यह सबसे ऊपर मौजूद बैक स्टैक एंट्री को एक पैनल लेआउट में दिखाता है. जब बैक स्टैक पर सबसे ऊपर मौजूद बटन बदलता है, तो NavDisplay इस बटन का इस्तेमाल करके, एंट्री देने वाली कंपनी से उससे जुड़े कॉन्टेंट का अनुरोध करता है.

3. एंट्री देने वाली कंपनी कॉन्टेंट उपलब्ध कराती है. एंट्री प्रोवाइडर एक ऐसा फ़ंक्शन है जो किसी कुंजी को NavEntry में बदलता है. NavDisplay से पासकोड मिलने के बाद, एंट्री की सेवा देने वाली कंपनी उससे जुड़ा NavEntry उपलब्ध कराती है. इसमें पासकोड और कॉन्टेंट, दोनों शामिल होते हैं.

4. कॉन्टेंट दिखता है. NavDisplay को NavEntry मिलता है और वह कॉन्टेंट दिखाता है.