‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

انتقال Jetpack Navigation به Navigation Compose

میانای برنامه‌سازی کاربردی Navigation Compose به شما امکان می‌دهد بین عناصر ترکیبی در برنامه Compose پیمایش کنید و درعین‌حال از مؤلفه، زیرساخت، و ویژگی‌های پیمایش Jetpack بهره‌مند شوید.

این صفحه نحوه انتقال از «پیمایش Jetpack» مبتنی بر «تکه» به Navigation Compose را به‌عنوان بخشی از انتقال بزرگ‌تر میانای کاربر مبتنی بر View به Jetpack Compose شرح می‌دهد.

پیش‌نیازهای انتقال

وقتی بتوانید همه «تکه‌کدهای» خود را با عناصر ترکیبی صفحه متناظر جایگزین کنید، می‌توانید به «ترکیب پیمایش» انتقال دهید. ترکیب‌های صفحه‌نمایش می‌توانند حاوی مخلوطی از محتوای Compose و View باشند، اما همه مقصد‌های پیمایش باید ترکیب‌پذیر باشند تا انتقال «پیمایش Compose» فعال شود. تا آن زمان، باید در پایگاه کد View و Compose هم‌کنش‌پذیر خود به استفاده از عنصر «پیمایش مبتنی بر بخش» ادامه دهید. برای اطلاعات بیشتر، مستندات تعامل‌پذیری ناوبری را ببینید.

مراحل انتقال

چه از استراتژی انتقال توصیه‌شده ما پیروی کنید یا رویکرد دیگری را اتخاذ کنید، به نقطه‌ای خواهید رسید که همه مقصدهای پیمایش، عناصر ترکیبی صفحه هستند و «تکه‌ها» فقط به‌عنوان محتوی‌های ترکیبی عمل می‌کنند. در این مرحله، می‌توانید به «نوشتن با پیمایش» انتقال دهید.

اگر برنامه شما ازقبل از الگوی طراحی UDF و راهنمای ما برای معماری پیروی می‌کند، انتقال به Jetpack Compose و Navigation Compose نباید به بازسازی‌های عمده لایه‌های دیگر برنامه شما، به‌جز لایه رابط کاربری، نیاز داشته باشد.

برای انتقال به «نوشتن با پیمایش»، این مراحل را دنبال کنید:

وابستگی Navigation Compose را به برنامه‌تان اضافه کنید.

یک عنصر ترکیبی App-level ایجاد کنید و آن را به‌عنوان نقطه ورود Compose به Activity اضافه کنید و جایگزین راه‌اندازی چیدمان View کنید:

class SampleActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
        setContent {
            SampleApp(/* ... */)
        }
    }
}MigrationCommonScenariosSnippets.kt

برای هر مقصد پیمایش، نوعی ایجاد کنید. از data object برای مقصد‌هایی که به داده نیاز ندارند و از data class یا class برای مقصد‌هایی که به داده نیاز دارند استفاده کنید.
```
@Serializable data object First
@Serializable data class Second(val id: String)
@Serializable data object Third
MigrationCommonScenariosSnippets.kt
```
NavController را در جایی راه‌اندازی کنید که همه عناصر ترکیبی که نیاز دارند به آن ارجاع دهند به آن دسترسی داشته باشند (این معمولاً داخل عنصر ترکیبی App شما است). این رویکرد از اصول بالابردن وضعیت پیروی می‌کند و به شما امکان می‌دهد از NavController به‌عنوان منبع اصلی اطلاعات برای پیمایش بین صفحه‌های ترکیب‌پذیر و حفظ پشته برگشت استفاده کنید:
```
@Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}MigrationCommonScenariosSnippets.kt
```

NavHost برنامه را در App عنصر ترکیبی ایجاد کنید و navController را ارسال کنید:

@Composable
fun SampleApp() {
    val navController = rememberNavController()

    SampleNavHost(navController = navController)
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        // ...
    }
}MigrationCommonScenariosSnippets.kt

مقصد composable را اضافه کنید تا نمودار ناوبری‌تان را بسازید. اگر هر صفحه قبلاً به Compose انتقال داده شده باشد، این مرحله فقط شامل استخراج این عناصر ترکیبی صفحه از «تکه‌های» شما به composable مقصد است:

class FirstFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            setContent {
                // FirstScreen(...) EXTRACT FROM HERE
            }
        }
    }
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(/* ... */) // EXTRACT TO HERE
        }
        composable<Second> {
            SecondScreen(/* ... */)
        }
        // ...
    }
}MigrationCommonScenariosSnippets.kt

اگر راهنمایی‌های مربوط به معماری کردن «میانای کاربر Compose» را دنبال کرده‌اید، به‌ویژه نحوه انتقال ViewModel و رویدادهای پیمایش به ترکیب‌پذیرها، مرحله بعدی تغییر نحوه ارائه ViewModel به هر ترکیب‌پذیر صفحه است. اغلب می‌توانید از تزریق Hilt و نقطه یکپارچه‌سازی آن با Compose و Navigation ازطریق hiltViewModel استفاده کنید:
```
@Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}MigrationCommonScenariosSnippets.kt
```

