تمت ترجمة هذه الصفحة بواسطة 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 الخاصة بالنظام الجديد.

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

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

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

تحديث تطبيق يستخدم ميزة الرجوع إلى الصفحة التلقائية

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

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

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

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

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

نقل بيانات تنفيذ التنقّل الخلفي على AndroidX

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

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

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

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

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

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

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

تفعيل إيماءة الرجوع التنبؤية

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

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

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

في حال عدم إدخال قيمة، سيتم ضبطها تلقائيًا على false وسيتم إجراء ما يلي:

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

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

بدءًا من الإصدار 14 من نظام التشغيل Android، تتيح لك علامة 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 Platform API. ويستمر تنفيذ الطلبات إلى OnBackPressedCallback لأنّ "OnBackPressedCallback" متوافق مع الأنظمة القديمة ويطلب واجهة برمجة التطبيقات onBackPressed، وهي غير متاحة قبل الإصدار Android 13.
يؤدي ضبط علامة enableOnBackInvokedCallback على مستوى التطبيق إلى تحديد القيمة التلقائية لجميع الأنشطة في التطبيق. ويمكنك إلغاء العلامة التلقائية لكل نشاط من خلال ضبطها على مستوى النشاط كما هو موضّح في مثال الرمز السابق.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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