این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ناوبری 3

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

مفاهیم اصلی

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

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

وابستگی‌های مورد نیاز Navigation 3، Wear Compose و Serialization را به پروژه خود اضافه کنید.

گرووی

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

    // Wear OS specific Navigation 3 integration
    implementation "androidx.wear.compose:compose-navigation3:1.6.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.2.0-alpha02")
    implementation("androidx.navigation3:navigation3-ui:1.2.0-alpha02")

    // Wear OS specific Navigation 3 integration
    implementation("androidx.wear.compose:compose-navigation3:1.6.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
}Navigation.kt

مرحله ۳: تنظیم `NavDisplay` و back stack

در ریشه برنامه خود، back stack و استراتژی صحنه 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) }
            )
        }
    }
)Navigation.kt

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

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

مرحله 5: (اختیاری) انتقال ViewModelها به مقصدها

به طور پیش‌فرض، ViewModel ها به Activity محدود می‌شوند. Navigation 3 یک مصنوع خاص ( lifecycle-viewmodel-navigation3 ) را فراهم می‌کند تا به طور ایمن یک ViewModel را به یک NavEntry در back stack محدود کند. وقتی مقصد از back stack حذف می‌شود، ViewModel پاک می‌شود.

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

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

دکوراتور Store مربوط به ViewModel را به entryDecorators مربوط به NavDisplay خود اضافه کنید. همچنین هنگام ارائه دکوراتورهای سفارشی برای حفظ وضعیت 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()
        }
    }
)Navigation.kt

ناوبری 3 با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.