إتاحة استخدام إيماءة توقّع شاشة الرجوع

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تتيح ميزة "إظهار شاشة الرجوع"، وهي ميزة تنقّل بالإيماءات، للمستخدمين معاينة الصفحات التي سينقلهم إليها التمرير سريعًا للخلف.

على سبيل المثال، يمكن أن يؤدي استخدام إيماءة للرجوع إلى عرض معاينة متحركة للشاشة الرئيسية خلف تطبيقك، كما هو موضّح في التصميم التجريبي بالشكل 1.

اعتبارًا من الإصدار 15 من نظام التشغيل Android، لن يعود خيار المطوّر للرسوم المتحركة التنبؤية للرجوع إلى الخلف متاحًا. تظهر الآن الصور المتحركة للنظام، مثل الرجوع إلى الشاشة الرئيسية والتنقّل بين المهام والأنشطة، للتطبيقات التي فعّلت ميزة "إيماءة الرجوع التوقّعي" بالكامل أو على مستوى نشاط معيّن.

يمكنك اختبار هذا التأثير المتحرك للعودة إلى الصفحة الرئيسية (كما هو موضّح في القسم التالي من هذه الصفحة).

يتطلب تفعيل ميزة الإيماءة التوقّعية للرجوع تحديث تطبيقك باستخدام واجهة برمجة التطبيقات المتوافقة مع الإصدارات القديمة OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) أو إصدار أحدث، أو استخدام واجهة برمجة التطبيقات الجديدة OnBackInvokedCallback platform API. تستخدم معظم التطبيقات واجهة برمجة التطبيقات AndroidX API المتوافقة مع الإصدارات القديمة.

يقدّم هذا التعديل مسار نقل بيانات لمنع التنقّل للخلف بشكلٍ سليم، ويشمل ذلك استبدال عمليات اعتراض الرجوع من KeyEvent.KEYCODE_BACK وأي فئات تتضمّن طرق onBackPressed مثل Activity و Dialog باستخدام واجهات برمجة تطبيقات النظام الجديدة لمنع التنقّل للخلف.

فيديو حول الدرس التطبيقي حول الترميز ومؤتمر Google I/O

بالإضافة إلى استخدام هذه المستندات في هذه الصفحة، يمكنك تجربة الدرس التطبيقي حول الترميز. ويقدّم هذا الإصدار تنفيذًا شائعًا لحالة الاستخدام في WebView من خلال معالجة إيماءة الرجوع التوقّعية باستخدام واجهات برمجة تطبيقات AndroidX Activity.

يمكنك أيضًا مشاهدة فيديو Google I/O الذي يعرض أمثلة إضافية على تنفيذ واجهات برمجة التطبيقات AndroidX وواجهات برمجة التطبيقات الخاصة بالنظام الأساسي.

تعديل تطبيق يستخدم ميزة التنقّل للخلف التلقائية

تكون ميزة "الرجوع التوقّعي" مفعّلة تلقائيًا.

إذا كان تطبيقك يستخدم "المقاطع" أو "مكوّن التنقّل"، عليك أيضًا الترقية إلى AndroidX Activity 1.6.0-alpha05 أو إصدار أحدث.

تحديث تطبيق يستخدم ميزة التنقّل للخلف المخصّصة

إذا كان تطبيقك ينفِّذ سلوكًا مخصّصًا للرجوع، تتوفّر مسارات نقل بيانات مختلفة حسب ما إذا كان يستخدم AndroidX وطريقة معالجته للتنقّل للخلف.

نقل عملية تنفيذ ميزة الرجوع إلى الصفحة السابقة في AndroidX

وتعدّ حالة الاستخدام هذه هي الأكثر شيوعًا (والأكثر اقتراحًا). وينطبق ذلك على التطبيقات الجديدة أو الحالية التي توفّر معالجة مخصّصة للتنقّل باستخدام الإيماءات باستخدام OnBackPressedDispatcher، كما هو موضّح في توفير ميزة التنقّل للخلف المخصّصة.

