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

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

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

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

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

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

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

ویدیو Codelab و Google I/O

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

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

کنترل اشاره‌های برگشت سفارشی در «نوشتن»

«ترکیب» 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 استفاده کنید.

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

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

اگر برنامه‌تان از «تکه‌کدها» یا «عنصر پیمایش» استفاده می‌کند، به AndroidX Activity 1.6.0 یا بالاتر نیز ارتقا دهید.

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

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

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

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

برای اطمینان از اینکه میاناهای برنامه‌سازی کاربردی که ازقبل از OnBackPressedDispatcher (مثل «تکه‌تکه کردن» و «عنصر پیمایش») استفاده می‌کنند به‌طور یکپارچه با اشاره برگشت پیش‌بینی‌کننده کار می‌کنند، به 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. منطق مدیریت «بازگشت» سیستم خود را به AndroidX's OnBackPressedDispatcher با پیاده‌سازی OnBackPressedCallback انتقال دهید. برای راهنمایی دقیق، به ارائه ناوبری برگشت سفارشی مراجعه کنید.

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

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

4. حتماً به 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"
   }
   

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

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

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

اگر این تنظیم را روی «نادرست» قرار دهید، موارد زیر اتفاق می‌افتد:

• پویانمایی سیستم اشاره برگشت پیش‌گویانه را غیرفعال می‌کند.
• 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 (برای «نوشتن»)، OnBackPressedCallback، یا OnBackInvokedCallback.

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

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

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

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

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

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

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

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

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

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

ایجاد کردن کارگزاری‌های تک‌مسئولیتی

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

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

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

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

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

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

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

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

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

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

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