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

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

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

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

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

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

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

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

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

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

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

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

لاستخدام PredictiveBackHandler، تأكَّد من أنّ تطبيقك يتضمّن الاعتمادية androidx.activity:activity-compose (الإصدار 1.8.0 أو إصدار أحدث):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

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.
    }
}
PredictiveBackSnippets.kt

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

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

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

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

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

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

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

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

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

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

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

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

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

1. انقل منطق معالجة زر الرجوع في نظامك إلى OnBackPressedDispatcher في AndroidX مع تنفيذ OnBackPressedCallback. للحصول على إرشادات مفصّلة، يُرجى الاطّلاع على توفير التنقّل للخلف المخصّص.

2. أوقِف OnBackPressedCallback عندما تكون مستعدًا لإيقاف اعتراض إيماءة الرجوع.

3. توقَّف عن اعتراض أحداث الرجوع باستخدام OnBackPressed أو KeyEvent.KEYCODE_BACK.

4. احرص على الترقية إلى الإصدار 1.6.0 من AndroidX Activity أو إصدار أحدث.

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

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

لإيقاف هذه الميزة، اضبط العلامة 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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