Jetpack Navigation را به Navigation Compose منتقل کنید

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

این صفحه نحوه مهاجرت از یک Jetpack Navigation مبتنی بر Fragment به Navigation Compose را به عنوان بخشی از انتقال UI بزرگتر مبتنی بر View به Jetpack Compose توضیح می دهد.

پیش نیازهای مهاجرت

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

استفاده از Navigation Compose در یک برنامه فقط نوشتن پیش نیاز نیست. تا زمانی که Fragments را برای میزبانی محتوای قابل ترکیب خود نگه دارید، می توانید به استفاده از مولفه ناوبری مبتنی بر قطعه ادامه دهید .

مراحل مهاجرت

چه از استراتژی مهاجرت توصیه‌شده ما پیروی کنید یا از رویکرد دیگری استفاده کنید، به نقطه‌ای خواهید رسید که همه مقاصد پیمایش قابل تنظیم روی صفحه هستند و Fragments فقط به عنوان کانتینرهای قابل ترکیب عمل می‌کنند. در این مرحله می توانید به Navigation Compose مهاجرت کنید.

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

برای انتقال به Navigation Compose، این مراحل را دنبال کنید:

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

  2. یک Composable 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

  3. NavController در مکانی راه اندازی کنید که همه اجزای سازنده که نیاز به ارجاع به آن دارند به آن دسترسی داشته باشند (این معمولاً در داخل App قابل تنظیم است). این رویکرد از اصول بالا بردن حالت پیروی می کند و به شما امکان می دهد از NavController به عنوان منبع حقیقت برای پیمایش بین صفحه های قابل ترکیب و حفظ پشته استفاده کنید:

    @Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}
    MigrationCommonScenariosSnippets.kt

  4. NavHost برنامه خود را در App composable ایجاد کنید و navController ارسال کنید:

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

    SampleNavHost(navController = navController)
}

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

  5. برای ساختن نمودار ناوبری، مقصدهای composable را اضافه کنید. اگر هر صفحه قبلاً به Compose منتقل شده است، این مرحله فقط شامل استخراج این صفحه‌های قابل ترکیب از Fragments شما به مقصدهای 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

  6. اگر دستورالعمل‌های معماری Compose UI را دنبال کرده‌اید، به‌ویژه اینکه چگونه ViewModel و رویدادهای ناوبری باید به composable‌ها منتقل شوند، گام بعدی این است که نحوه ارائه ViewModel برای هر صفحه نمایش‌پذیر تغییر دهید. اغلب می توانید از تزریق Hilt و نقطه ادغام آن با Compose و Navigation از طریق hiltViewModel استفاده کنید:

    @Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}
    MigrationCommonScenariosSnippets.kt

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

    1. اگر قبلاً از افزونه Safe Args برای ایجاد جهت‌ها و اقدامات ناوبری استفاده کرده‌اید، آن را با یک مسیر جایگزین کنید - یک مسیر رشته‌ای به دستگاه composable خود که برای هر مقصد منحصربه‌فرد است.
    2. برای جایگزینی Safe Args هنگام ارسال داده، به پیمایش با آرگومان ها مراجعه کنید.

    3. برای ایمنی نوع در Navigation Compose، بخش Safe Args زیر را بخوانید.

      @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = "first") {
        composable("first") {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate("second_screen_route")
                }
            )
        }
        composable("second") {
            SecondScreen(
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate("third_screen_route")
                }
            )
        }
        // ...
    }
}
      MigrationCommonScenariosSnippets.kt

  8. تمام قطعات، طرح‌بندی‌های XML مرتبط، ناوبری غیر ضروری و سایر منابع، و وابستگی‌های قدیمی Fragment و Jetpack Navigation را حذف کنید.

می‌توانید همین مراحل را با جزئیات بیشتر مربوط به نوشتن مسیریابی در مستندات راه‌اندازی بیابید.

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

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

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

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

ارگ ایمن

برخلاف Jetpack Navigation، Navigation Compose از استفاده از افزونه Safe Args برای تولید کد پشتیبانی نمی‌کند. درعوض، می‌توانید با استفاده از Navigation Compose از طریق ساختاردهی کد خود به ایمنی نوع آن در زمان اجرا دست یابید.

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

Navigation Compose مبتنی بر مسیر رشته است و برخلاف Jetpack Navigation، از ارسال Parcelables و Serializable های سفارشی به عنوان آرگومان پشتیبانی نمی کند .

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

اگر Fragments شما اشیاء پیچیده را به عنوان آرگومان ارسال می کند، ابتدا کد خود را مجدداً فاکتور کنید، به گونه ای که امکان ذخیره و واکشی این اشیاء را از لایه داده فراهم کند. برای مثال به مخزن Now in Android مراجعه کنید.

محدودیت ها

این بخش محدودیت‌های کنونی برای نوشتن مسیریابی را توضیح می‌دهد.

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

در حال حاضر، در حالی که هنوز از Fragments به عنوان مقصد در کد خود استفاده می کنید، نمی توانید از Navigation Compose استفاده کنید. برای شروع استفاده از Navigation Compose، همه مقصدهای شما باید قابل نوشتن باشند. می توانید این درخواست ویژگی را در ردیاب مشکل ردیابی کنید.

انیمیشن های انتقالی

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

بیشتر بدانید

برای اطلاعات بیشتر در مورد انتقال به Navigation Compose، به منابع زیر مراجعه کنید:

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