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

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

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

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

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

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

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

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

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

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

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

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

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

// 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 استفاده می‌کند، آن را به AndroidX Activity 1.6.0 یا بالاتر نیز ارتقا دهید.

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

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

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

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

برای اطمینان از اینکه APIهایی که از قبل OnBackPressedDispatcher استفاده می‌کنند (مانند Fragments و کامپوننت Navigation) به طور یکپارچه با حرکت پیش‌بینی‌کننده‌ی بازگشت کار می‌کنند، 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 حاوی APIهای ناوبری برگشتی پشتیبانی نشده را به APIهای AndroidX منتقل کنید

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

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

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

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>

تنظیم این مقدار روی 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ها را برای اجرای منطق کاری یا ثبت وقایع ایجاد نکنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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