تحديث تطبيقك لإتاحة إيماءة الرجوع التنبؤية في المستقبل

1. مقدمة

في نظام التشغيل Android 13، أضفنا واجهات برمجة تطبيقات تشكّل الأساس لإتاحة ميزة "إيماءة إظهار شاشة الرجوع" قريبًا.

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

لإتاحة إيماءة إظهار شاشة الرجوع، يضيف نظام التشغيل Android 13 واجهة برمجة التطبيقات الجديدة OnBackInvokedCallback على مستوى النافذة. تحلّ واجهة برمجة التطبيقات هذه محلّ واجهة برمجة التطبيقات KeyEvent.KEYCODE_BACK وجميع فئات النظام الأساسي التي تستخدم OnBackPressed، والتي من المقرر إيقافها نهائيًا وسيتطلب نقلها في إصدار Android الرئيسي التالي بعد الإصدار 13. لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات.

في هذا الدرس التطبيقي حول الترميز، سنعمل على إصلاح جزء من استطلاع يستخدم WebView.

هدف هذا الدرس التطبيقي حول الترميز

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

ما ستنشئه

في هذا الدرس التطبيقي، ستستخدم مكتبات AndroidX API للتعامل مع إيماءات الرجوع في تطبيق Sunflower.

أهداف الدورة التعليمية

• كيفية اعتراض استدعاء on-back في AndroidX
• كيفية إعادة حدث "الرجوع" إلى النظام
• خيارات أخرى للتعامل مع إيماءات الرجوع
• تجربة المستخدم الجديدة التي ستتوفّر في الإصدار 13 من نظام التشغيل Android والإصدارات الأحدث، والتي توفّر تنقلاً أكثر توقعًا باستخدام إيماءة إظهار شاشة الرجوع

المتطلبات

• استوديو Android
• جهاز Android تم تفعيل التنقل بالإيماءات عليه
• (اختياري) Git

2. التخطيط لتوفير إمكانية استخدام إيماءة إظهار شاشة الرجوع

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

استخدام واجهات برمجة تطبيقات AndroidX لتنفيذ هذه الميزة

تم تصميم هذا الدرس التطبيقي حول الترميز للتطبيقات التي تستخدم AndroidX.

ستنفّذ OnBackPressedDispatcher وOnBackPressedCallback لتوفير إمكانية التنقّل للخلف.

خيارات أخرى

لدينا خيارات أخرى للتعامل مع هذه الميزة، وذلك حسب الاحتياجات المختلفة التي قد يتطلّبها تطبيقك:

• بالنسبة إلى التطبيقات التي لا يمكنها استخدام AndroidX: إذا كان هذا ينطبق عليك، لا داعي للقلق. استخدِم فئتَي النظام الأساسي الجديدتَين OnBackInvokedDispatcher وOnBackInvokedCallback اللتين نقدّمهما في Android 13، ما يتيح لك استخدام واجهات برمجة التطبيقات التي تعمل بنظام التحويل المسبق بدون الحاجة إلى AndroidX. لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات.
• بالنسبة إلى التطبيقات التي لا يمكن نقلها مؤقتًا: إذا كنت من بين هؤلاء المستخدمين، لا تقلق، فسنساعدك أيضًا. يمكنك إيقاف ميزة "إيماءة إظهار شاشة الرجوع" إذا لم يكن من الممكن نقل البيانات إلى مكتبات AndroidX أو واجهات برمجة التطبيقات الخاصة بالنظام الأساسي في الوقت الحالي. لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات.

3- قبل البدء

تثبيت "استوديو Android"

ثبِّت استوديو Android وحزمة تطوير البرامج (SDK) لنظام التشغيل Android 13.

الحصول على جهاز

يمكنك استخدام جهاز Android افتراضي أو حقيقي لتشغيل التطبيق الذي تنشئه باستخدام هذا الدرس التطبيقي حول الترميز.

تفعيل "التنقّل بالإيماءات"

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

الحصول على الشفرة‏

يمكنك الحصول على الرمز بإحدى الطرق التالية:

تنزيل ملف ZIP

