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

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

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

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

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

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

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

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

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

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

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

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

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

التأكّد من أنّ واجهات برمجة التطبيقات التي تستخدم حاليًا واجهات OnBackPressedDispatcher API (مثل "أجزاء" و"مكوّن التنقل") بسلاسة مع إيماءة توقُّع رجوع، الترقية إلى النشاط على 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 مع تنفيذ 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 الجديدة على الأجهزة التي تعمل بنظام التشغيل Android 13 أو الإصدارات الأحدث، والاعتماد على واجهات برمجة التطبيقات غير المتوافقة على الأجهزة التي تعمل بنظام التشغيل Android 12 أو أَقَل
سجِّل منطق الرجوع المخصّص في 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، وهو ما لا يتوفّر في OnBackPressedCallback المشابه في AndroidX . تسجيل معاودة الاتصال باستخدام PRIORITY_OVERLAY هو مفيدًا في بعض الحالات. الحالة التي يمكن أن ينطبق فيها ذلك هي عند نقل البيانات من onKeyPreIme()، ويجب أن يتلقّى معاودة الاتصال إيماءة الرجوع بدلاً من ذلك. محرر أسلوب الإدخال (IME) المفتوح. تسجِّل أدوات IME طلبات معاودة الاتصال باستخدام PRIORITY_DEFAULT عند فتحها. تسجيل معاودة الاتصال لدى PRIORITY_OVERLAY للتأكد يرسل OnBackInvokedDispatcher إيماءة الرجوع إلى جهة معاودة الاتصال بدلاً من ذلك. لفتح IME.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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