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