ناوبری ۳

«پیمایش ۳» کتابخانه پیمایشی است که از ابتدا برای Jetpack Compose طراحی شده است. این راهنما نحوه پیاده‌سازی «ناوبری ۳» در برنامه‌های Wear OS را توضیح می‌دهد.

مفاهیم اصلی

  • NavKey: شناسه نوع‌امن و سریال‌شدنی برای مقصد (صفحه) در برنامه شما.
  • NavBackStack: فهرست تغییرپذیر نمونه‌های NavKey که نشان‌دهنده سابقه پیمایش است. مستقیماً از این فهرست، موارد را اضافه و حذف می‌کنید.
  • rememberNavBackStack: عنصر ترکیبی که پشته برگشت را درطول تغییرات پیکربندی و مرگ فرایند ایجاد و حفظ می‌کند.
  • NavDisplay: عنصر اصلی میانای کاربر که پشته پشتی را مشاهده می‌کند و صفحه فعال را ارائه می‌کند.
  • EntryProvider: یک زبان مدل‌سازی دامنه که NavKey را به میانای کاربر @Composable واقعی آن پیوند می‌دهد.
  • SwipeDismissableSceneStrategy: استراتژی ویژه Wear که صفحه‌های شما را در ژست تند کشیدن برای بستن می‌پیچد و پویانمایی‌های درون‌ساخت برگشت را مدیریت می‌کند.

مرحله ۱: افزودن وابستگی‌ها

وابستگی‌های موردنیاز «پیمایش ۳»، «Wear Compose»، و «سریال‌سازی» را به پروژه‌تان اضافه کنید.

شیک

dependencies {
    // Core Navigation 3 APIs
    implementation "androidx.navigation3:navigation3-runtime:1.3.0-alpha02"
    implementation "androidx.navigation3:navigation3-ui:1.3.0-alpha02"

    // Wear OS specific Navigation 3 integration
    implementation "androidx.wear.compose:compose-navigation3:1.7.1"

    // Kotlinx Serialization for type-safe routing
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0"
}

کاتلین

dependencies {
    // Core Navigation 3 APIs
    implementation("androidx.navigation3:navigation3-runtime:1.3.0-alpha02")
    implementation("androidx.navigation3:navigation3-ui:1.3.0-alpha02")

    // Wear OS specific Navigation 3 integration
    implementation("androidx.wear.compose:compose-navigation3:1.7.1")

    // Kotlinx Serialization for type-safe routing
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
}

مرحله ۲: تعریف مقصدها (NavKey)

صفحه‌ها به‌عنوان اشیای قابل‌سریال‌سازی یا کلاس‌های داده‌ای با نوع قوی تعریف می‌شوند که واسط NavKey را پیاده‌سازی می‌کنند.

@Serializable
sealed interface Screen : NavKey {
    @Serializable
    data object Home : Screen

    @Serializable
    data class Details(val itemId: String) : Screen
}

مرحله ۳: راه‌اندازی NavDisplay و پشته برگشت

در ریشه برنامه‌تان، پشته برگشت و استراتژی صحنه Wear OS را مقداردهی اولیه کنید، سپس آن‌ها را به NavDisplay متصل کنید.

// 1. Create the persistent back stack starting at the Home screen
val backStack = rememberNavBackStack(Screen.Home)

// 2. Initialize the Wear OS swipe-to-dismiss strategy
val strategy = rememberSwipeDismissableSceneStrategy<NavKey>()

// 3. Render the NavDisplay
NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryProvider = entryProvider {
        // 4. Map keys to Composables
        entry<Screen.Home> {
            HomeScreen(
                onNavigateToDetails = { id -> backStack.add(Screen.Details(id)) }
            )
        }
        entry<Screen.Details> { key ->
            DetailsScreen(
                itemId = key.itemId,
                onBack = { backStack.removeAt(backStack.lastIndex) }
            )
        }
    }
)

مرحله ۴: انجام کنش‌های ناوبری

چون پشته برگشت فقط یک MutableList سفارشی‌سازی‌شده است، پیمایش به‌طرز باورنکردنی ساده است. عملیات را مستقیماً روی نمونه backStack انجام می‌دهید:

  • پیمایش به جلو: backStack.add(Screen.Details("123"))
  • پیمایش به عقب: backStack.removeLast() یا backStack.removeLastOrNull()
  • پاک کردن و بازنشانی: backStack.clear(); backStack.add(Screen.Home) (یا از عملکردهای فهرست برای جایگزین کردن پشته استفاده کنید).

مرحله ۵: (اختیاری) محدود کردن ViewModels به مقصدها

به‌طور پیش‌فرض، ViewModelها به Activity محدود می‌شوند. «پیمایش ۳» یک آرتیفکت خاص (lifecycle-viewmodel-navigation3) ارائه می‌دهد تا ViewModel را به‌طور ایمن به NavEntry در پشته پشتی محدود کند. وقتی مقصد از پشته برگشت برداشته می‌شود، ViewModel پاک می‌شود.

  1. وابستگی را اضافه کنید:

    implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:...")

  2. تزئین‌کننده فروشگاه ViewModel را به NavDisplay entryDecorators اضافه کنید. همچنین هنگام ارائه تزئین‌کننده‌های سفارشی برای حفظ وضعیت Compose rememberSaveable، باید به‌طور صریح SaveableStateHolderNavEntryDecorator را اضافه کنید:

    NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberViewModelStoreNavEntryDecorator()
    ),
    entryProvider = entryProvider {
        entry<Screen.Home> {
            // Any viewModel() requested here will be scoped to this NavEntry
            val viewModel: HomeViewModel = viewModel()
        }
    }
)