تمت ترجمة هذه الصفحة بواسطة 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 والنظام الأساسي.

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

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

إذا كان تطبيقك يستخدم "المقاطع" أو "مكوّن التنقّل"، عليك أيضًا الترقية إلى 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:

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

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

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

تفعيل إيماءة الرجوع التنبؤية

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

لتفعيل الميزة، في AndroidManifest.xml، اضبط العلامة android:enableOnBackInvokedCallback على true في العلامة <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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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