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

**الشكل 1.** تصميم تجريبي لإيماءة "الرجوع التوقّعي" على هاتف

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

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

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

يمكنك اختبار هذه الحركة (كما هو موضّح في قسم لاحق من هذه الصفحة).

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

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

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

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

إيقاف ميزة "الرجوع التوقّعي"

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

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

يؤدي ضبط هذا الخيار على "خطأ" إلى ما يلي:

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

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

تتيح لك العلامة 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، وفعِّل أو أوقِف معاودة الاتصال عند تغيُّر الحالة.

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

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

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

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

إنشاء عمليات ردّ نداء ذات مسؤولية فردية

يمكنك إضافة عدة عمليات ردّ إلى أداة الإرسال. تتم إضافة عمليات معاودة الاتصال إلى حزمة، حيث تعالج عملية معاودة الاتصال الأخيرة المفعَّلة الإيماءة التالية للرجوع مع عملية معاودة اتصال واحدة لكل إيماءة رجوع.

يسهل إدارة حالة التفعيل لدالة معالجة إذا كانت هذه الدالة تتضمّن مسؤولية واحدة. مثلاً:

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

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

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

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

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

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

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

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

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

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