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 استفاده می کند | نحوه مدیریت برنامه شما با ناوبری برگشتی | مسیر مهاجرت پیشنهادی (لینک در این صفحه) |
بله | API های AndroidX | یک پیاده سازی پشتی AndroidX موجود را انتقال دهید |
APIهای پلتفرم پشتیبانی نشده | یک برنامه AndroidX حاوی APIهای ناوبری پشتیبان پشتیبانی نشده را به APIهای AndroidX منتقل کنید | |
خیر | API های پلت فرم پشتیبانی نشده، قادر به مهاجرت هستند | برنامهای را که از APIهای ناوبری پشتیبان پشتیبانی نشده استفاده میکند به APIهای پلتفرم منتقل کنید |
API های پلتفرم پشتیبانی نمی شوند، اما نمی توانند منتقل شوند | تا زمانی که این یک ویژگی ضروری شود ، شرکت در آن را به تعویق بیندازید |
پیادهسازی پیمایش عقب AndroidX را مهاجرت کنید
این مورد استفاده رایج ترین (و توصیه شده ترین) است. این برنامه برای برنامههای جدید یا موجود که مدیریت ناوبری ژستهای سفارشی را با OnBackPressedDispatcher
اجرا میکنند، همانطور که در ارائه پیمایش برگشت سفارشی توضیح داده شده است، اعمال میشود.
اگر برنامه شما در این دسته قرار میگیرد، این مراحل را برای افزودن پشتیبانی از حرکت پیشبینی کننده برگشت دنبال کنید:
برای اطمینان از اینکه 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"
همانطور که در این صفحه توضیح داده شده است، ژست بازگشت پیشگویانه را انتخاب کنید .
یک برنامه AndroidX حاوی APIهای ناوبری پشتیبان پشتیبانی نشده را به APIهای AndroidX منتقل کنید
اگر برنامه شما از کتابخانههای AndroidX استفاده میکند اما APIهای ناوبری پشتیبان پشتیبانینشده را پیادهسازی میکند یا به آنها اشاره میکند، باید برای پشتیبانی از رفتار جدید به استفاده از APIهای AndroidX بروید.
برای انتقال API های پشتیبانی نشده به API های AndroidX:
سیستم خود را با اجرای
OnBackPressedCallback
بهOnBackPressedDispatcher
AndroidX منتقل کنید. برای راهنمایی دقیق، به ارائه پیمایش برگشت سفارشی مراجعه کنید.هنگامی که آماده توقف رهگیری حرکت برگشت هستید،
OnBackPressedCallback
را غیرفعال کنید.رهگیری رویدادهای برگشتی را از طریق
OnBackPressed
یاKeyEvent.KEYCODE_BACK
متوقف کنید.حتماً به 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"
هنگامی که برنامه خود را با موفقیت انتقال دادید، برای مشاهده انیمیشن سیستم بازگشت به خانه ، ژست بازگشت پیشگویانه (همانطور که در این صفحه توضیح داده شده است) را انتخاب کنید .
برنامهای را که از APIهای ناوبری پشتیبان پشتیبانی نشده استفاده میکند به APIهای پلتفرم منتقل کنید
اگر برنامه شما نمیتواند از کتابخانههای AndroidX استفاده کند و در عوض با استفاده از APIهای پشتیبانینشده، پیمایش برگشت سفارشی را پیادهسازی کرده یا به آن ارجاع میدهد، باید به API پلتفرم OnBackInvokedCallback
مهاجرت کنید.
مراحل زیر را برای انتقال APIهای پشتیبانی نشده به API پلتفرم انجام دهید:
از
OnBackInvokedCallback
API جدید در دستگاههای دارای Android نسخه 13 یا بالاتر استفاده کنید و در دستگاههای دارای Android 12 یا پایینتر به APIهای پشتیبانینشده تکیه کنید.منطق برگشت سفارشی خود را در
OnBackInvokedCallback
باonBackInvokedDispatcher
ثبت کنید. این کار از اتمام فعالیت فعلی جلوگیری میکند، و پس از تکمیل ناوبری برگشت سیستم توسط کاربر، فرصتی برای واکنش به عمل برگشت به شما داده میشود.هنگامی که آماده توقف رهگیری حرکت برگشت هستید، ثبت نام
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) */ } ); } }
رهگیری رویدادهای برگشتی را از طریق
OnBackPressed
یاKeyEvent.KEYCODE_BACK
برای Android نسخه 13 و بالاتر متوقف کنید.هنگامی که برنامه خود را با موفقیت انتقال دادید، ژست بازگشت پیش بینی کننده (همانطور که در این صفحه توضیح داده شده است) را انتخاب کنید تا
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 را توصیف می کند. توصیه می کنیم این مراحل سطح بالا را دنبال کنید.
وضعیت رابط کاربری را تعیین کنید که هر پاسخ تماس را فعال و غیرفعال می کند.
آن حالت را با استفاده از یک نوع دارنده داده قابل مشاهده ، مانند
StateFlow
یا Compose State تعریف کنید، و با تغییر وضعیت، پاسخ تماس را فعال یا غیرفعال کنید.
اگر برنامه شما قبلاً منطق برگشت را با عبارات شرطی مرتبط میکرد، این ممکن است به این معنی باشد که شما به رویداد برگشتی پس از وقوع واکنش نشان میدهید - الگویی که باید با تماسهای جدیدتر اجتناب کنید. در صورت امکان، پاسخ تماس را به خارج از عبارت شرطی منتقل کنید و به جای آن، پاسخ تماس را به یک نوع دارنده داده قابل مشاهده مرتبط کنید.
از تماس های برگشتی سیستم برای UI Logic استفاده کنید
منطق UI نحوه نمایش UI را دیکته می کند. برای اجرای منطق UI، مانند نمایش یک پنجره بازشو یا اجرای یک انیمیشن، از تماس های برگشتی سیستم استفاده کنید.
اگر برنامه شما پاسخ تماس سیستمی را فعال میکند، انیمیشنهای پیشبینیکننده اجرا نمیشوند و باید رویداد برگشت را مدیریت کنید. فقط برای اجرای منطق غیر UI، فراخوان ایجاد نکنید.
به عنوان مثال، اگر رویدادهای پشتیبان را فقط برای ورود به سیستم رهگیری می کنید، به جای آن وارد چرخه حیات Activity یا Fragment شوید.
- برای موارد فعالیت به فعالیت یا موارد قطعه به فعالیت، اگر
isFinishing
درonDestroy
در چرخه حیات Activitytrue
است، وارد شوید. - برای موارد قطعه به قطعه، اگر
isRemoving
درonDestroy
در چرخه عمر نمای Fragment صادق است، وارد شوید. یا با استفاده از روشهایonBackStackChangeStarted
یاonBackStackChangeCommitted
درFragmentManager.OnBackStackChangedListener
وارد شوید.
برای مورد Compose، وارد فراخوانی onCleared()
یک ViewModel
مرتبط با مقصد Compose شوید. این بهترین سیگنال برای دانستن زمانی است که یک مقصد نوشتن از پشته پشته خارج شده و از بین رفته است.
ایجاد پاسخ تماس با مسئولیت واحد
این امکان پذیر است زیرا می توانید چندین تماس را به دیسپچر اضافه کنید. تماسهای برگشتی به پشتهای اضافه میشوند که در آن آخرین تماس فعال اضافه شده، ژست برگشتی بعدی را با یک تماس در هر حرکت برگشتی انجام میدهد.
انیمیشن ژستهای برگشتی پیشبینیکننده را آزمایش کنید
با شروع نسخه نهایی اندروید 13، باید بتوانید یک گزینه توسعه دهنده را برای آزمایش انیمیشن بازگشت به خانه نشان داده شده در شکل 1 فعال کنید.
برای تست این انیمیشن مراحل زیر را انجام دهید:
در دستگاه خود، به تنظیمات > سیستم > گزینههای برنامهنویس بروید.
انیمیشنهای برگشتی پیشبینیکننده را انتخاب کنید.
برنامه بهروزرسانیشدهتان را راهاندازی کنید و از ژست برگشتی برای مشاهده آن در عمل استفاده کنید.