للتأكّد من أنّ واجهات برمجة التطبيقات التي تستخدم OnBackPressedDispatcher (مثل "المقاطع" و"مكوّن التنقّل") تعمل بسلاسة مع إيماءة الرجوع التوقّعية، عليك الترقية إلى 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 يحتوي على واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات AndroidX

إذا كان تطبيقك يستخدم مكتبات AndroidX ولكنه ينفِّذ واجهات برمجة التطبيقات غير المتوافقة للتنقّل للخلف أو يشير إليها، عليك نقل البيانات لاستخدام واجهات برمجة التطبيقات في AndroidX لتوفير السلوك الجديد.

لنقل واجهات برمجة التطبيقات غير المتوافقة إلى واجهات برمجة تطبيقات AndroidX:

1. نقل منطق معالجة Back في النظام إلى ملف OnBackPressedDispatcher في AndroidX باستخدام تنفيذ OnBackPressedCallback للحصول على إرشادات مفصّلة، يُرجى الاطّلاع على مقالة توفير ميزة التنقّل للخلف المخصّصة.

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"
   

نقل بيانات تطبيق يستخدم واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات النظام الأساسي

إذا لم يتمكّن تطبيقك من استخدام مكتبات AndroidX، ونفَّذ بدلاً من ذلك واجهة برمجة تطبيقات مخصّصة للرجوع أو أشار إليها باستخدام واجهات برمجة التطبيقات غير المتوافقة، يجب نقل بياناته إلى واجهة برمجة تطبيقات نظام التشغيل OnBackInvokedCallback.

أكمِل الخطوات التالية لنقل واجهات برمجة التطبيقات غير المتوافقة إلى واجهة برمجة تطبيقات النظام الأساسي:

1. استخدِم واجهة برمجة التطبيقات OnBackInvokedCallback الجديدة على الأجهزة التي تعمل بنظام Android 13 أو الإصدارات الأحدث، واعتمد على واجهات برمجة التطبيقات غير المتوافقة على الأجهزة التي تعمل بنظام Android 12 أو الإصدارات الأقدم.

2. سجِّل منطق الرجوع المخصّص في OnBackInvokedCallback باستخدام onBackInvokedDispatcher. يمنع ذلك من إنهاء النشاط الحالي، وتحصل دالة ردّ الاتصال على فرصة للتفاعل مع إجراء "الرجوع" بعد أن يُكمل المستخدم عملية التنقّل للرجوع في النظام.

3. أزِل تسجيل 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)
              */
           }
       );
     }
   }

4. توقّف عن اعتراض أحداث الرجوع باستخدام OnBackPressed أو KeyEvent.KEYCODE_BACK على الإصدار Android 13 والإصدارات الأحدث.

يمكنك تسجيل OnBackInvokedCallback باستخدام PRIORITY_DEFAULT أو PRIORITY_OVERLAY، وهو ما لا يتوفّر في OnBackPressedCallback المشابهة في AndroidX. قد يكون تسجيل مكالمة تلقائية مع PRIORITY_OVERLAY مفيداً في بعض الحالات.

ينطبق ذلك عند نقل البيانات من onKeyPreIme() ويجب أن يتلقّى الإجراء المُعاد الاتصال به إيماءة الرجوع بدلاً من واجهة IME مفتوحة. تسجِّل تطبيقات IME عمليات تسجيل المكالمات باستخدام PRIORITY_DEFAULT عند فتحها. سجِّل طلب معاودة الاتصال باستخدام PRIORITY_OVERLAY لضمان أن يرسل OnBackInvokedDispatcher إيماءة الرجوع إلى طلب معاودة الاتصال بدلاً من واجهة IME المفتوحة.

إيقاف ميزة "إيماءة إظهار شاشة الرجوع"

للإيقاف، في AndroidManifest.xml، في علامة <application>، اضبط العلامة android:enableOnBackInvokedCallback على false.

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

يؤدي ضبط هذا الخيار على false إلى تنفيذ ما يلي:

