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

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

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

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

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

Navigation 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

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

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

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

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

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

सीधे तौर पर एंट्री प्रोवाइडर फ़ंक्शन बनाना

आम तौर पर, 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") }
        }
    }
}
BasicSnippets.kt

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

entryProvider डीएसएल, आपके लैम्डा फ़ंक्शन को आसान बना सकता है. इसके लिए, आपको अपने हर मुख्य टाइप के हिसाब से जांच करने और हर टाइप के लिए 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 पैरामीटर स्वीकार करता है

पिछली ऐक्टिविटी दिखाएं

बैक स्टैक, आपके ऐप्लिकेशन की नेविगेशन स्थिति को दिखाता है. जब भी बैक स्टैक में बदलाव होता है, तो ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में बैक स्टैक की नई स्थिति दिखनी चाहिए. Navigation 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 दिखाता है. इस रिकॉर्डिंग में, इस ऐप्लिकेशन को चलते हुए दिखाया गया है:

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

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

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

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

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

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