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

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

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

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

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

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