• يؤدي هذا الخيار إلى إيقاف الصور المتحركة في النظام لإيماءة الرجوع إلى الخلف التنبؤية.
• يتم تجاهل OnBackInvokedCallback، ولكن تظل مكالمات OnBackPressedCallback تعمل.

إيقاف الإعداد على مستوى نشاط

بدءًا من الإصدار 16 من Android، تتيح لك العلامة 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 لأنّه متوافق مع الإصدارات القديمة ويطلب واجهة برمجة التطبيقات onBackPressed التي لا تتوفّر قبل Android 13.OnBackPressedCallback
• يؤدي ضبط العلامة enableOnBackInvokedCallback على مستوى التطبيق إلى تحديد القيمة التلقائية لجميع الأنشطة في التطبيق. ويمكنك إلغاء القيمة التلقائية لكل نشاط من خلال ضبط العلامة على مستوى النشاط، كما هو موضّح في مثال الرمز البرمجي السابق.

أفضل الممارسات المتعلّقة بميزة "الاتصال مرة أخرى"

في ما يلي أفضل الممارسات لاستخدام طلبات إعادة الاتصال المسموح بها للنظام: BackHandler (لإنشاء الرسائل) أو OnBackPressedCallback أو OnBackInvokedCallback.

تحديد حالة واجهة المستخدم التي تفعّل كل وظيفة استدعاء وتوقِفها

حالة واجهة المستخدم هي سمة تصف واجهة المستخدم. ننصحك باتّباع الخطوات التالية على مستوى عالٍ.

1. تحديد حالة واجهة المستخدم التي تفعّل كلّ طلب إعادة اتصال وتوقِفه

2. حدِّد هذه الحالة باستخدام نوع حامل بيانات قابل للرصد، مثل StateFlow أو Compose State، وفعِّل دالة الاستدعاء أو أوقِفها عند تغيُّر الحالة.

إذا كان تطبيقك يربط منطق الرجوع سابقًا ببيانات شرطية، قد يعني ذلك أنّك تتفاعل مع حدث الرجوع بعد وقوعه. تجنَّب هذا النمط باستخدام طلبات الاستدعاء الأحدث. إذا أمكن، انقل دالة "مكالمة العودة" خارج العبارة الشَرطية وقم بدلاً من ذلك بربط دالة "مكالمة العودة" بنوع حامل بيانات قابل للرصد.

استخدام طلبات الاستدعاء لنظام "الرجوع" في منطق واجهة المستخدم

يحدِّد منطق واجهة المستخدم كيفية عرض واجهة المستخدم. استخدِم عمليات ردّ الاتصال لنظام الرجوع إلى الخلف من أجل تنفيذ منطق واجهة المستخدم، مثل عرض نافذة منبثقة أو تشغيل صورة متحركة.

إذا كان تطبيقك يفعّل طلب استدعاء لنظام الرجوع إلى الخلف، لن يتم تشغيل الصور المتحركة التنبؤية، وعليك معالجة حدث الرجوع. لا تنشئ وظائف استدعاء فقط لتشغيل منطق غير مرتبط بواجهة المستخدم.

على سبيل المثال، إذا كنت تعترض أحداث تسجيل الدخول فقط لتسجيلها، سجِّل الدخول ضمن دورة حياة Activity أو Fragment بدلاً من ذلك.

• بالنسبة إلى حالات النشاط إلى النشاط أو حالات المقتطف إلى النشاط، سجِّل ما إذا كان isFinishing ضمن onDestroy هو true ضمن دورة حياة النشاط.
• بالنسبة إلى الحالات التي تنتقل فيها البيانات من قطعة إلى أخرى، سجِّل ما إذا كان isRemoving ضمن onDestroy هو صحيح ضمن دورة عرض القطعة. أو سجِّل الدخول باستخدام إحدى الطريقتَين onBackStackChangeStarted أو onBackStackChangeCommitted ضمن FragmentManager.OnBackStackChangedListener.