تنزيل ملف ZIP (بدء)

التنزيل عبر Git

إذا كنت تفضّل تنزيل الرمز باستخدام Git، اتّبِع الخطوات التالية:

1. ثبِّت Git.
2. استنسِخ الفرع starter-code أو main للحصول على التطبيق الخاص بهذا التمرين:

المحطة

// Get starter app.
git clone --branch starter-code \
https://github.com/android/codelab-handling-back-navigation.git

تشغيل التطبيق

أكمِل الخطوات التالية:

1. افتح التطبيق وأنشئه في "استوديو Android".
2. أنشئ جهازًا افتراضيًا جديدًا، واختَر Tiramisu. يمكنك بدلاً من ذلك توصيل جهاز فعلي يعمل بالمستوى 33 أو مستوى أحدث من واجهة برمجة التطبيقات.
3. شغِّل تطبيق Sunflower.

بعد ذلك، ستحدّد المتوقع وتوضّح تجربة سيئة ضمن تطبيق Sunflower.

4. تحديد مقياس أساسي

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

استكشاف العرض التوضيحي

بدءًا من الشاشة الرئيسية، لنستعرض سير العمل الرئيسي لتطبيقك من أجل مراجعة التجربة السيئة باستخدام وظيفة WebView.

1. في الشاشة التلقائية لتطبيق Sunflower، انقر على قائمة النباتات.

2. في قائمة النباتات، انقر على أي نبات. (في هذا المثال، سنستخدم فاكهة الأفوكادو).

3. في شاشة المعلومات الخاصة بالنبات الذي نقرت عليه، انقر على رمز الإعجاب (في أعلى يسار الشاشة) لتقييم النبات.

4. ابدأ بملء الاستطلاع، ولكن توقّف عند السؤال رقم 3.

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

لنبدأ الآن في حلّ هذه المشاكل.

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

يستخدم تطبيقنا AndroidX، لذا ستستخدم واجهات برمجة التطبيقات الخاصة بالتنقل للخلف. تتوافق هذه اللغات حاليًا مع نموذج "الترجمة المسبقة".

استهداف Android 13

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

build.gradle (المشروع)

buildscript {
   ext {
       // Sdk and tools
       minSdkVersion = 29
       compileSdkVersion = 33
       targetSdkVersion = 33
   }
...
}

ترقية العناصر التابعة

في ملف build.gradle، اضبط appCompatVersion على 1.6.0 أو إصدار أحدث.

build.gradle (المشروع)

buildscript {
   ext {

    // App dependencies
    appCompatVersion = '1.6.0-rc01' // Built original with changes

...
}

يمكنك الترقية إلى الإصدار 1.6.0 من AndroidX Activity أو إصدار أحدث.

build.gradle (الوحدة)

dependencies {
    implementation "androidx.activity:activity-ktx:1.6.0"
    ...
}

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

لتفعيل واجهات برمجة التطبيقات الخاصة بإيماءة إظهار شاشة الرجوع، اضبط قيمة enableOnBackInvokedCallback على true في ملف البيان.

AndroidManifest.xml

<application
   ...
   android:enableOnBackInvokedCallback="true" // Enables this feature.
   ... >
...
</application>

تعريف OnBackPressedCallback وتسجيله للتعامل مع إيماءات الرجوع

أنشئ رد الاتصال وألغِ طريقة handleOnBackPressed للتعامل مع إيماءات الرجوع. بالنسبة إلى حالة استخدام WebView، لنستخدِم إيماءة "الرجوع" للرجوع في حزمة الصفحات إلى أن لا تتبقّى أي صفحات.

SurveyFragment.kt

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
...
  val onBackPressedCallback = object: OnBackPressedCallback(true) {
    override fun handleOnBackPressed() {
      when {
        webView.canGoBack() -> webView.goBack()
      }
    }
  }
  requireActivity().onBackPressedDispatcher
    .addCallback(onBackPressedCallback)
}

تجربة ما أنشأته

الآن، ستختبر ما إذا كان التنقّل في WebView يعمل بشكل سليم.

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

