تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

يتوافق نظام التشغيل Android 14 (المستوى 34 من واجهة برمجة التطبيقات) مع الصور المتحركة الإضافية للنظام وواجهات برمجة التطبيقات لإنشاء صور متحركة مخصّصة. لمعرفة مزيد من المعلومات، يُرجى الاطّلاع على مقالة إضافة الصور المتحركة المقترَحة المخصّصة والمدمَجة التنبؤية.

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

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

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

فيديو حول الترميز وفيديو مؤتمر Google I/O

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

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

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

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

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

تحديث تطبيق يستخدم ميزة التنقّل المخصّصة إلى الوراء

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

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

نقل عملية تنفيذ ميزة التنقل للخلف في نظام التشغيل AndroidX

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

إذا كان تطبيقك يندرج ضمن هذه الفئة، اتّبِع الخطوات التالية لإتاحة إيماءة الرجوع بالتوقع:

للتأكّد من أنّ واجهات برمجة التطبيقات التي تستخدم حاليًا واجهات برمجة تطبيقات OnBackPressedDispatcher (مثل الأجزاء ومكوّن التنقل) تعمل بسلاسة مع إيماءة الرجوع التنبؤية، عليك الترقية إلى 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"
```
فعِّل إيماءة الرجوع التنبئي، كما هو موضَّح في هذه الصفحة.

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

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

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

يمكنك نقل منطق المناولة الخاص بالنظام إلى نظام التشغيل AndroidX OnBackPressedDispatcher من خلال تنفيذ OnBackPressedCallback. للحصول على إرشادات تفصيلية، راجِع توفير ميزة التنقّل المخصّصة إلى الخلف.
يمكنك إيقاف ميزة "OnBackPressedCallback" عندما تكون جاهزًا لإيقاف اعتراض إيماءة الرجوع.
أوقِف اعتراض الأحداث العكسية من خلال OnBackPressed أو KeyEvent.KEYCODE_BACK.

احرص على الترقية إلى النشاط على AndroidX 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"

عند إتمام نقل بيانات التطبيق بنجاح، فعِّل إيماءة الرجوع إلى الشاشة السابقة (كما هو موضّح في هذه الصفحة) لرؤية الصور المتحركة للنظام الذي يظهر عند الرجوع إلى المنزل.

ملاحظة: يتم استدعاء OnBackPressedCallback دائمًا بغض النظر عن قيمة android:enableOnBackInvokedCallback. بعبارة أخرى، لن يؤثر إيقاف الحركة في النظام على منطق معالجة الرجوع إلى التطبيق في حال استخدام OnBackPressedCallback.

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

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

أكمِل الخطوات التالية لنقل واجهات برمجة التطبيقات غير المتوافقة إلى واجهة برمجة تطبيقات النظام الأساسي:

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

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

تفعيل إيماءة الرجوع إلى شاشة الساعة

بعد تحديد كيفية تحديث التطبيق بناءً على طلبك، ننصحك بالسماح باستخدام إيماءة الرجوع التنبؤية.

لتفعيل الميزة، اضبط علامة android:enableOnBackInvokedCallback على true في العلامة <application> في AndroidManifest.xml.

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

في حال عدم تقديم قيمة، سيتم ضبط القيمة التلقائية على false وسيتم تنفيذ ما يلي:

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

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

بدءًا من نظام التشغيل Android 14، تتيح لك العلامة 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=true للسمة ".SecondActivity" إلى تفعيل الرسوم المتحركة لنظام تبادُل الأنشطة.

يُرجى مراعاة الاعتبارات التالية عند استخدام علامة android:enableOnBackInvokedCallback:

يؤدي ضبط android:enableOnBackInvokedCallback=false إلى إيقاف الصور المتحركة السابقة التنبؤية، سواء على مستوى النشاط أو على مستوى التطبيق، بناءً على مكان ضبط العلامة، وتوجيه النظام إلى تجاهل طلبات البيانات إلى واجهة برمجة تطبيقات النظام الأساسي OnBackInvokedCallback. ومع ذلك، يستمر تنفيذ الطلبات المتعلّقة بـ OnBackPressedCallback لأنّ OnBackPressedCallback متوافق مع الأنظمة القديمة ويطلب واجهة برمجة التطبيقات onBackPressed غير المتوافقة مع الإصدار Android 13.
يؤدي ضبط العلامة enableOnBackInvokedCallback على مستوى التطبيق إلى إنشاء القيمة التلقائية لجميع الأنشطة في التطبيق. يمكنك إلغاء القيمة التلقائية لكل نشاط من خلال ضبط العلامة على مستوى النشاط، كما هو موضَّح في مثال الرمز السابق.

أفضل ممارسات معاودة الاتصال

في ما يلي أفضل الممارسات لاستخدام عمليات معاودة الاتصال المتوافقة مع النظام: BackHandler (للإنشاء) أو OnBackPressedCallback أو OnBackInvokedCallback.

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

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

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

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

استخدام عمليات معاودة الاتصال في النظام لمنطق واجهة المستخدم

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

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

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

في ما يتعلّق بحالات بدء النشاط أو التحوّل من جزء إلى نشاط، يُرجى تسجيل ما إذا كانت قيمة isFinishing ضمن onDestroy هي true خلال دورة حياة النشاط.
بالنسبة إلى حالات "تقسيم إلى جزء"، سجِّل ما إذا كان isRemoving ضمن onDestroy صحيحًا ضمن دورة حياة عرض الجزء، أو سجِّل باستخدام طريقة onBackStackChangeStarted أو onBackStackChangeCommitted ضمن FragmentManager.OnBackStackChangedListener.

بالنسبة إلى حالة الإنشاء، يمكنك تسجيل الدخول ضمن استدعاء onCleared() لـ ViewModel المرتبط بالوجهة Compose. هذه هي أفضل إشارة لمعرفة متى يتم إخراج وجهة الإنشاء من الحزمة الخلفية وتدميرها.

إنشاء طلبات معاودة الاتصال على مستوى المسؤولية

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

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

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

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

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