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

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

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

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

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

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

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

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

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

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

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

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

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

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

إذا كان تطبيقك يستخدم سلوكًا مخصّصًا للرجوع، فهناك مسارات نقل مختلفة حسب ما إذا كان يستخدم 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. يمكنك نقل منطق معالجة زر الرجوع في النظام إلى AndroidX OnBackPressedDispatcher من خلال تنفيذ 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"
   }
   

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

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

إرشادات معاودة الاتصال

اتّبِع الإرشادات التالية عند استخدام عمليات الاستدعاء المتوافقة مع النظام للرجوع: 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. يؤدي ذلك إلى إنشاء دالة استدعاء للمراقب لا تستهلك حدث الرجوع. على سبيل المثال، يمكنك تسجيل عملية الاستدعاء هذه عندما يمرّر المستخدم سريعًا للخلف من النشاط الجذر (مغادرة تطبيقك) لتسجيل حدث الرجوع أو تشغيل منطق النشاط التجاري مع السماح بتشغيل تأثير الرجوع إلى الشاشة الرئيسية.
• في التطبيقات المستندة إلى View: يمكنك تسجيل الأحداث ضمن عمليات الاستدعاء لمراحل النشاط أو الأنشطة السابقة بدلاً من استخدام أحداث الرجوع:
  • بالنسبة إلى انتقالات النشاط، تحقَّق مما إذا كان isFinishing هو true خلال Activity.onDestroy().
  • بالنسبة إلى عمليات الانتقال بين الأجزاء، تحقَّق مما إذا كان isRemoving هو true ضمن مراحل النشاط onDestroy() لعرض الجزء، أو استخدِم FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

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

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

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

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

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

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

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

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

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

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

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

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