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

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

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

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

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

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

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

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

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

يمكنك أيضًا مشاهدة فيديو 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.

تعديل تطبيق يستخدم التنقّل التلقائي للرجوع

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

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

تعديل تطبيق يستخدم التنقّل المخصّص للرجوع

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

نقل تنفيذ التنقّل للرجوع في AndroidX

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

للتأكّد من أنّ واجهات برمجة التطبيقات التي تستخدم حاليًا OnBackPressedDispatcher (مثل الفئات `Fragments` ومكوّن التنقّل) تعمل بسلاسة مع إيماءة إظهار شاشة الرجوع، عليك الترقية إلى AndroidX Activity 1.6.0-alpha05.

```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:

1. انقل منطق معالجة الرجوع في النظام إلى AndroidX’s 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"
   

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

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

<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.

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

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

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

2. حدِّد هذه الحالة باستخدام نوع حامل بيانات قابل للملاحظة، مثل 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 كيف يمكنك استخدام عمليات إعادة استدعاء متعددة في الحزمة، كل منها مسؤول عن إجراء واحد. لا يتم تشغيل عملية إعادة الاستدعاء إلا إذا كانت عمليات إعادة الاستدعاء أعلاه في الحزمة غير مفعّلة. في هذا المثال، يتم تفعيل عملية إعادة الاستدعاء "هل أنت متأكد..." عندما يُدخِل المستخدم بيانات في نموذج، ويتم إيقافها بخلاف ذلك. تفتح عملية إعادة الاستدعاء مربّع حوار تأكيد عندما يسحب المستخدم للرجوع لمغادرة النموذج.

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

ينطبق سلوك الحزمة نفسه في Compose: تكون الأولوية لـ PredictiveBackHandler أو BackHandler الأقرب.

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

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

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

اختبار الصورة المتحركة التي تعرض إيماءة إظهار شاشة الرجوع

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

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

1. على جهازك، انتقِل إلى الإعدادات > النظام > خيارات المطوّرين.

2. اختَر صور متحركة تعرض إيماءة إظهار شاشة الرجوع.

3. شغِّل تطبيقك المعدَّل واستخدِم إيماءة الرجوع لمشاهدة الصورة المتحركة أثناء العمل.