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

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

على سبيل المثال، يمكن أن يؤدي استخدام إيماءة للرجوع إلى عرض معاينة متحركة للشاشة الرئيسية خلف تطبيقك، كما هو موضّح في التصميم التجريبي بالشكل 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 وPlatform API.

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

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

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

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

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

استخدام تطبيقك لنظام AndroidX	كيفية معالجة تطبيقك لميزة التنقّل للخلف	مسار نقل البيانات المقترَح (الرابط في هذه الصفحة)
نعم	واجهات برمجة تطبيقات AndroidX	نقل عملية تنفيذ حالية لـ AndroidX
	واجهات برمجة تطبيقات الأنظمة الأساسية غير المتوافقة	نقل تطبيق AndroidX يحتوي على واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات AndroidX
لا	واجهات برمجة تطبيقات الأنظمة الأساسية غير المتوافقة، والتي يمكن نقلها	نقل بيانات تطبيق يستخدم واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات النظام الأساسي
	واجهات برمجة تطبيقات المنصة غير متوافقة، ولكن يتعذّر نقل البيانات	تأجيل تفعيل الميزة إلى أن تصبح ميزة مطلوبة

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

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

إذا كان تطبيقك يندرج ضمن هذه الفئة، اتّبِع الخطوات التالية لإتاحة استخدام إيماءة الرجوع التوقّعية:

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

2. تفعيل إيماءة إظهار شاشة الرجوع، كما هو موضّح في هذه الصفحة

نقل بيانات تطبيق AndroidX يحتوي على واجهات برمجة تطبيقات غير متوافقة للتنقّل للخلف إلى واجهات برمجة تطبيقات AndroidX

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

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

1. نقل منطق معالجة Back في النظام إلى ‎AndroidX OnBackPressedDispatcher من خلال تنفيذ 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"
   

5. بعد نقل بيانات تطبيقك بنجاح، فعِّل الإيماءة التوقّعية للرجوع (على النحو الموضّح في هذه الصفحة) للاطّلاع على الصورة المتحركة لنظام الرجوع إلى الصفحة الرئيسية.

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

إذا لم يكن بإمكان تطبيقك استخدام مكتبات 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 والإصدارات الأحدث

5. بعد نقل بيانات تطبيقك بنجاح، فعِّل ميزة الإيماءة التوقّعية للرجوع (على النحو الموضّح في هذه الصفحة) لكي يتم تفعيل OnBackInvokedCallback.

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

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

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

بعد تحديد كيفية تحديث تطبيقك استنادًا إلى حالتك، فعِّل ميزة إتاحة إيماءة الرجوع التوقّعية.

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

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

في حال عدم تقديم قيمة، يتم ضبط القيمة التلقائية على false وتنفيذ ما يلي:

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

تفعيل الميزة على مستوى النشاط

بدءًا من Android 14، تتيح لك العلامة android:enableOnBackInvokedCallback تفعيل الرسوم المتحرّكة القائمة على التوقّعات للنظام على مستوى النشاط. يسهّل هذا السلوك نقل التطبيقات الكبيرة التي تتضمّن أنشطة متعددة إلى الإيماءات التوقّعية للرجوع. في Android 15، لم تعُد ميزة "الرجوع التوقّعي" متاحة من خلال خيار المطوّر. يمكن للتطبيقات تفعيل ميزة "الترجيع التوقّعي" بالكامل أو على مستوى النشاط.

يعرض الرمز البرمجي التالي مثالاً على استخدام 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=true على ".SecondActivity" إلى تفعيل الصور المتحركة في النظام على مستوى الأنشطة المختلفة.

يُرجى مراعاة النقاط التالية عند استخدام العلامة android:enableOnBackInvokedCallback:

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