تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

**الشكل 1.** نموذج تجريبي لشكل إيماءة الرجوع القائمة على التوقّعات ومضمونها على الهاتف

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

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

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

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

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

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

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

نقل منطق معالجة Back في النظام إلى ‎AndroidX OnBackPressedDispatcher باستخدام تنفيذ OnBackPressedCallback للحصول على إرشادات مفصّلة، يُرجى الاطّلاع على مقالة توفير ميزة التنقّل للخلف المخصّصة.
أوقِف OnBackPressedCallback عندما تكون مستعدًا لإيقاف اعتراض إشارة الانحناء للخلف.
يمكنك إيقاف اعتراض الأحداث مرة أخرى من خلال OnBackPressed أو KeyEvent.KEYCODE_BACK.

احرص على الترقية إلى 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"

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

ملاحظة: يتم دائمًا استدعاء OnBackPressedCallback بغض النظر عن قيمة android:enableOnBackInvokedCallback. بمعنى آخر، لن يؤثر إيقاف الصور المتحركة للنظام في منطق المعالجة للخلف في تطبيقك إذا كان يستخدم OnBackPressedCallback.

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

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

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

استخدِم واجهة برمجة التطبيقات OnBackInvokedCallback الجديدة على الأجهزة التي تعمل بالإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث، واعتمد على واجهات برمجة التطبيقات غير المتوافقة على الأجهزة التي تعمل بالإصدار 12 من نظام التشغيل Android أو الإصدارات الأقدم.
بإمكانك تسجيل منطقك الخلفي المخصّص في 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 على نظام التشغيل Android 13 والإصدارات الأحدث
بعد نقل بيانات تطبيقك بنجاح، فعِّل ميزة الإيماءة التوقّعية للرجوع (على النحو الموضّح في هذه الصفحة) لكي يتم تفعيل OnBackInvokedCallback.

يمكنك تسجيل OnBackInvokedCallback مع PRIORITY_DEFAULT أو PRIORITY_OVERLAY، وهي غير متاحة على جهاز AndroidX OnBackPressedCallback المشابه. يكون تسجيل معاودة الاتصال باستخدام 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 تعمل.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ترتيب عمليات تسجيل الإحالات الناجحة في حزمة. — **الشكل 2.** مخطّط حِزم معاودة الاتصال

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

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

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

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

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

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

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

لاختبار هذا المقطع المتحرك، أكمِل الخطوات التالية:

على جهازك، انتقِل إلى الإعدادات > النظام > خيارات المطوّرين.
اختَر صور متحركة تعرض إيماءة الرجوع إلى الخلف التنبؤية.
افتح تطبيقك المُحدَّث واستخدِم إيماءة الرجوع لتجربة هذه الميزة.