برای ژست برگشتی پیش بینی کننده پشتیبانی اضافه کنید

Android 14 (سطح API 34) برای ایجاد انیمیشن های سفارشی از انیمیشن های سیستمی و API های اضافی پشتیبانی می کند. برای اطلاعات بیشتر، به افزودن پشتیبانی برای انیمیشن‌های پشتی پیش‌بینی داخلی و سفارشی مراجعه کنید.

برای مثال، با استفاده از ژست برگشتی می‌توانید پیش‌نمایش متحرکی از صفحه اصلی را در پشت برنامه‌تان نمایش دهید، همانطور که در ماکت در شکل 1 ارائه شده است. با شروع Android 13، می‌توانید این انیمیشن بازگشت به خانه را با فعال کردن یک گزینه توسعه‌دهنده آزمایش کنید ( همانطور که در این صفحه توضیح داده شده است).

پشتیبانی از حرکت پیشگویانه برگشت مستلزم به‌روزرسانی برنامه شما، با استفاده از API سازگار با عقب OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) یا بالاتر، یا استفاده از API پلتفرم OnBackInvokedCallback جدید است. اکثر برنامه ها از API سازگار با AndroidX استفاده می کنند.

این به‌روزرسانی یک مسیر انتقال را برای رهگیری صحیح ناوبری برگشتی ارائه می‌کند، که شامل جایگزینی رهگیری‌های برگشتی از KeyEvent.KEYCODE_BACK و هر کلاسی با روش‌های onBackPressed مانند Activity و Dialog با APIهای بازگشت سیستم جدید است.

Codelab و ویدیوی Google I/O

علاوه بر استفاده از این مستندات در این صفحه، کدهای ما را امتحان کنید . این یک پیاده‌سازی مورد استفاده معمول از WebView را ارائه می‌کند که با استفاده از APIهای AndroidX Activity ژست پیش‌بینی‌کننده برگشت را مدیریت می‌کند.

همچنین می‌توانید ویدیوی Google I/O ما را مشاهده کنید، که نمونه‌های دیگری از پیاده‌سازی AndroidX و APIهای پلتفرم را پوشش می‌دهد.

برنامه‌ای را که از پیمایش پیش‌فرض پشتیبان استفاده می‌کند، به‌روزرسانی کنید

به‌روزرسانی برنامه‌تان برای پشتیبانی از این ویژگی ساده است، اگر برنامه‌تان هیچ رفتار پشتیبان سفارشی را اجرا نکند (به عبارت دیگر، مدیریت را به سیستم واگذار می‌کند). همانطور که در این راهنما توضیح داده شده است ، از این ویژگی استفاده کنید .

اگر برنامه شما از Fragments یا Navigation Component استفاده می کند، به AndroidX Activity 1.6.0-alpha05 یا بالاتر نیز ارتقا دهید.

برنامه ای را به روز کنید که از پیمایش برگشت سفارشی استفاده می کند

اگر برنامه شما رفتار برگشت سفارشی را پیاده سازی می کند، بسته به اینکه آیا از AndroidX استفاده می کند و چگونه ناوبری برگشتی را انجام می دهد، مسیرهای مهاجرت متفاوتی وجود دارد.

پیاده‌سازی پیمایش عقب AndroidX را مهاجرت کنید

این مورد استفاده رایج ترین (و توصیه شده ترین) است. این برنامه برای برنامه‌های جدید یا موجود که مدیریت ناوبری ژست‌های سفارشی را با OnBackPressedDispatcher اجرا می‌کنند، همانطور که در ارائه پیمایش برگشت سفارشی توضیح داده شده است، اعمال می‌شود.

اگر برنامه شما در این دسته قرار می‌گیرد، این مراحل را برای افزودن پشتیبانی از حرکت پیش‌بینی کننده برگشت دنبال کنید:

