
تتيح ميزة "إيماءة إظهار شاشة الرجوع"، وهي إحدى ميزات التنقّل بالإيماءات، للمستخدمين معاينة المكان الذي ستنقلهم إليه إيماءة الرجوع.
على سبيل المثال، يمكن أن تؤدي إيماءة الرجوع إلى عرض معاينة متحركة للشاشة الرئيسية خلف تطبيقك، كما هو موضّح في النموذج التجريبي في الشكل 1.
اعتبارًا من Android 15، لن يعود خيار المطوّر لصور الرجوع التنبؤي المتحركة متوفّرًا. تظهر الآن صور متحركة للنظام، مثل الرجوع إلى الشاشة الرئيسية والتنقّل بين المهام والتنقّل بين الأنشطة، للتطبيقات التي فعّلت إيماءة "الرجوع التوقّعي" بالكامل أو على مستوى النشاط.
يمكنك اختبار هذه الحركة عند الرجوع إلى الصفحة الرئيسية (كما هو موضّح في قسم لاحق من هذه الصفحة).
يتطلّب إتاحة استخدام الإيماءة التنبؤية للرجوع تحديث تطبيقك واستخدام
OnBackPressedCallback
الإصدار 1.6.0-alpha05 من AppCompat
(AndroidX) أو إصدار أحدث من واجهة برمجة التطبيقات المتوافقة مع الإصدارات القديمة، أو استخدام OnBackInvokedCallback
واجهة برمجة التطبيقات الجديدة للنظام الأساسي. تستخدم معظم التطبيقات واجهة AndroidX API المتوافقة مع الإصدارات القديمة.
يوفّر هذا التحديث مسار نقل البيانات لاعتراض التنقّل للخلف بشكل صحيح،
ويشمل ذلك استبدال عمليات اعتراض التنقّل للخلف من KeyEvent.KEYCODE_BACK
وأي فئات تتضمّن طرق onBackPressed
مثل Activity
و
Dialog
بواجهات برمجة التطبيقات الجديدة لإيماءة الرجوع في النظام.
فيديو الدرس التطبيقي حول الترميز ومؤتمر Google I/O
بالإضافة إلى استخدام هذه المستندات على هذه الصفحة، يمكنك تجربة الدرس التطبيقي. توفّر هذه المكتبة عملية تنفيذ شائعة لحالة استخدام WebView التي تتعامل مع إيماءة "الرجوع التوقّعي" باستخدام واجهات برمجة التطبيقات Activity في AndroidX.
يمكنك أيضًا مشاهدة فيديو Google I/O الذي يتضمّن أمثلة إضافية حول تنفيذ واجهات برمجة التطبيقات AndroidX وواجهات برمجة التطبيقات الخاصة بالمنصة.
تحديث تطبيق يستخدم ميزة "الرجوع" التلقائية
يتم تفعيل ميزة "الرجوع التوقّعي" تلقائيًا.
إذا كان تطبيقك يستخدم "التقسيمات" أو "مكوّن التنقّل"، عليك أيضًا الترقية إلى الإصدار AndroidX Activity 1.6.0-alpha05 أو إصدار أحدث.
تعديل تطبيق يستخدم التنقّل المخصّص للخلف
إذا كان تطبيقك ينفّذ سلوكًا مخصّصًا للرجوع، تتوفّر مسارات نقل بيانات مختلفة حسب ما إذا كان يستخدم AndroidX وكيفية تعامله مع التنقّل للخلف.
يستخدم تطبيقك AndroidX | طريقة تعامل تطبيقك مع التنقّل للخلف | مسار نقل البيانات المقترَح (رابط على هذه الصفحة) |
نعم | واجهات برمجة تطبيقات AndroidX | نقل عملية تنفيذ حالية للرجوع في AndroidX |
واجهات برمجة التطبيقات غير المتوافقة مع النظام الأساسي | نقل تطبيق AndroidX يحتوي على واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات AndroidX | |
لا | واجهات برمجة التطبيقات غير المتوافقة مع النظام الأساسي، ولكن يمكن نقلها | نقل تطبيق يستخدم واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات النظام الأساسي |
واجهات برمجة تطبيقات غير متوافقة مع النظام الأساسي، ولكن يتعذّر نقلها | يمكنك إيقاف هذه الميزة مؤقتًا من خلال ضبط السمة android:enableOnBackInvokedCallback على false في العلامة
<application> أو <activity> في ملف AndroidManifest.xml الخاص بتطبيقك. |
نقل عملية تنفيذ ميزة الرجوع إلى الصفحة السابقة في AndroidX
تُعدّ حالة الاستخدام هذه هي الأكثر شيوعًا (والأكثر يُنصح بها). وينطبق ذلك على التطبيقات الجديدة أو الحالية التي تنفّذ معالجة مخصّصة للتنقّل بالإيماءات باستخدام OnBackPressedDispatcher
، كما هو موضّح في توفير تنقّل مخصّص للرجوع.
للتأكّد من أنّ واجهات برمجة التطبيقات التي تستخدم OnBackPressedDispatcher
حاليًا (مثل "التقسيمات" و"مكوّن التنقّل") تعمل بسلاسة مع إيماءة "الرجوع التوقّعي"، عليك الترقية إلى الإصدار 1.6.0-alpha05 من مكتبة AndroidX Activity.
```xml
// In your build.gradle file:
dependencies {
// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
نقل تطبيق AndroidX يحتوي على واجهات برمجة تطبيقات غير متوافقة مع التنقّل للخلف إلى واجهات برمجة تطبيقات AndroidX
إذا كان تطبيقك يستخدم مكتبات AndroidX ولكنه ينفّذ أو يشير إلى واجهات برمجة التطبيقات غير المتوافقة مع التنقّل للخلف، عليك نقل البيانات إلى واجهات برمجة تطبيقات AndroidX لإتاحة السلوك الجديد.
لنقل البيانات من واجهات برمجة التطبيقات غير المتوافقة إلى واجهات برمجة تطبيقات AndroidX، اتّبِع الخطوات التالية:
انقل منطق معالجة زر الرجوع في نظامك إلى
OnBackPressedDispatcher
في AndroidX مع تنفيذOnBackPressedCallback
. للحصول على إرشادات مفصّلة، يُرجى الاطّلاع على توفير التنقّل المخصّص للخلف.أوقِف
OnBackPressedCallback
عندما تكون مستعدًا لإيقاف اعتراض إيماءة الرجوع.أوقِف اعتراض أحداث الرجوع باستخدام
OnBackPressed
أوKeyEvent.KEYCODE_BACK
.احرص على الترقية إلى الإصدار 1.6.0-alpha05 من AndroidX Activity.
// In your build.gradle file: dependencies { // Add this in addition to your other dependencies implementation "androidx.activity:activity:1.6.0-alpha05"
نقل بيانات تطبيق يستخدم واجهات برمجة تطبيقات غير متوافقة للرجوع إلى الخلف إلى واجهات برمجة تطبيقات النظام الأساسي
إذا كان تطبيقك لا يمكنه استخدام مكتبات AndroidX ويستخدم بدلاً من ذلك ميزة التنقّل المخصّص للخلف أو يشير إليها باستخدام واجهات برمجة التطبيقات غير المتوافقة، عليك نقل البيانات إلى OnBackInvokedCallback
واجهة برمجة التطبيقات الخاصة بالمنصة.
أكمِل الخطوات التالية لنقل واجهات برمجة التطبيقات غير المتوافقة إلى واجهة برمجة التطبيقات الخاصة بالمنصة:
استخدِم واجهة برمجة التطبيقات
OnBackInvokedCallback
الجديدة على الأجهزة التي تعمل بنظام التشغيل Android 13 أو الإصدارات الأحدث، واعتمد على واجهات برمجة التطبيقات غير المتوافقة على الأجهزة التي تعمل بنظام التشغيل Android 12 أو الإصدارات الأقدم.سجِّل منطق الرجوع المخصّص في
OnBackInvokedCallback
باستخدامonBackInvokedDispatcher
. يمنع ذلك إنهاء النشاط الحالي، ويمنح دالة رد الاتصال فرصة للرد على إجراء "الرجوع" بعد أن يكمل المستخدم عملية التنقّل إلى الخلف في النظام.ألغِ تسجيل
OnBackInvokedCallback
عندما تكون مستعدًا لإيقاف اعتراض الإيماءة الرجوع. بخلاف ذلك، قد يلاحظ المستخدمون سلوكًا غير مرغوب فيه عند استخدام ميزة "الرجوع" في النظام، مثل "التعليق" بين طرق العرض وإجبارهم على إيقاف تطبيقك بالقوة.في ما يلي مثال على كيفية نقل المنطق خارج
onBackPressed
:Kotlin
@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) */ } } }
Java
@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
في الإصدار 13 من نظام التشغيل Android والإصدارات الأحدث.
يمكنك تسجيل OnBackInvokedCallback
باستخدام PRIORITY_DEFAULT
أو PRIORITY_OVERLAY
، وهو غير متاح في OnBackPressedCallback
المشابهة في AndroidX. يُعدّ تسجيل دالة ردّ نداء باستخدام PRIORITY_OVERLAY
مفيدًا في بعض الحالات.
ينطبق ذلك عند نقل البيانات من onKeyPreIme()
، وعندما يحتاج رد الاتصال إلى تلقّي إيماءة الرجوع بدلاً من فتح محرر أسلوب الإدخال (IME). تسجّل طرق الإدخال عمليات رد الاتصال باستخدام PRIORITY_DEFAULT
عند فتحها. سجِّل دالة رد الاتصال باستخدام PRIORITY_OVERLAY
لضمان إرسال OnBackInvokedDispatcher
إيماءة الرجوع إلى دالة رد الاتصال
بدلاً من فتح محرّك طرق الإدخال.
إيقاف ميزة "الرجوع التوقّعي"
لإيقاف هذه الميزة، اضبط العلامة android:enableOnBackInvokedCallback
على false
في علامة <application>
ضمن AndroidManifest.xml
.
<application
...
android:enableOnBackInvokedCallback="false"
... >
...
</application>
يؤدي ضبط هذا الخيار على "خطأ" إلى ما يلي:
- يؤدي ذلك إلى إيقاف الصورة المتحركة في النظام لإيماءة الرجوع إلى الخلف التنبؤية.
- يتجاهل
OnBackInvokedCallback
، ولكن تستمر عمليات استدعاءOnBackPressedCallback
في العمل.
إيقاف الإعداد على مستوى النشاط
بدءًا من Android 16، يتيح لك العلامة 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
على مستوى التطبيق إلى تحديد القيمة التلقائية لجميع الأنشطة في التطبيق. ويمكنك تجاهل القيمة التلقائية لكل نشاط من خلال ضبط العلامة على مستوى النشاط، كما هو موضّح في مثال الرمز البرمجي السابق.
أفضل الممارسات المتعلّقة بوظائف معاودة الاتصال
في ما يلي أفضل الممارسات لاستخدام عمليات معاودة الاتصال المتوافقة مع الرجوع إلى الخلف في النظام:
BackHandler
(في Compose) أو OnBackPressedCallback
أو OnBackInvokedCallback
.
تحديد حالة واجهة المستخدم التي تفعّل كلّ دالة ردّ نداء وتوقفها
حالة واجهة المستخدم هي سمة تصف واجهة المستخدم. ننصحك باتّباع الخطوات العامة التالية.
تحديد حالة واجهة المستخدم التي تتيح تفعيل كل دالة رد نداء وإيقافها
حدِّد هذه الحالة باستخدام نوع حامل البيانات القابل للمراقبة، مثل
StateFlow
أو Compose State، وفعِّل أو أوقِف معاودة الاتصال عند تغيُّر الحالة.
إذا كان تطبيقك يربط منطق الرجوع إلى الخلف بعبارات شرطية، قد يشير ذلك إلى أنّك تتفاعل مع حدث الرجوع إلى الخلف بعد حدوثه. تجنَّب هذا النمط باستخدام عمليات معاودة الاتصال الأحدث. إذا أمكن، يمكنك نقل دالة معاودة الاتصال إلى خارج العبارة الشرطية وربطها بدلاً من ذلك بنوع حامل البيانات القابل للمراقبة.
استخدام عمليات معاودة الاتصال الخاصة بالرجوع إلى الخلف في النظام لمنطق واجهة المستخدم
تحدّد منطق واجهة المستخدم كيفية عرض واجهة المستخدم. استخدِم عمليات رد الاتصال الخاصة بإيماءة الرجوع إلى الخلف في النظام لتنفيذ منطق واجهة المستخدم، مثل عرض مربّع حوار أو تشغيل صورة متحركة.
إذا كان تطبيقك يفعّل OnBackPressedCallback
أو OnBackInvokedCallback
مع PRIORITY_DEFAULT
أو PRIORITY_OVERLAY
، لن يتم تشغيل رسوم "إيماءة الرجوع التوقّعية"، وعليك التعامل مع حدث الرجوع. لا تنشئ عمليات ردّ الاتصال هذه لتنفيذ منطق النشاط التجاري أو التسجيل.
استخدِم الطرق التالية إذا كان تطبيقك يحتاج إلى تنفيذ منطق النشاط التجاري أو تسجيل الدخول عند تمرير المستخدم سريعًا للرجوع:
- استخدِم
OnBackInvokedCallback
معPRIORITY_SYSTEM_NAVIGATION_OBSERVER
على الأجهزة التي تعمل بالإصدار 16 من نظام التشغيل Android والإصدارات الأحدث. يؤدي ذلك إلى إنشاء دالة رد نداء للمراقب لا تستهلك حدث الرجوع. على سبيل المثال، يمكنك تسجيل معاودة الاتصال هذه عندما ينزلق المستخدم سريعًا للرجوع من النشاط الأساسي، أو بعبارة أخرى، عندما يغادر المستخدم تطبيقك. وفي هذه الحالة، يمكنك تسجيل حدث الرجوع أو تنفيذ منطق تجاري آخر، وسيستمر تشغيل الرسوم المتحركة للرجوع إلى الشاشة الرئيسية. - بالنسبة إلى حالات الانتقال من نشاط إلى آخر أو من جزء إلى نشاط، سجِّل ما إذا كان
isFinishing
ضمنonDestroy
هوtrue
ضمن دورة حياة النشاط. - بالنسبة إلى حالات الانتقال من جزء إلى آخر، سجِّل ما إذا كانت قيمة
isRemoving
ضمنonDestroy
هي true خلال دورة حياة عرض الجزء. أو سجِّل الدخول باستخدام طريقتَيonBackStackChangeStarted
أوonBackStackChangeCommitted
ضمنFragmentManager.OnBackStackChangedListener
. - بالنسبة إلى حالة Compose، سجِّل الدخول ضمن معاودة الاتصال
onCleared()
الخاصة بـViewModel
المرتبط بوجهة Compose. هذه هي أفضل إشارة لمعرفة وقت إزالة وجهة Compose من الخلف وتدميرها.
إنشاء عمليات ردّ نداء ذات مسؤولية فردية
يمكنك إضافة عدة دوال ردّ إلى أداة الإرسال. تتم إضافة عمليات معاودة الاتصال إلى حزمة، حيث تعالج عملية معاودة الاتصال المفعَّلة التي تمت إضافتها آخر مرة إيماءة الرجوع التالية، وذلك بمعدل عملية معاودة اتصال واحدة لكل إيماءة رجوع.
يسهل إدارة حالة التفعيل لدالة رد الاتصال إذا كانت هذه الدالة تتضمّن مسؤولية واحدة. مثلاً:

يوضّح الشكل 2 كيف يمكنك الحصول على عدة عمليات ردّ في الحزمة، كل منها مسؤول عن شيء واحد. لا يتم تنفيذ دالة معاودة الاتصال إلا إذا تم إيقاف دوال معاودة الاتصال التي تسبقها في حزمة البيانات. في هذا المثال، يتم تفعيل وظيفة الاستدعاء "هل أنت متأكد..." عندما يُدخل المستخدِم بيانات في نموذج، ويتم إيقافها في الحالات الأخرى. يفتح دالة الرجوع مربّع حوار تأكيد عندما يتراجع المستخدم للخروج من النموذج.
يمكن أن تتضمّن دالة الرجوع الأخرى أحد عناصر Material التي تتوافق مع ميزة "الرجوع التوقّعي"، أو عملية انتقال AndroidX باستخدام واجهات برمجة التطبيقات Progress، أو دالة رجوع مخصّصة أخرى.
يتم تنفيذ معاودة الاتصال الخاصة بـ childFragmentManager
إذا كانت معاودات الاتصال أعلاه غير مفعّلة ولم يكن سجلّ الرجوع الخاص بـ FragmentManager
فارغًا، حيث يتم إرفاق childFragmentManager
ضمن Fragment. في هذا المثال، تم إيقاف رد الاتصال الداخلي هذا.
وبالمثل، يتم تنفيذ معاودة الاتصال الداخلية الخاصة بـ supportFragmentManager
إذا تم إيقاف معاودات الاتصال المذكورة أعلاه وكان المكدس غير فارغ. ويكون هذا السلوك متسقًا عند استخدام FragmentManager
أو NavigationComponent
للتنقّل، لأنّ NavigationComponent
تعتمد على FragmentManager
. في هذا المثال، يتم تنفيذ دالة معاودة الاتصال هذه إذا لم يُدخل المستخدم نصًا في النموذج، ما يؤدي إلى إيقاف دالة معاودة الاتصال "هل أنت متأكد...".
أخيرًا، super.onBackPressed()
هي معاودة الاتصال على مستوى النظام، والتي يتم تنفيذها مرة أخرى في حال إيقاف معاودات الاتصال أعلاه. لتفعيل الصور المتحركة في النظام، مثل الرجوع إلى الشاشة الرئيسية والتنقل بين الأنشطة والمهام، يجب أن يكون سجلّ الرجوع في supportFragmentManager
فارغًا حتى يتم إيقاف معاودة الاتصال الداخلية.
اختبار الصورة المتحركة لإيماءة الرجوع إلى الخلف التنبؤية
إذا كنت لا تزال تستخدم Android 13 أو Android 14، يمكنك اختبار الرسوم المتحركة للرجوع إلى الشاشة الرئيسية الموضّحة في الشكل 1.
لاختبار هذه الصورة المتحركة، أكمِل الخطوات التالية:
على جهازك، انتقِل إلى الإعدادات > النظام > خيارات المطوّرين.
اختَر صور متحركة تعرض إيماءة الرجوع إلى الخلف التنبؤية.
شغِّل تطبيقك المُحدَّث، واستخدِم إيماءة الرجوع لرؤية تأثيرها.