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

«برگشت پیش‌گویانه»، که ویژگی پیمایش اشاره‌ای است، به کاربران امکان می‌دهد پیش‌نمایش مقصد تند کشیدن برای برگشت را ببینند.

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

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

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

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

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

Codelab و ویدیو Google I/O

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

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

مدیریت اشاره‌های برگشت سفارشی در Compose

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

برای استفاده از PredictiveBackHandler، مطمئن شوید برنامه‌تان شامل وابستگی androidx.activity:activity-compose (نسخه ۱.۸.۰ یا بالاتر) باشد:

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

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.
    }
}
PredictiveBackSnippets.kt

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. حتماً به AndroidX Activity نسخه ۱.۶.۰ یا بالاتر ارتقا دهید.

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

انصراف از اشاره برگشت پیش‌گویانه

برای انصراف دادن، در 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 پویانمایی‌های برگشت پیش‌بینانه را در سطح فعالیت یا در سطح برنامه خاموش می‌کند (بسته به اینکه برچسب را کجا تنظیم کرده باشید) و به سیستم دستور می‌دهد تماس‌های برقرارشده با میانای برنامه‌سازی کاربردی پلاتفرم OnBackInvokedCallback را نادیده بگیرد. بااین‌حال، تماس‌ها با OnBackPressedCallback همچنان اجرا می‌شوند زیرا OnBackPressedCallback با نسخه قدیمی سازگار است و با میانای برنامه‌سازی کاربردی onBackPressed تماس می‌گیرد که قبل‌از Android 13 پشتیبانی نمی‌شود.
• تنظیم پرچم enableOnBackInvokedCallback در سطح برنامه، مقدار پیش‌فرض را برای همه فعالیت‌ها در برنامه تعیین می‌کند. می‌توانید با تنظیم پرچم در سطح فعالیت، مقدار پیش‌فرض را برای هر فعالیت لغو کنید، همان‌طور که در نمونه کد قبلی نشان داده شده است.

رهنمودهای پاسخ تماس

هنگام استفاده از فراخوان‌های برگشت سیستم پشتیبانی‌شده، این دستورالعمل‌ها را دنبال کنید: PredictiveBackHandler یا BackHandler (برای Compose)، OnBackPressedCallback، یا OnBackInvokedCallback.

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

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

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

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

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

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

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

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

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

• در Compose: در بازخوانی onCleared() مربوط به ViewModel مرتبط با مقصد Compose ثبت کنید. این بهترین سیگنال برای دانستن زمانی است که مقصد Compose از پشته قبلی‌ها خارج و نابود می‌شود.
• در Android 16 و بالاتر: از OnBackInvokedCallback با PRIORITY_SYSTEM_NAVIGATION_OBSERVER استفاده کنید. این کار یک فراخوان ناظر ایجاد می‌کند که رویداد برگشت را مصرف نمی‌کند. برای مثال، می‌توانید این callback را وقتی کاربر از فعالیت ریشه تند به‌عقب می‌کشد (برنامه شما را ترک می‌کند) ثبت کنید تا رویداد برگشت را ثبت کند یا منطق کسب‌وکار را اجرا کند و درعین‌حال اجازه دهد پویانمایی برگشت به صفحه اصلی پخش شود.
• در برنامه‌های مبتنی بر View: به‌جای مصرف رویدادهای برگشت، در فراخوانی‌های برگشتی پشته قبلی‌ها یا چرخه حیات ثبت کنید:
  • برای انتقال فعالیت، بررسی کنید که آیا isFinishing در true Activity.onDestroy() است یا نه.
  • برای انتقال‌های قطعه، بررسی کنید که آیا isRemoving در چرخه حیات نمای قطعه onDestroy()، true است یا از FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted) استفاده کنید.

ایجاد فراخوانی‌های برگشتی با مسئولیت واحد

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

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

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

• کادر گفتگوی «مطمئنید…» PredictiveBackHandler وقتی فعال می‌شود که کاربر داده‌ها را در فرمی وارد کند، و درغیراین‌صورت غیرفعال می‌شود. وقتی فعال باشد، اشاره برگشت را رهگیری می‌کند تا کادر گفتگوی تأیید یا پویانمایی درون‌برنامه سفارشی را نمایش دهد.
• اگر فراخوانی قبلی غیرفعال باشد، BackHandler سطح صفحه اجرا می‌شود. در این مثال، غیرفعال است.
• اگر فراخوان‌های سفارشی قبلی غیرفعال باشند، فراخوان NavHost پیمایش به عقب را برای خارج کردن مقصدها از پشته قبلی‌ها مدیریت می‌کند.
• درنهایت، اگر همه فراخوانی‌های قبلی غیرفعال باشند، سیستم اشاره برگشت را مدیریت می‌کند. وقتی پشته قبلی‌ها در مقصد ریشه‌ای خود باشد، سیستم پویانمایی‌های سطح سیستم را راه‌اندازی می‌کند، مثل برگشت به صفحه اصلی، بین فعالیتی، و بین تکلیفی.

همین رفتار پشته در برنامه‌های مبتنی بر View اعمال می‌شود: آخرین OnBackPressedCallback فعال‌شده اضافه‌شده اولویت دارد، و درصورت عدم موفقیت به FragmentManager و درنهایت به مدیریت برگشت سیستم برمی‌گردد.

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

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

در دستگاه‌های دارای Android 13 یا Android 14، می‌توانید گزینه توسعه‌دهنده را برای آزمایش پویانمایی برگشت به صفحه اصلی نشان‌داده‌شده در شکل ۱ فعال کنید:

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

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

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