1. برای اطمینان از اینکه APIهایی که قبلاً از OnBackPressedDispatcher API استفاده می‌کنند (مانند Fragments و Navigation Component) یکپارچه با حرکت پیش‌بینی برگشت کار می‌کنند، به AndroidX Activity 1.6.0-alpha05 ارتقا دهید.

   // In your build.gradle file:
   dependencies {
   
   // Add this in addition to your other dependencies
   implementation "androidx.activity:activity:1.6.0-alpha05"
   

2. همانطور که در این صفحه توضیح داده شده است، ژست بازگشت پیشگویانه را انتخاب کنید .

یک برنامه AndroidX حاوی APIهای ناوبری پشتیبان پشتیبانی نشده را به APIهای AndroidX منتقل کنید

اگر برنامه شما از کتابخانه‌های AndroidX استفاده می‌کند اما APIهای ناوبری پشتیبان پشتیبانی‌نشده را پیاده‌سازی می‌کند یا به آنها اشاره می‌کند، باید برای پشتیبانی از رفتار جدید به استفاده از APIهای AndroidX بروید.

برای انتقال API های پشتیبانی نشده به API های AndroidX:

1. سیستم خود را با اجرای OnBackPressedCallback به OnBackPressedDispatcher AndroidX منتقل کنید. برای راهنمایی دقیق، به ارائه پیمایش برگشت سفارشی مراجعه کنید.

2. هنگامی که آماده توقف رهگیری حرکت برگشت هستید، OnBackPressedCallback را غیرفعال کنید.

3. رهگیری رویدادهای برگشتی را از طریق OnBackPressed یا KeyEvent.KEYCODE_BACK متوقف کنید.

4. حتماً به AndroidX Activity 1.6.0-alpha05 ارتقا دهید.

   // In your build.gradle file:
   dependencies {
   
   // Add this in addition to your other dependencies
   implementation "androidx.activity:activity:1.6.0-alpha05"
   

5. هنگامی که برنامه خود را با موفقیت انتقال دادید، برای مشاهده انیمیشن سیستم بازگشت به خانه ، ژست بازگشت پیشگویانه (همانطور که در این صفحه توضیح داده شده است) را انتخاب کنید .

برنامه‌ای را که از APIهای ناوبری پشتیبان پشتیبانی نشده استفاده می‌کند به APIهای پلتفرم منتقل کنید

اگر برنامه شما نمی‌تواند از کتابخانه‌های AndroidX استفاده کند و در عوض با استفاده از APIهای پشتیبانی‌نشده، پیمایش برگشت سفارشی را پیاده‌سازی کرده یا به آن ارجاع می‌دهد، باید به API پلتفرم OnBackInvokedCallback مهاجرت کنید.

مراحل زیر را برای انتقال APIهای پشتیبانی نشده به API پلتفرم انجام دهید:

1. از OnBackInvokedCallback API جدید در دستگاه‌های دارای Android نسخه 13 یا بالاتر استفاده کنید و در دستگاه‌های دارای Android 12 یا پایین‌تر به API‌های پشتیبانی‌نشده تکیه کنید.

2. منطق برگشت سفارشی خود را در OnBackInvokedCallback با onBackInvokedDispatcher ثبت کنید. این کار از اتمام فعالیت فعلی جلوگیری می‌کند، و پس از تکمیل ناوبری برگشت سیستم توسط کاربر، فرصتی برای واکنش به عمل برگشت به شما داده می‌شود.

3. هنگامی که آماده توقف رهگیری حرکت برگشت هستید، ثبت نام OnBackInvokedCallback را لغو کنید. در غیر این صورت، کاربران ممکن است رفتار نامطلوبی را هنگام استفاده از پیمایش برگشتی سیستم مشاهده کنند - به عنوان مثال، "گیر کردن" بین نماها و مجبور کردن آنها به خروج اجباری از برنامه شما.

   در اینجا مثالی از نحوه انتقال منطق به خارج از onBackPressed آورده شده است:

   کاتلین

   @Override
   fun onCreate() {
       if (BuildCompat.isAtLeastT()) {
           onBackInvokedDispatcher.registerOnBackInvokedCallback(
               OnBackInvokedDispatcher.PRIORITY_DEFAULT
           ) {
               /**
                * onBackPressed logic goes here. For instance:
                * Prevents closing the app to go home screen when in the
                * middle of entering data to a form
                * or from accidentally leaving a fragment with a WebView in it
                *
                * Unregistering the callback to stop intercepting the back gesture:
                * When the user transitions to the topmost screen (activity, fragment)
                * in the BackStack, unregister the callback by using
                * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
                * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
                */
           }
       }
   }

   جاوا

   @Override
   void onCreate() {
     if (BuildCompat.isAtLeastT()) {
       getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
           OnBackInvokedDispatcher.PRIORITY_DEFAULT,
           () -> {
             /**
              * onBackPressed logic goes here - For instance:
              * Prevents closing the app to go home screen when in the
              * middle of entering data to a form
              * or from accidentally leaving a fragment with a WebView in it
              *
              * Unregistering the callback to stop intercepting the back gesture:
              * When the user transitions to the topmost screen (activity, fragment)
              * in the BackStack, unregister the callback by using
              * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
              * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
              */
           }
       );
     }
   }

4. رهگیری رویدادهای برگشتی را از طریق OnBackPressed یا KeyEvent.KEYCODE_BACK برای Android نسخه 13 و بالاتر متوقف کنید.

5. هنگامی که برنامه خود را با موفقیت انتقال دادید، ژست بازگشت پیش بینی کننده (همانطور که در این صفحه توضیح داده شده است) را انتخاب کنید تا OnBackInvokedCallback اعمال شود.

می‌توانید یک OnBackInvokedCallback با PRIORITY_DEFAULT یا PRIORITY_OVERLAY ثبت کنید، که در AndroidX مشابه OnBackPressedCallback موجود نیست. ثبت پاسخ تماس با PRIORITY_OVERLAY در برخی موارد مفید است. موردی که می‌تواند اعمال شود، زمانی است که شما از onKeyPreIme() مهاجرت می‌کنید و پاسخ تماس شما باید به جای یک IME باز، ژست برگشت را دریافت کند. IME پس از باز شدن، تماس‌های برگشتی را با PRIORITY_DEFAULT ثبت می‌کند. پاسخ تماس خود را با PRIORITY_OVERLAY ثبت کنید تا مطمئن شوید که OnBackInvokedDispatcher حرکت برگشت را به جای IME باز به پاسخ تماس شما ارسال می کند.

ژست برگشتی پیش‌بینی‌کننده را انتخاب کنید

هنگامی که نحوه به روز رسانی برنامه خود را بر اساس مورد خود تعیین کردید، از ژست برگشتی پیش بینی کننده پشتیبانی کنید.

برای شرکت کردن، در AndroidManifest.xml ، در تگ <application> ، پرچم android:enableOnBackInvokedCallback روی true تنظیم کنید.

<application
    ...
    android:enableOnBackInvokedCallback="true"
    ... >
...
</application>

اگر مقداری را ارائه نکنید، به طور پیش‌فرض روی false قرار می‌گیرد و کارهای زیر را انجام می‌دهد:

• پویانمایی سیستم ژست‌های برگشتی پیش‌بینی‌کننده را غیرفعال می‌کند.
• OnBackInvokedCallback نادیده می گیرد، اما تماس های OnBackPressedCallback همچنان به کار خود ادامه می دهند.

در سطح فعالیت شرکت کنید

با شروع Android 14، پرچم android:enableOnBackInvokedCallback به شما امکان می دهد انیمیشن های سیستمی پیش بینی را در سطح فعالیت انتخاب کنید. این رفتار انتقال برنامه‌های بزرگ چند فعالیتی را به حرکات پیش‌گویانه برگشت قابل کنترل‌تر می‌کند.

کد زیر نمونه ای از استفاده از enableOnBackInvokedCallback برای فعال کردن انیمیشن سیستم بازگشت به خانه از MainActivity را نشان می دهد:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

در مثال قبل، تنظیم android:enableOnBackInvokedCallback=true برای ".SecondActivity" انیمیشن سیستم متقابل را فعال می کند.

هنگام استفاده از پرچم android:enableOnBackInvokedCallback ، ملاحظات زیر را در نظر داشته باشید:

• تنظیم android:enableOnBackInvokedCallback=false انیمیشن‌های پیش‌بینی‌کننده برگشت را در سطح فعالیت یا در سطح برنامه، بسته به محل تنظیم برچسب، خاموش می‌کند و به سیستم دستور می‌دهد تا تماس‌های API پلتفرم OnBackInvokedCallback را نادیده بگیرد. با این حال، تماس‌های مربوط به OnBackPressedCallback همچنان اجرا می‌شوند، زیرا OnBackPressedCallback با نسخه‌های قبلی سازگار است و onBackPressed API را که قبل از Android 13 پشتیبانی نمی‌شد، فراخوانی می‌کند.
• تنظیم پرچم enableOnBackInvokedCallback در سطح برنامه، مقدار پیش‌فرض را برای همه فعالیت‌های برنامه تعیین می‌کند. همانطور که در مثال کد قبلی نشان داده شده است، می توانید با تنظیم پرچم در سطح فعالیت، پیش فرض را برای هر فعالیت لغو کنید.

بهترین شیوه های پاسخ به تماس

در اینجا بهترین روش‌ها برای استفاده از سیستم پشتیبانی‌شده برگشت به تماس وجود دارد. BackHandler (برای نوشتن)، OnBackPressedCallback ، یا OnBackInvokedCallback .

وضعیت رابط کاربری را تعیین کنید که هر پاسخ تماس را فعال و غیرفعال می کند

حالت رابط کاربری خصوصیتی است که UI را توصیف می کند. توصیه می کنیم این مراحل سطح بالا را دنبال کنید.

1. وضعیت رابط کاربری را تعیین کنید که هر پاسخ تماس را فعال و غیرفعال می کند.

2. آن حالت را با استفاده از یک نوع دارنده داده قابل مشاهده ، مانند StateFlow یا Compose State تعریف کنید، و با تغییر وضعیت، پاسخ تماس را فعال یا غیرفعال کنید.

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

از تماس های برگشتی سیستم برای UI Logic استفاده کنید

منطق UI نحوه نمایش UI را دیکته می کند. برای اجرای منطق UI، مانند نمایش یک پنجره بازشو یا اجرای یک انیمیشن، از تماس های برگشتی سیستم استفاده کنید.

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

به عنوان مثال، اگر رویدادهای پشتیبان را فقط برای ورود به سیستم رهگیری می کنید، به جای آن وارد چرخه حیات Activity یا Fragment شوید.

• برای موارد فعالیت به فعالیت یا موارد قطعه به فعالیت، اگر isFinishing در onDestroy در چرخه حیات Activity true است، وارد شوید.
• برای موارد قطعه به قطعه، اگر isRemoving در onDestroy در چرخه عمر نمای Fragment صادق است، وارد شوید. یا با استفاده از روش‌های onBackStackChangeStarted یا onBackStackChangeCommitted در FragmentManager.OnBackStackChangedListener وارد شوید.

برای مورد Compose، وارد فراخوانی onCleared() یک ViewModel مرتبط با مقصد Compose شوید. این بهترین سیگنال برای دانستن زمانی است که یک مقصد نوشتن از پشته پشته خارج شده و از بین رفته است.

ایجاد پاسخ تماس با مسئولیت واحد

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

انیمیشن ژست‌های برگشتی پیش‌بینی‌کننده را آزمایش کنید

با شروع نسخه نهایی اندروید 13، باید بتوانید یک گزینه توسعه دهنده را برای آزمایش انیمیشن بازگشت به خانه نشان داده شده در شکل 1 فعال کنید.

برای تست این انیمیشن مراحل زیر را انجام دهید:

1. در دستگاه خود، به تنظیمات > سیستم > گزینه‌های برنامه‌نویس بروید.

2. انیمیشن‌های برگشتی پیش‌بینی‌کننده را انتخاب کنید.

3. برنامه به‌روزرسانی‌شده‌تان را راه‌اندازی کنید و از ژست برگشتی برای مشاهده آن در عمل استفاده کنید.