Nav3 روٹر: Jetpack Navigation 3 کے اوپر پر آسان نائیجیریا

Jetpack Navigation 3 کیا ہے؟ Jetpack Navigation 3 ایک نئی گوگل نیویگیشن لائبریری ہے جو پچھلے ورژن سے بنیادی طور پر مختلف ہے. Nav3 کا بنیادی خیال سادہ ہے: آپ کو ایک — ایک معمولی متغیر کی فہرست جہاں ہر عنصر آپ کے ایپلی کیشن میں ایک سکرین کی نمائندگی کرتا ہے. NavBackStack آپ اس فہرست سے عناصر شامل کرتے ہیں اور حذف کرتے ہیں، اور UI خود بخود اپ ڈیٹ کرتا ہے. - ایک معمولی Kotlin کلاس. NavKey یہ آپ کو نیویگیشن پر مکمل کنٹرول فراہم کرتا ہے، لیکن عام آپریشنوں کے لئے کافی بہت سے boilerplate کوڈ لکھنے کی ضرورت ہے. NavBackStack کے ساتھ براہ راست کام کرنا کیوں غیر معمولی ہے ہم دیکھیں کہ کوڈ کے ساتھ براہ راست کام کرتے وقت کیسا لگتا ہے : NavBackStack @Composable fun MyApp() { val backStack = rememberNavBackStack(Screen.Home) // Add a screen backStack.add(Screen.Details("123")) // Go back backStack.removeLastOrNull() // Replace current screen backStack.set(backStack.lastIndex, Screen.Success) } مسئلہ شروع ہوتا ہے جب آپ کو ایک ViewModel سے نیویگیشن کو چالو کرنے کی ضرورت ہوتی ہے. ViewModel (جو، میرے خیال میں، آرکیٹیکل اصولوں کی خلاف ورزی کرتا ہے، کیونکہ مجھے لگتا ہے کہ ViewModel کو Compose مخصوص چیزوں کے بارے میں نہیں جاننا چاہئے)، یا ہر نائیجنگ کارروائی کے لئے intermediate callbacks بنائیں. NavBackStack اس کے علاوہ، براہ راست اسٹاک کے ساتھ کام کرتے وقت، یہ آسانی سے کنڈج کیسز کا انتظام کرنے کے لئے بھولنا ہے. Nav3 روٹر کام کو آسان بنانے کے لئے کس طرح Nav3 Router Navigation 3 کے مقابلے میں ایک ٹھنڈا wrapper ہے جو نائیجیریا کے لئے ایک مشہور API فراہم کرتا ہے. انڈیکس اور فہرست آپریشنوں کے بارے میں سوچنے کے بجائے، آپ صرف "X سکرین پر جائیں" یا "بہت واپس جائیں." اہم نقطہ: Nav3 روٹر اپنے سٹاک کو پیدا نہیں کرتا. یہ اسی کے ساتھ کام کرتا ہے کہ Navigation 3 فراہم کرتا ہے، صرف اس کے ساتھ کام کرنے کے لئے آسان بناتا ہے. ، لائبریری اس کو اصل پیکیج کے ساتھ متعلقہ عمل میں ترجمہ کرتا ہے. NavBackStack router.push(Screen.Details) اہم فوائد: ViewModel سے استعمال کیا جا سکتا ہے نائیجیریا کمانڈز کو بفرل کیا جاتا ہے اگر UI موقتی طور پر دستیاب نہیں ہے (مثال کے طور پر، اسکرین rotation کے دوران) تمام اسٹاک آپریشنوں کو ایٹمی طور پر ہوتا ہے صاف آگ تبدیلی اور اپنی مرضی کے رویے کو شامل کرنے میں انعطاف تنصیب Nav3 Router Maven Central پر دستیاب ہے. آپ کے : build.gradle.kts // For shared module in KMP project kotlin { sourceSets { commonMain.dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } } } // For Android-only project dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } لائبریری کے ذریعہ کوڈ GitHub پر دستیاب ہے: github.com/arttttt/Nav3Router سے رابطہ کریں Nav3 Router کیسے تعمیر کیا جاتا ہے لائبریری تین بنیادی حصوں پر مشتمل ہے، ہر ایک اپنے کام کو حل کرتا ہے: Router - ڈویلپر انٹرفیس Router اس طرح کے طریقوں کو فراہم کرتا ہے ، ، جب آپ ان طریقوں کو بلاتے ہیں تو راٹر مندرجہ ذیل کمانڈز پیدا کرتا ہے اور ان کو زنجیر پر بھیجتا ہے. راٹر اپنے آپ کو اس کے بارے میں کچھ بھی نہیں جانتا ہے کہ کس طرح نائیجیریا کو انجام دیا جائے گا - یہ کسی بھی جگہ سے اس کا استعمال کرنے کی اجازت دیتا ہے. push() pop() replace() CommandQueue - کمانڈز اور ان کے عمل کے درمیان بوسر CommandQueue وقت کے مسئلے کو حل کرتا ہے. تصور کریں: صارف نے اسکرین کے دورے کے دوران ایک بٹن پر کلک کیا. UI کو دوبارہ تخلیق کیا جا رہا ہے، اور نائجیریٹر موقتی طور پر دستیاب نہیں ہے. CommandQueue کمانڈ کو محفوظ کرے گا اور اسے دوبارہ چلائے گا جب نائجیریٹر تیار ہو جائے گا. // Simplified queue logic class CommandQueue { private var navigator: Navigator ? = null private val pending = mutableListOf >() fun executeCommand(command: Command ) { if (navigator != null) { navigator.apply(command) // Navigator exists - execute immediately } else { pending.add(command) // No - save for later } } } Navigator - وہ جو Stack کے ساتھ کام کرتا ہے Navigator کمانڈز لیتا ہے اور ان کو لاگو کرتا ہے اہم تفصیلات: یہ سب سے پہلے موجودہ سٹاک کا ایک کاپی بناتا ہے، اس پر تمام کمانڈز کو لاگو کرتا ہے، اور صرف اس کے بعد اصل سٹاک کو ترمیم شدہ کاپی کے ساتھ آٹو طور پر تبدیل کرتا ہے. NavBackStack // Simplified Navigator logic fun applyCommands(commands: Array ) { val stackCopy = backStack.toMutableList() // Work with a copy for (command in commands) { when (command) { is Push -> stackCopy.add(command.screen) is Pop -> stackCopy.removeLastOrNull() // ... other commands } } backStack.swap(stackCopy) // Atomically apply changes } Nav3 Router کے ساتھ شروع کریں سب سے آسان طریقہ یہ ہے کہ آپ روٹر کو دستی طور پر نہیں بنائیں۔ Nav3Host آپ کے لئے یہ کام کرے گا: @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) // Nav3Host will create Router automatically Nav3Host(backStack = backStack) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen( onOpenDetails = { router.push(Screen.Details) // Use router } ) } entry { DetailsScreen( onBack = { router.pop() } ) } } ) } } زیادہ پیچیدہ ایپلی کیشنز کے لئے، DI کے ذریعے ایک راٹر بنانے اور اسے ViewModel میں منتقل کرنے کا مطلب ہے: سکرین کا تعین کریں @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen @Serializable data object Cart : Screen } Nav3Host پر راٹر منتقل کریں. @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) val router: Router = getSomehowUsingDI() // Pass Router to Nav3Host Nav3Host( backStack = backStack, router = router, ) { backStack, onBack, _ -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen() } entry { DetailsScreen() } } ) } } ViewModel constructor کے ذریعے روٹر وصول کرتا ہے. class ProductViewModel( private val router: Router , private val cartRepository: CartRepository ) : ViewModel() { fun addToCart(productId: String) { viewModelScope.launch { cartRepository.add(productId) router.push(Screen.Cart) // Navigation from ViewModel } } } UI میں، صرف ViewModel کا استعمال کریں. @Composable fun ProductScreen(viewModel: ProductViewModel = koinViewModel()) { Button(onClick = { viewModel.addToCart(productId) }) { Text("Add to Cart") } } Typical Scenarios کی مثالیں آسانی سے پیچھے کی نائجیریا // Navigate to a new screen router.push(Screen.Details(productId)) // Go back router.pop() // Navigate with replacement of current screen (can't go back) router.replaceCurrent(Screen.Success) Screen Chains کے ساتھ کام // Open multiple screens at once router.push( Screen.Category("electronics"), Screen.Product("laptop-123"), Screen.Reviews("laptop-123") ) // Return to a specific screen // Will remove all screens above Product from the stack router.popTo(Screen.Product("laptop-123")) چیک آؤٹ سکرین @Composable fun CheckoutScreen(router: Router ) { Button( onClick = { // After checkout we need to: // 1. Show confirmation screen // 2. Prevent going back to cart router.replaceStack( Screen.Home, Screen.OrderSuccess(orderId) ) // Now only Home and OrderSuccess are in the stack } ) { Text("Place Order") } } نائجیریا سے باہر نکلنا // User is deep in settings: // Home -> Settings -> Account -> Privacy -> DataManagement // "Done" button should return to home Button( onClick = { // Will leave only root (Home) router.clearStack() } ) { Text("Done") } // Or if you need to close the app from anywhere Button( onClick = { // Will leave only current screen and trigger system back router.dropStack() } ) { Text("Exit") } Bonus: SceneStrategy اور بات چیت اب تک، ہم نے صرف اسکرینوں کے درمیان سادہ نقل و حمل کے بارے میں بات کی ہے. لیکن اگر آپ کو ایک ڈیوائس یا نیچے کی فہرست دکھانے کی ضرورت ہے تو کیا؟ یہاں Navigation 3 سے SceneStrategy مفهوم مدد کے لئے آتا ہے. SceneStrategy کیا ہے؟ SceneStrategy ایک میکانیزم ہے جو اس بات کا تعین کرتا ہے کہ آپ کے اسٹاک سے اسکرین کس طرح دکھایا جائے گا. ، جس میں صرف اسٹاک سے آخری سکرین دکھاتا ہے. لیکن آپ کو زیادہ پیچیدہ سکرین کے لئے اپنے حکمت عملی پیدا کر سکتے ہیں. SinglePaneSceneStrategy SceneStrategy کو ایک ڈائریکٹر کے طور پر سوچو جو آپ کے اسکرینوں کی ایک سیٹ کو دیکھتا ہے اور فیصلہ کرتا ہے: "ہاں، ان تین اسکرینوں کو ہم عام طور پر دکھاتے ہیں، لیکن یہ آخری ایک - پہلے لوگوں کے اوپر ایک ماڈل ونڈوز کے طور پر". ModalBottomSheet کے لئے ایک حکمت عملی بنائیں ہم ایک حکمت عملی بنائیں جو کچھ اسکرینوں کو نیچے کے شیٹ کے طور پر دکھائے گا. سب سے پہلے، ہم اس طرح کے اسکرینوں کو کیسے نشانہ بنائیں گے کی وضاحت کریں گے: @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen // This screen will be shown as bottom sheet @Serializable data object Filters : Screen } اب، ہم خود کی حکمت عملی بنائیں. یہ آخری سکرین کے میٹا ڈیٹا کو چیک کرے گا اور، اگر یہ ایک خاص مارکر تلاش کرتا ہے، تو اسے ایک نیچے کی فہرست کے طور پر دکھائے گا: class BottomSheetSceneStrategy : SceneStrategy { companion object { // Metadata key by which we identify bottom sheet private const val BOTTOM_SHEET_KEY = "bottomsheet" // Helper function to create metadata fun bottomSheet(): Map { return mapOf(BOTTOM_SHEET_KEY to true) } } @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check if the last screen has bottom sheet marker val isBottomSheet = lastEntry.metadata[BOTTOM_SHEET_KEY] as? Boolean if (isBottomSheet == true) { // Return special Scene for bottom sheet return BottomSheetScene( entry = lastEntry, previousEntries = entries.dropLast(1), onBack = onBack ) } // This is not a bottom sheet, let another strategy handle it return null } } کئی پالیسیوں کا مجموعہ ایک حقیقی ایپلی کیشن میں، آپ کو نیچے ٹیبلز، بات چیت، اور باقاعدگی سے اسکرین کی ضرورت ہوسکتی ہے. اس کے لئے، آپ ایک نمائندے کی حکمت عملی پیدا کرسکتے ہیں جو ہر اسکرین کے لئے صحیح حکمت عملی منتخب کرے گا: class DelegatedScreenStrategy ( private val strategyMap: Map >, private val fallbackStrategy: SceneStrategy ) : SceneStrategy { @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check all keys in metadata for (key in lastEntry.metadata.keys) { val strategy = strategyMap[key] if (strategy != null) { // Found suitable strategy return strategy.calculateScene(entries, onBack) } } // Use default strategy return fallbackStrategy.calculateScene(entries, onBack) } } درخواست میں استعمال اب، ہم سب کو جمع کریں. یہاں ایک حقیقی ایپلی کیشن میں نیچے شیٹ کا استعمال کرتے ہوئے کیا نظر آتا ہے: @Composable fun ShoppingApp() { val backStack = rememberNavBackStack(Screen.Home) val router = rememberRouter () Nav3Host( backStack = backStack, router = router ) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, // Use our combined strategy sceneStrategy = DelegatedScreenStrategy( strategyMap = mapOf( "bottomsheet" to BottomSheetSceneStrategy(), "dialog" to DialogSceneStrategy() // Navigation 3 already has this strategy ), fallbackStrategy = SinglePaneSceneStrategy() // Regular screens ), entryProvider = entryProvider { entry { HomeScreen( onOpenFilters = { // Open filters as bottom sheet router.push(Screen.Filters) } ) } entry { screen -> ProductScreen(productId = screen.id) } // Specify that Filters should be bottom sheet entry ( metadata = BottomSheetSceneStrategy.bottomSheet() ) { FiltersContent( onApply = { filters -> // Apply filters and close bottom sheet applyFilters(filters) router.pop() } ) } } ) } } یہاں کیا ہو رہا ہے؟ جب آپ کال کرتے ہیں لیکن میٹا ڈیٹا اور ہماری حکمت عملی کے لئے شکریہ، UI سمجھتا ہے کہ اس سکرین کو اگلے سکرین کے اوپر ایک نیچے شیٹ کے طور پر دکھایا جانا چاہئے، اس کے بجائے اسے مکمل طور پر تبدیل کرنے کے لئے. router.push(Screen.Filters) کال کرتے وقت نیچے کا شیٹ بند ہو جائے گا، اور آپ گزشتہ سکرین پر واپس جائیں گے.روٹر کے نقطہ نظر سے، یہ باقاعدگی سے واپس پلگ ان ہے، لیکن بصری طور پر یہ ایک ماڈل ونڈوز کو بند کرنے کی طرح لگتا ہے. router.pop() اس نقطہ نظر کے فوائد SceneStrategy کا استعمال کرتے ہوئے کئی اہم فوائد فراہم کرتے ہیں. سب سے پہلے، آپ کی نائیجنگ منطق سادہ ہے - آپ اب بھی استعمال کرتے ہیں اور دوسری صورت میں، نائیجیریا کی حالت مطابقت رکھتا ہے - نیچے کا شیٹ صرف اسٹاک میں ایک اور سکرین ہے جو سکرین روٹنگ یا عمل کو مارنے کے دوران مناسب طریقے سے محفوظ کیا جاتا ہے. اور آخر میں، یہ بہت زیادہ انعطاف پذیری فراہم کرتا ہے - آپ آسانی سے نائیجیریا کی منطق کو ٹچ کرنے کے بغیر اس کے میٹا ڈیٹا کو تبدیل کرکے ایک سکرین کو ظاہر کرنے کا طریقہ تبدیل کرسکتے ہیں. push pop مثال کے طور پر، لاگ ان اسکرین پہلی اپلی کیشن شروع کرنے پر ایک معمولی اسکرین اور ایک ماڈل بات چیت ہوسکتا ہے جب ایک کارروائی کو انجام دینے کی کوشش کرتے ہیں جس کی اجازت کی ضرورت ہوتی ہے. Nav3 Router کیوں استعمال کرنا چاہئے Nav3 روٹر نائجیریا 3 کو تبدیل کرنے یا نئے خصوصیات شامل کرنے کی کوشش نہیں کرتا. اس کا کام نائجیریا کے ساتھ کام کرنے کے لئے آسان اور پیشہ ورانہ بنانے کے لئے ہے. آپ کو ایک سادہ API ملتا ہے جو ایپلی کیشن کے کسی بھی layer سے استعمال کیا جا سکتا ہے، وقت کے مسائل کا خود کار طریقے سے انتظام، اور آسانی سے نائجیریا منطق کا تجربہ کرنے کی صلاحیت. ایک ہی وقت میں، کلاؤڈ کے تحت، باقاعدگی سے نائجیریا 3 اب بھی اس کی تمام صلاحیتوں کے ساتھ کام کرتا ہے: اسٹیڈیم بچاؤ، انیمیشن کی حمایت، اور نظام "بٹ" بٹن کا مناسب انتظام. اگر آپ پہلے سے ہی نائجیریا 3 کا استعمال کر رہے ہیں یا اس پر منتقل کرنے کی منصوبہ بندی کر رہے ہیں تو، Nav3 روٹر اس تجربے کو زیادہ لطف اندوز کرنے میں مدد ملے گی، پروجیکٹ کو غیر ضروری پیچیدگی شامل کرنے کے بغیر. بائیں GitHub کے ذخائر: github.com/arttttt/Nav3Router استعمال کی مثالیں: اسٹوریج میں sample folder دیکھیں