انتقال به «پیمایش ۳»

«پیمایش ۳» نشان‌دهنده تغییری اساسی در نحوه مدیریت حالت پیمایش توسط Jetpack Compose است و مزایای معماری قابل‌توجهی نسبت به «پیمایش ۲» ارائه می‌دهد.

با تغییرات معماری و مراحل لازم برای انتقال برنامه Wear Compose از «پیمایش ۲» به «پیمایش ۳» آشنا شوید.

مزایای کلیدی «پیمایش ۳»

  • کنترل پشته برگشت مستقیم: NavBackStack اساساً فقط فهرستی تغییرپذیر از اشیای NavKey است که سابقه صفحه‌هایی را که کاربر بازدید کرده است نشان می‌دهد. دقیقاً مثل هر Kotlin دیگری MutableList (add،‏ removeLast،‏ clear) آن را کنترل می‌کنید. برای انجام کنش‌های پیمایش، مثل افزودن کلید برای رفتن به جلو یا برداشتن کلید برای رفتن به عقب، مستقیماً فهرست را دستکاری می‌کنید.
  • طراحی «ترکیب اول»: پشته پشتی به‌عنوان وضعیت قابل‌مشاهده استاندارد مدل‌سازی می‌شود. تغییر سابقه پیمایش دقیقاً مانند به‌روزرسانی هر وضعیت «نگارش» دیگری عمل می‌کند و به‌طور خودکار باعث بازترکیب برای نمایش صفحه فعلی می‌شود.
  • امن ازنظر نوع به‌طور پیش‌فرض: مسیرهای مبتنی بر رشته به‌طور کامل حذف می‌شوند. ناوبری از اشیای داده و کلاس‌های داده سریال‌شدنی استفاده می‌کند.
  • ارائه‌های جداشده (استراتژی‌های صحنه): لایه انتقال میانای کاربر (NavDisplay و SwipeDismissableSceneStrategy) به‌طور کامل از پیگیری وضعیت (NavBackStack) جدا شده است و امکان ادغام ساده‌تر انتقال‌های پیمایش داخلی Wear OS را فراهم می‌کند.

مراحل انتقال

۱. به‌روزرسانی وابستگی‌ها

وابستگی قدیمی androidx.wear.compose:compose-navigation را بردارید و وابستگی‌های جدید Navigation 3 را به‌همراه پشتیبانی از سریال‌سازی Kotlin معرفی کنید.

برداشتن:

implementation("androidx.wear.compose:compose-navigation:...")

افزودن:

implementation("androidx.navigation3:navigation3-runtime:...") // State logic
implementation("androidx.navigation3:navigation3-ui:...")      // Display logic
implementation("androidx.wear.compose:compose-navigation3:...") // Wear gestures
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:...") // Requires compiler plugin

۲. به‌روزرسانی مقصدها برای پیاده‌سازی NavKey

در «ناوبری ۲»، ممکن است از رشته‌ها یا اشیای عمومی برای مسیریابی استفاده کرده باشید. در Navigation 3، باید رابط نشانه NavKey را پیاده‌سازی کنید و هر شیء صفحه را با @Serializable حاشیه‌نویسی کنید.

چرا این کار لازم است؟ بنابراین پشته برگشت می‌تواند ذخیره شود و درصورت مرگ پردازش بازیابی شود، navigation3-runtime زیرین برای سریال‌سازی وضعیت به kotlinx-serialization متکی است.

قبل‌از (پیمایش ۲ - مسیرهای امن نوع عمومی):

sealed class Nav2Screen {
    data object Landing : Nav2Screen()
    data object List : Nav2Screen()
}

پس‌از (پیمایش ۳ - NavKey + Serializable):

@Serializable
sealed interface MigrationScreen : NavKey {
    @Serializable
    data object Landing : MigrationScreen

    @Serializable
    data object List : MigrationScreen
}

۳. جایگزین کردن «منطق مسیریابی» (NavController به NavBackStack)

NavController را با NavBackStack مقداردهی اولیه شده بااستفاده از rememberNavBackStack جایگزین کنید. همچنین باید SwipeDismissableSceneStrategy را به‌طور ویژه برای Wear OS نمونه‌سازی کنید.

قبل‌از (پیمایش ۲):

val navController = rememberSwipeDismissableNavController()

بعداز (پیمایش ۳):

val backStack = rememberNavBackStack(MigrationScreen.Landing as NavKey)
val strategy = rememberSwipeDismissableSceneStrategy<NavKey>()

۴. جایگزین کردن NavHost با NavDisplay و entryProvider DSL

محتوی NavHost و سازنده داخلی composable("route") { ... } DSL آن با NavDisplay و entryProvider { entry<Key> { ... } } DSL جایگزین شده است.

قبل‌از (پیمایش ۲):

SwipeDismissableNavHost(navController = navController, startDestination = "menu") {
    composable("menu") {
        GreetingScreen(
            onShowList = { navController.navigate("list") }
        )
    }
    composable("list") {
        ListScreen()
    }
}

بعداز (پیمایش ۳):

NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryProvider = entryProvider {
        entry<MigrationScreen.Landing> {
            GreetingScreen(
                onShowList = { backStack.add(MigrationScreen.List) }
            )
        }
        entry<MigrationScreen.List> {
            ListScreen()
        }
    }
)