بالنسبة إلى طلب الإنشاء، سجِّل في ردّ الاتصال onCleared() على ViewModel المرتبط بوجهة الإنشاء. هذه هي أفضل إشارة لمعرفة وقت إزالة وجهة إنشاء من الحزمة الخلفية وإزالتها.

إنشاء وظائف استدعاء ذات مسؤولية واحدة

يمكنك إضافة عدة عمليات استدعاء إلى أداة الإرسال. تتم إضافة وظائف الاستدعاء إلى تدرّج يعالج فيه آخر وظيفتَي استدعاء مفعَّلتَين إيماءة الرجوع التالية باستخدام وظيفة استدعاء واحدة لكل إيماءة رجوع.

من الأسهل إدارة حالة تفعيل طلب معاودة الاتصال إذا كان طلب معاودة الاتصال هذا لديه مسؤولية واحدة. مثلاً:

يوضّح الشكل 2 كيفية الحصول على وظائف استدعاء متعددة في الحزمة، وكلّ واحدة منها مسؤولة عن إجراء واحد. لا يتم تشغيل طلب الاستدعاء إلا إذا كانت طلبات الاستدعاء أعلاه في الحزمة غير مفعّلة. في هذا المثال، يتم تفعيل الإجراء المُعاد "هل أنت متأكّد؟" عندما يُدخل المستخدم بيانات في نموذج، ويتم إيقافه في غير ذلك. يفتح طلب إعادة الاتصال مربّع حوار لتأكيد عندما يمرّر المستخدم سريعًا للخلف للخروج من النموذج.

يمكن أن يتضمّن الإجراء المُعاد الاتصال به الآخر مكوّنًا أساسيًا يتوافق مع الترجيع التوقّعي، أو انتقال AndroidX باستخدام واجهات برمجة تطبيقات Progress، أو إجراء مُعاد اتصال به مخصّصًا آخر.

يتمّ تشغيل دالة الاستدعاء لعنصر childFragmentManager إذا كانت دوالّ الاستدعاء أعلاه متوقفة ولم تكن حزمة الرجوع لعنصر FragmentManager هذه فارغة، حيث يتمّ إرفاق childFragmentManager داخل عنصر "الجزء". في هذا المثال، يتم إيقاف ردّ الاتصال الداخلي.

وبالمثل، يتم تشغيل دالة الاستدعاء الداخلية لـ supportFragmentManager إذا كانت دالات الاستدعاء المذكورة أعلاه غير مفعّلة وكانت الحزمة غير فارغة. يكون هذا السلوك متّسقًا عند استخدام FragmentManager أو NavigationComponent للتنقّل، لأنّ NavigationComponent يعتمد على FragmentManager. في هذا المثال، يتم تنفيذ callback هذا إذا لم يُدخِل المستخدم نصًا في النموذج، ما يؤدي إلى إيقاف callback "هل أنت متأكّد؟".

أخيرًا، super.onBackPressed() هو طلب معاودة الاتصال على مستوى النظام، ويتم تشغيله مرة أخرى في حال كانت طلبات معاودة الاتصال أعلاه غير مفعّلة. لتشغيل الصور المتحركة للنظام، مثل الرجوع إلى الشاشة الرئيسية والتنقّل بين الأنشطة والمهام، يجب أن تكون ملفوظة الرجوع في supportFragmentManager فارغة حتى يتم إيقاف طلب الاستدعاء الداخلي.

اختبار الصورة المتحركة لإيماءة الرجوع إلى الخلف التنبؤية

إذا كنت لا تزال تستخدم Android 13 أو Android 14، يمكنك اختبار الميمَج المتحرّك للرجوع إلى الشاشة الرئيسية المعروض في الشكل 1.

لاختبار هذا المشهد المتحرّك، يُرجى إكمال الخطوات التالية:

1. على جهازك، انتقِل إلى الإعدادات > النظام > خيارات المطوّرين.

2. اختَر صور متحركة تعرض إيماءة الرجوع إلى الخلف التنبؤية.

3. افتح تطبيقك المُحدَّث واستخدِم إيماءة الرجوع لتجربة هذه الميزة.