آرگومان‌های ایمن

روش توصیه‌شده برای پیمایش بین مقصدها استفاده از افزونه Safe Args Gradle است. این افزونه کلاس‌های سازنده و شیء تولید می‌کند که امکان پیمایش ایمن ازنظر نوع را بین مقصدها فراهم می‌کند. از «آرگومان‌های ایمن» برای پیمایش و انتقال داده بین مقصدها استفاده کنید.

توجه: اگر از Gradle استفاده نمی‌کنید، باید از روش‌های پیمایش دیگری استفاده کنید.

هشدار: «آرگومان‌های ایمن» فقط برای نماها و قطعه‌های Android دردسترس است. اگر از Compose استفاده می‌کنید، راهنمای پیمایش ایمن تایپی را ببینید.

فعال کردن «آرگومان‌های ایمن»

برای افزودن آرگومان‌های ایمن به پروژه خود، classpath زیر را در فایل build.gradle سطح بالای خود وارد کنید:

گرووی

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.10.2"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

کاتلین

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.10.2"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

همچنین باید یکی از دو افزونه موجود را اعمال کنید.

برای تولید کد زبان جاوا که برای ماژول‌های جاوا یا ترکیبی از جاوا و کاتلین مناسب باشد، این خط را به فایل build.gradle برنامه یا ماژول خود اضافه کنید:

گرووی

plugins {
  id 'androidx.navigation.safeargs'
}

کاتلین

plugins {
    id("androidx.navigation.safeargs")
}

روش دیگر، برای تولید کد کاتلین مناسب برای ماژول‌های فقط کاتلین، اضافه کردن:

گرووی

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

کاتلین

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

شما باید طبق دستور Migrating to AndroidX، در فایل gradle.properties خود، android.useAndroidX=true را داشته باشید.

کد تولیدشده

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

«آرگومان‌های ایمن» برای هر مقصدی که کنشی از آن شروع می‌شود، یک کلاس تولید می‌کند. نام کلاس تولیدشده «مسیرها» را به نام کلاس مقصد اصلی اضافه می‌کند. برای مثال، اگر نام مقصد مبدأ SpecifyAmountFragment باشد، نام کلاس تولیدشده SpecifyAmountFragmentDirections خواهد بود.

کلاس تولیدشده حاوی یک روش ایستا برای هر کنش تعریف‌شده در مقصد مبدأ است. این روش هر پارامتر کنش تعریف‌شده‌ای را به‌عنوان آرگومان می‌گیرد و شیء NavDirections را برمی‌گرداند که می‌توانید مستقیماً به navigate() ارسال کنید.

نمونه Safe Args

برای مثال، یک نمودار پیمایش را با یک کنش واحد درنظر بگیرید که دو مقصد SpecifyAmountFragment و ConfirmationFragment را به هم متصل می‌کند. ‫ConfirmationFragment یک پارامتر float تکی را که به‌عنوان بخشی از کنش ارائه می‌دهید می‌گیرد.

Safe Args یک کلاس SpecifyAmountFragmentDirections با یک متد واحد، actionSpecifyAmountFragmentToConfirmationFragment()، و یک کلاس داخلی به نام ActionSpecifyAmountFragmentToConfirmationFragment تولید می‌کند. کلاس داخلی از NavDirections مشتق شده است و شناسه کنش مرتبط و پارامتر float را ذخیره می‌کند. سپس شیء NavDirections برگردانده‌شده می‌تواند مستقیماً به navigate() منتقل شود، همان‌طور که در مثال زیر نشان داده شده است:

کاتلین

override fun onClick(v: View) {
    val amount: Float = ...
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount)
    v.findNavController().navigate(action)
}

جاوا

@Override
public void onClick(View view) {
    float amount = ...;
    action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment(amount);
    Navigation.findNavController(view).navigate(action);
}

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

بااستفاده از «آرگومان‌های ایمن»، ایمنی تایپی را تضمین کنید

بااستفاده از افزونه Safe Args Gradle، بین مقصدها پیمایش کنید. این افزونه کلاس‌های سازنده و شیء ساده‌ای تولید می‌کند که پیمایش ایمن ازنظر نوع و ارسال آرگومان بین مقصدها را ممکن می‌سازد.

توجه: برای روش‌های دیگر پیمایش، پیمایش به مقصد را ببینید.

برای افزودن آرگومان‌های ایمن به پروژه خود، classpath زیر را در فایل build.gradle سطح بالای خود وارد کنید:

گرووی

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.10.2"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

کاتلین

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.10.2"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

همچنین باید یکی از دو افزونه موجود را اعمال کنید.

برای تولید کد زبان جاوا که برای ماژول‌های جاوا یا ترکیبی از جاوا و کاتلین مناسب باشد، این خط را به فایل build.gradle برنامه یا ماژول خود اضافه کنید:

گرووی

plugins {
  id 'androidx.navigation.safeargs'
}

کاتلین

plugins {
    id("androidx.navigation.safeargs")
}

روش دیگر، برای تولید کد کاتلین مناسب برای ماژول‌های فقط کاتلین، اضافه کردن:

گرووی

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

کاتلین

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

شما باید طبق دستور Migrating to AndroidX، در فایل gradle.properties خود، android.useAndroidX=true را داشته باشید.

پس‌از فعال کردن «آرگومان‌های ایمن»، افزایه کدی تولید می‌کند که حاوی کلاس‌ها و روش‌هایی برای هر کنشی است که تعریف کرده‌اید. برای هر کنش، Safe Args همچنین کلاسی برای هر مقصد مبدأ تولید می‌کند که مقصدی است که کنش از آنجا آغاز می‌شود. نام کلاس تولیدشده ترکیبی از نام کلاس مقصد مبدأ و کلمه «Directions» است. برای مثال، اگر نام مقصد SpecifyAmountFragment باشد، نام کلاس تولیدشده SpecifyAmountFragmentDirections خواهد بود. کلاس تولیدشده حاوی یک روش ایستا برای هر کنش تعریف‌شده در مقصد مبدأ است. این روش هر پارامتر کنش تعریف‌شده‌ای را به‌عنوان آرگومان می‌گیرد و شیء NavDirections را برمی‌گرداند که می‌توانید به navigate() ارسال کنید.

به‌عنوان مثال، فرض کنید نمودار ناوبری با یک کنش داریم که مقصد مبدأ، SpecifyAmountFragment، را به مقصد گیرنده، ConfirmationFragment، متصل می‌کند.

‫Safe Args یک کلاس SpecifyAmountFragmentDirections با یک روش واحد، actionSpecifyAmountFragmentToConfirmationFragment()، تولید می‌کند که یک شیء NavDirections را برمی‌گرداند. سپس این شیء NavDirections برگردانده‌شده می‌تواند مستقیماً به navigate() منتقل شود، همان‌طور که در مثال زیر نشان داده شده است:

کاتلین

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

جاوا

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

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