همه فراخوانی‌های پیمایش findNavController() را با فراخوانی‌های navController جایگزین کنید و این فراخوانی‌ها را به‌جای کل navController به‌عنوان رویدادهای پیمایش به هر صفحه ترکیب‌پذیر ارسال کنید. این رویکرد از روال‌های مطلوب برای نمایان کردن رویدادها از توابع ترکیبی به تماس‌گیرندگان پیروی می‌کند و navController را به‌عنوان منبع واحد حقیقت حفظ می‌کند.

با ایجاد نمونه‌ای از کلاس مسیر تعریف‌شده برای مقصد، می‌توان داده‌ها را به مقصد منتقل کرد. سپس می‌توان آن را یا مستقیماً از ورودی پشته برگشت در مقصد یا از ViewModel بااستفاده از SavedStateHandle.toRoute() دریافت کرد.

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate(Second(id = "ABC"))
                }
            )
        }
        composable<Second> { backStackEntry ->
            val secondRoute = backStackEntry.toRoute<Second>()
            SecondScreen(
                id = secondRoute.id,
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate(Third)
                }
            )
        }
        // ...
    }
}MigrationCommonScenariosSnippets.kt

همه «تکه‌کدها»، چیدمان‌های XML مربوطه، پیمایش غیرضروری، و منابع دیگر، و همچنین وابستگی‌های منسوخ‌شده «تکه‌کد» و «پیمایش Jetpack» را بردارید.

همین مراحل را با جزئیات بیشتر درباره «ترکیب پیمایش» می‌توانید در اسناد راه‌اندازی پیدا کنید.

موارد استفاده رایج

مهم نیست از کدام عنصر «پیمایش» استفاده می‌کنید، اصول یکسانی برای پیمایش اعمال می‌شود.

موارد استفاده رایج هنگام انتقال شامل موارد زیر است:

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

بازیابی داده‌های پیچیده هنگام ناوبری

به‌شدت توصیه می‌کنیم هنگام پیمایش، اشیای داده پیچیده را منتقل نکنید. درعوض، هنگام انجام کنش‌های پیمایش، حداقل اطلاعات لازم، مانند شناسه یکتا یا شکل دیگری از مدرک شناسایی، را به‌عنوان آرگومان ارسال کنید. باید اشیاء پیچیده را به‌عنوان داده در یک منبع واحد حقیقت، مثل لایه داده، ذخیره کنید. برای اطلاعات بیشتر، بازیابی داده‌های پیچیده هنگام ناوبری را ببینید.

اگر «تکه‌کدهای» شما اشیای پیچیده را به‌عنوان آرگومان ارسال می‌کنند، ابتدا کدتان را به‌گونه‌ای بازسازی کنید که امکان ذخیره و واکشی این اشیا از لایه داده را فراهم کند. برای نمونه، مجموعه اطلاعات Now in Android را ببینید.

محدودیت‌ها

این بخش محدودیت‌های فعلی «نوشتن با پیمایش» را شرح می‌دهد.

انتقال تدریجی به Navigation Compose

درحال‌حاضر، نمی‌توانید از «ترکیب پیمایش» درحالی‌که همچنان از «تکه‌کدها» به‌عنوان مقصد در کدتان استفاده می‌کنید استفاده کنید. برای شروع استفاده از «ترکیب ناوبری»، همه مقصدها باید ترکیب‌شدنی باشند. می‌توانید این درخواست ویژگی را در «پیگیری‌کننده مشکلات» پیگیری کنید.

پویانمایی‌های گذار

از Navigation 2.7.0-alpha01، پشتیبانی از تنظیم گذارهای سفارشی، که قبلاً از AnimatedNavHost بود، اکنون مستقیماً در NavHost پشتیبانی می‌شود. برای کسب اطلاعات بیشتر، یادداشت‌های انتشار را بخوانید.

بیشتر بدانید

برای اطلاعات بیشتر درباره انتقال به «پیمایش Compose»، منابع زیر را ببینید:

‫Codelab مربوط به Navigation Compose: با یک codelab عملی، با اصول اولیه Navigation Compose آشنا شوید.
اکنون در مخزن Android: برنامه Android کاملاً کاربردی که کاملاً با Kotlin و Jetpack Compose ساخته شده است، از شیوه‌های مطلوب طراحی و توسعه Android پیروی می‌کند و شامل Navigation Compose است.
انتقال Sunflower به Jetpack Compose: پست وبلاگی که سفر انتقال برنامه نمونه Sunflower از Views به Compose را مستند می‌کند، که شامل انتقال به Navigation Compose نیز می‌شود.
‫Jetnews برای هر صفحه‌نمایش: پست وبلاگی که بازسازی و انتقال نمونه Jetnews را برای پشتیبانی از همه صفحه‌نمایش‌ها با Jetpack Compose و Navigation Compose مستند می‌کند.

توصیه‌شده برای شما

توجه: نوشتار پیوند وقتی جاوا اسکریپت خاموش است نمایش داده می‌شود
پیمایش با «نوشتن»
Compose و کتابخانه‌های دیگر
ملاحظات دیگر