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

شکل ۱. ماکت ظاهر و حس ژست پیش‌بینی‌کننده‌ی بازگشت در یک تلفن

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

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

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

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

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

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

نکته: KeyEvent.KEYCODE_BACK منسوخ نشده است زیرا برخی موارد استفاده پشتیبانی شده از KeyEvent.KEYCODE_BACK وجود دارد؛ با این حال، رهگیری رویدادهای برگشتی از KeyEvent.KEYCODE_BACK دیگر پشتیبانی نمی‌شود.

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

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

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

مدیریت حرکات برگشت سفارشی در نوشتن

Compose PredictiveBackHandler composable را برای مدیریت حرکات برگشت سفارشی ارائه می‌دهد. این API به شما امکان می‌دهد به حرکت برگشت پاسخ دهید و Flow از اشیاء BackEventCompat را ارائه می‌دهد که می‌توانید از آنها برای پیاده‌سازی انیمیشن‌ها یا انتقال‌های سفارشی هنگام کشیدن انگشت کاربر استفاده کنید.

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress
        }
        // Handle the final back action (e.g., navigate back)
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI
    }
}

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

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

قابلیت پیش‌بینی بازگشت به عقب به طور پیش‌فرض فعال است.

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

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

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

نحوه مدیریت ناوبری برگشتی در اپلیکیشن شما	مسیر مهاجرت پیشنهادی (لینک در همین صفحه)
رابط‌های برنامه‌نویسی کاربردی اندروید ایکس	انتقال یک پیاده‌سازی موجود AndroidX به نسخه قبلی
APIهای پلتفرم پشتیبانی نشده	یک برنامه AndroidX حاوی APIهای ناوبری برگشتی پشتیبانی نشده را به APIهای AndroidX منتقل کنید

مهم: اکیداً توصیه می‌کنیم که در اسرع وقت قابلیت پیش‌بینی بازگشت به عقب را پیاده‌سازی کنید. در غیر این صورت، ممکن است کاربران در نسخه‌های بعدی اندروید با رفتار غیرمنتظره‌ای مواجه شوند.

انتقال یک پیاده‌سازی ناوبری برگشتی AndroidX

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

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

```xml
// 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 مهاجرت کنید.

توجه: ما اکیداً استفاده از کتابخانه‌های AndroidX را توصیه می‌کنیم. AndroidX به طور خودکار به‌روزرسانی سیستم ناوبری برگشت را در برنامه شما فعال می‌کند، وقتی این ویژگی را فعال می‌کنید، و همچنین بسیاری از ویژگی‌های مفید دیگر را ارائه می‌دهد که به طور خودکار APIها را با هر نسخه به‌روزرسانی می‌کنند تا در کار و زمان شما صرفه‌جویی شود.

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

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

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"
   

   نکته: OnBackPressedCallback صرف نظر از مقدار android:enableOnBackInvokedCallback همیشه فراخوانی می‌شود. به عبارت دیگر، غیرفعال کردن انیمیشن سیستمی در صورت استفاده از OnBackPressedCallback ، بر منطق مدیریت بازگشت برنامه شما تأثیری نمی‌گذارد.

از حالت پیش‌بینی‌شده‌ی بازگشت انصراف دهید

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

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

تنظیم این مقدار روی false موارد زیر را انجام می‌دهد:

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

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

پرچم 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 نکات زیر را در نظر داشته باشید:

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

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

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

وضعیت رابط کاربری که هر فراخوانی برگشتی را فعال و غیرفعال می‌کند، تعیین کنید.

وضعیت رابط کاربری (UI state ) یک ویژگی (property) است که رابط کاربری (UI) را توصیف می‌کند. توصیه می‌کنیم این مراحل سطح بالا را دنبال کنید.

1. وضعیت رابط کاربری که هر فراخوانی برگشتی را فعال و غیرفعال می‌کند، تعیین کنید.

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

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

استفاده از فراخوانی‌های سیستمی برای منطق رابط کاربری

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

اگر برنامه شما OnBackPressedCallback یا OnBackInvokedCallback با PRIORITY_DEFAULT یا PRIORITY_OVERLAY فعال کند، انیمیشن‌های پیش‌بین back اجرا نمی‌شوند و شما باید رویداد back را مدیریت کنید. این callbackها را برای اجرای منطق کاری یا ثبت وقایع ایجاد نکنید.

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

• در دستگاه‌هایی که اندروید ۱۶ و بالاتر دارند، OnBackInvokedCallback به همراه PRIORITY_SYSTEM_NAVIGATION_OBSERVER استفاده کنید. این کار یک تابع فراخوانی ناظر (Observer-callback) ایجاد می‌کند که رویداد بازگشت (back event) را مصرف نمی‌کند. برای مثال، می‌توانید این تابع فراخوانی را زمانی ثبت کنید که کاربر از اکتیویتی ریشه به عقب برمی‌گردد، یا به عبارت دیگر، زمانی که کاربر برنامه شما را ترک کرده است. در این حالت، می‌توانید رویداد بازگشت را ثبت کنید یا منطق کاری دیگری را اجرا کنید، و انیمیشن بازگشت به خانه همچنان پخش خواهد شد.
• برای موارد فعالیت به فعالیت یا موارد قطعه به فعالیت، اگر isFinishing درون onDestroy درون چرخه حیات Activity true باشد، لاگ کنید.
• برای موارد قطعه به قطعه، اگر isRemoving درون onDestroy درون چرخه حیات نمای قطعه درست باشد، لاگ کنید. یا با استفاده از متدهای onBackStackChangeStarted یا onBackStackChangeCommitted درون FragmentManager.OnBackStackChangedListener لاگ بگیرید.
• برای مورد Compose، در تابع فراخوانی onCleared() از ViewModel مرتبط با مقصد Compose، لاگ بگیرید. این بهترین سیگنال برای اطلاع از زمانی است که یک مقصد compose از پشته حذف و نابود می‌شود.

ایجاد فراخوانی‌های تک مسئولیتی

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

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

شکل ۲. نمودار پشته فراخوانی.

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

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

همین رفتار پشته‌ای در Compose نیز اعمال می‌شود: درونی‌ترین PredictiveBackHandler یا BackHandler اولویت دارد.

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

به همین ترتیب، فراخوانی داخلی supportFragmentManager در صورتی اجرا می‌شود که فراخوانی‌های فوق غیرفعال باشند و پشته آن خالی نباشد. در این مثال، این فراخوانی در صورتی اجرا می‌شود که کاربر متنی را در فرم وارد نکرده باشد و باعث غیرفعال شدن فراخوانی "Are you sure..." شود.

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

انیمیشن پیش‌بینی حرکت برگشت را آزمایش کنید

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

اگر هنوز از اندروید ۱۳ یا اندروید ۱۴ استفاده می‌کنید، می‌توانید انیمیشن بازگشت به خانه نشان داده شده در شکل ۱ را آزمایش کنید.

برای آزمایش این انیمیشن، مراحل زیر را انجام دهید:

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

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

3. برنامه‌ی به‌روزرسانی‌شده‌تان را اجرا کنید و با استفاده از ژست حرکتی «بازگشت» (back) آن را در عمل مشاهده کنید.