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

بازگشت پیش‌بینی‌کننده، یک ویژگی پیمایش اشاره‌ای، به کاربران امکان می‌دهد پیش‌نمایش جایی را که با کشیدن انگشت به عقب می‌کشد، مشاهده کنند.

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

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

شما می توانید این انیمیشن بازگشت به خانه را آزمایش کنید (همانطور که در بخش بعدی این صفحه توضیح داده شده است).

پشتیبانی از حرکت پیشگویانه برگشت مستلزم به‌روزرسانی برنامه شما، با استفاده از 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 استفاده می کند	نحوه عملکرد برنامه شما با ناوبری برگشتی	مسیر مهاجرت پیشنهادی (لینک در این صفحه)
بله	API های AndroidX	یک پیاده سازی پشتی AndroidX موجود را انتقال دهید
	APIهای پلتفرم پشتیبانی نشده	یک برنامه AndroidX حاوی APIهای ناوبری پشتیبان پشتیبانی نشده را به APIهای AndroidX منتقل کنید
خیر	API های پلت فرم پشتیبانی نشده، قادر به مهاجرت هستند	برنامه‌ای را که از APIهای ناوبری پشتیبان پشتیبانی نشده استفاده می‌کند به APIهای پلتفرم منتقل کنید
	API های پلتفرم پشتیبانی نمی شوند، اما نمی توانند منتقل شوند	تا زمانی که این یک ویژگی ضروری شود ، شرکت در آن را به تعویق بیندازید

پیاده‌سازی پیمایش عقب 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 به شما امکان می دهد انیمیشن های سیستمی پیش بینی را در سطح فعالیت انتخاب کنید. این رفتار انتقال برنامه‌های بزرگ چند فعالیتی را به حرکات پیش‌گویانه برگشت قابل کنترل‌تر می‌کند. با اندروید 15، بازگشت پیشگویانه دیگر پشت گزینه توسعه دهنده نیست. برنامه‌ها می‌توانند به طور کامل یا در سطح فعالیت پیش‌بینی کنند.

کد زیر نمونه ای از استفاده از 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 شوید. این بهترین سیگنال برای دانستن زمانی است که یک مقصد نوشتن از پشته خارج شده و از بین می رود.

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

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

اگر پاسخ تماس یک مسئولیت واحد داشته باشد، مدیریت وضعیت فعال یک تماس برگشتی آسانتر است. به عنوان مثال:

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

پاسخ تماس دیگر می تواند شامل یک مؤلفه مادی باشد که از برگشت پیش بینی کننده پشتیبانی می کند، یک انتقال AndroidX با استفاده از API های Progress یا یک تماس سفارشی دیگر.

اگر تماس‌های فوق غیرفعال باشند و پشته پشتی این FragmentManager خالی نباشد، پاسخ تماس childFragmentManager اجرا می‌شود، جایی که childFragmentManager درون یک Fragment متصل است. در این مثال، این تماس داخلی غیرفعال است.

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

در نهایت، super.onBackPressed() یک تماس در سطح سیستم است که در صورت غیرفعال شدن تماس های بالا دوباره اجرا می شود. برای فعال کردن انیمیشن‌های سیستمی مانند بازگشت به خانه، فعالیت متقابل، و کار متقابل، پشته پشتی supportFragmentManager باید خالی باشد تا تماس داخلی آن غیرفعال شود.

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

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

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

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

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

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