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

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

**الشكل 1.** نموذج محاكاة لشكل ومظهر الإيماءة التنبؤية للرجوع على هاتف

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

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

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

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

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

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

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

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

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

التعامل مع إيماءات الرجوع المخصّصة في Compose

توفّر Compose العنصر القابل للإنشاء PredictiveBackHandler للتعامل مع الإيماءات المخصّصة للرجوع. تتيح لك واجهة برمجة التطبيقات هذه الاستجابة لإيماءة الرجوع وتوفّر Flow من عناصر BackEventCompat التي يمكنك استخدامها لتنفيذ رسوم متحركة أو انتقالات مخصّصة أثناء التمرير السريع للمستخدم.

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress
        }
        // Handle the final back action (e.g., navigate back)
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI
    }
}

إذا كنت بحاجة فقط إلى اعتراض إيماءة الرجوع بدون تتبُّع مستوى التقدّم، استخدِم BackHandler.

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

تكون ميزة "إيماءة إظهار شاشة الرجوع" مفعَّلة تلقائيًا.

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

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

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

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

نقل عملية تنفيذ ميزة التنقّل للخلف في AndroidX

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

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

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

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

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

أفضل الممارسات المتعلقة بوظائف معاودة الاتصال

في ما يلي أفضل الممارسات لاستخدام عمليات معاودة الاتصال المتوافقة مع ميزة "الرجوع إلى الخلف" على مستوى النظام: PredictiveBackHandler أو BackHandler (في Compose)، OnBackPressedCallback أو OnBackInvokedCallback.

تحديد حالة واجهة المستخدم التي تتيح وتوقف كل دالة ردّ نداء

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

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

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

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

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

إذا كان تطبيقك يفعّل OnBackPressedCallback أو OnBackInvokedCallback مع PRIORITY_DEFAULT أو PRIORITY_OVERLAY، لن يتم تشغيل رسوم "إيماءة إظهار شاشة الرجوع"، وعليك التعامل مع حدث الرجوع. لا تنشئ عمليات رد الاتصال هذه لتنفيذ منطق النشاط التجاري أو التسجيل.

استخدِم الطرق التالية إذا كان تطبيقك يحتاج إلى تنفيذ منطق النشاط التجاري أو تسجيل الدخول عند توجيه المستخدم سريعًا للرجوع:

استخدِم OnBackInvokedCallback مع PRIORITY_SYSTEM_NAVIGATION_OBSERVER على الأجهزة التي تعمل بنظام Android 16 والإصدارات الأحدث. يؤدي ذلك إلى إنشاء دالة معاودة الاتصال الخاصة بالمراقب التي لا تستخدم حدث الرجوع. على سبيل المثال، يمكنك تسجيل دالة رد الاتصال هذه عندما ينزلق المستخدم إلى الخلف من النشاط الجذر، أو بعبارة أخرى، عندما يغادر المستخدم تطبيقك. في هذه الحالة، يمكنك تسجيل حدث الرجوع أو تنفيذ منطق نشاط تجاري آخر، وسيستمر تشغيل الرسوم المتحركة للرجوع إلى الشاشة الرئيسية.
بالنسبة إلى حالات النشاط إلى النشاط أو الجزء إلى النشاط، سجِّل ما إذا كان isFinishing ضمن onDestroy هو true ضمن دورة حياة النشاط.
بالنسبة إلى حالات الانتقال من جزء إلى جزء، سجِّل ما إذا كانت isRemoving ضمن onDestroy صحيحة ضمن دورة حياة عرض الجزء. يمكنك أيضًا تسجيل الدخول باستخدام طريقتَي onBackStackChangeStarted أو onBackStackChangeCommitted ضمن FragmentManager.OnBackStackChangedListener.
بالنسبة إلى حالة Compose، سجِّل الدخول ضمن معاودة الاتصال onCleared() الخاصة بـ ViewModel المرتبط بوجهة Compose. هذه هي الإشارة الأفضل لمعرفة متى تتم إزالة وجهة Compose من الخلف وتدميرها.

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

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

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

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

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

يمكن أن تتضمّن دالة معاودة الاتصال الأخرى أحد مكوّنات Material التي تتوافق مع ميزة إيماءة إظهار شاشة الرجوع، أو عملية انتقال AndroidX باستخدام واجهات برمجة التطبيقات Progress، أو دالة معاودة اتصال مخصّصة أخرى.

ينطبق سلوك التجميع نفسه في Compose، إذ تكون الأولوية للعنصر PredictiveBackHandler أو BackHandler الأقرب إلى الداخل.

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

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

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

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

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

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

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