هذا هو السلوك المطلوب تمامًا. مع ذلك، لم يتم حلّ المشكلة بالكامل بعد. لنواصل توضيح ما نعنيه:

4. من السؤال رقم 2، مرِّر سريعًا للرجوع إلى السؤال رقم 1، ثم مرِّر سريعًا مرة أخرى في محاولة للرجوع إلى جزء تفاصيل النبتة.

لاحظ أنّه لا يمكنك الرجوع من السؤال رقم 1 إلى جزء تفاصيل النبتة. ويرجع ذلك إلى ما يلي:

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

6. إصلاح إيماءة الرجوع

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

تفعيل التنقّل للخلف باستخدام OnBackPressedCallback أو إيقافه

1. يمكنك إلغاء طريقة doUpdateVisitedHistory لتحديد ما إذا كان يجب اعتراض التنقّل للخلف. في ما يلي منطق التعامل مع التنقّل إلى الخلف:
   • إذا كان هناك المزيد من الصفحات التي يمكن الرجوع إليها في WebView (webView.canGoBack())، يجب تفعيل طريقة OnBackPressedCallback.
   • في المقابل، إذا لم تكن هناك صفحات أخرى للرجوع إليها في WebView، يجب إيقاف الطريقة OnBackPressedCallback. نتيجةً لذلك، ستؤدي إيماءة الرجوع إلى الرجوع إلى الجزء العلوي في سجلّ الأنشطة السابقة.

SurveyFragment.kt

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
  ...
  requireActivity().onBackPressedDispatcher
    .addCallback(onBackPressedCallback)

  disableOnBackPressedCallback(webView, onBackPressedCallback)
  }
}

private fun disableOnBackPressedCallback(webView: WebView, onBackPressedCallback: OnBackPressedCallback) {
  webView.webViewClient = object: WebViewClient() {
    override fun doUpdateVisitedHistory(view: WebView?, url: String?, isReload: Boolean) {
      // Disable the on-back press callback if there are no more questions in the
      // WebView to go back to, allowing us to exit the WebView and go back to
      // the fragment.
      onBackPressedCallback.isEnabled = webView.canGoBack()

    }
  }
}

2. لاختبار WebView مرة أخرى، املأ الاستطلاع مرة أخرى إلى أن تصل إلى السؤال رقم 3.
3. باستخدام إيماءات الرجوع، انتقِل إلى عرض تفاصيل النبتة. من المفترض أن تتمكّن من إجراء ذلك بدون أي مشكلة.

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

في ما يلي مثال على الشكل الذي يجب أن يظهر به كل ذلك بعد إصلاحه:

معاينة الصورة المتحركة الجديدة لإيماءة الرجوع إلى الشاشة الرئيسية

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

يمكنك معاينة التنقّل الجديد بالإيماءات للرجوع إلى الشاشة الرئيسية عن طريق تفعيل خيار المطوّرين.

7. تهانينا

تهانينا! لقد تناولنا الكثير من المحتوى. نأمل أن تكون قد فهمت بشكل أفضل الخيارات وواجهات برمجة التطبيقات اللازمة لبدء تعديل تطبيقك ليتوافق مع ميزة "إيماءة إظهار شاشة الرجوع" المتوفّرة في Android.

المواضيع التي تناولناها

• كيفية تفعيل تطبيقك لبدء استخدام واجهات برمجة التطبيقات التي تتيح استخدام إيماءة إظهار شاشة الرجوع
• كيفية اعتراض استدعاء زر الرجوع في AndroidX
• كيفية إعادة زر الرجوع إلى النظام
• خيارات أخرى للتعامل مع إيماءات الرجوع
• تجربة المستخدم الجديدة التي ستتوفّر في Android 13، والتي توفّر إيماءة إظهار شاشة الرجوع

الدرس التطبيقي حول الترميز المكتمل

تنزيل ملف zip (مكتمل)

// Get completed app.
git clone --branch main \
https://github.com/android/codelab-handling-back-navigation.git

مواد إضافية

• دليل المطوّر

المستندات المرجعية

• OnBackPressedDispatcher وOnBackPressedCallback
• OnBackInvokedDispatcher وOnBackInvokedCallback