צריך לעדכן את האפליקציה כדי לתמוך בתנועת חזרה חזויה

1. מבוא

ב-Android 13, הוספנו ממשקי API שמשמשים כבסיס לתמיכה עתידית בתנועת חזרה אינטואיטיבית.

התכונה הזו מאפשרת למשתמשים לצפות בתצוגה מקדימה של התוצאה של תנועת החזרה לפני שהם משלימים אותה. כך הם יכולים להחליט אם להישאר בתצוגה הנוכחית או להשלים את הפעולה ולחזור למסך הבית, לפעילות קודמת או לדף שבו הם ביקרו קודם ב-WebView. דוגמה למראה של כרטיס כזה:

כדי לתמוך בחיזוי תנועת החזרה, ב-Android 13 נוסף ממשק ה-API החדש OnBackInvokedCallback ברמת החלון. ה-API הזה מחליף את KeyEvent.KEYCODE_BACK API ואת כל מחלקות הפלטפורמה שמשתמשות ב-OnBackPressed, שצפויות לצאת משימוש ותידרש העברה בגרסה הגדולה הבאה של Android אחרי גרסה 13. פרטים נוספים זמינים במסמכים שלנו.

במקרה של ה-codelab הזה, נתקן קטע של סקר שמטמיע WebView.

מטרת ה-Codelab הזה

ב-Codelab הזה תלמדו איך להכין אפליקציית AndroidX שחוסמת את פעולת המערכת 'חזרה' על ידי העברה שלה לתמיכה בחיזוי תנועת החזרה באמצעות WebView, בעזרת ממשקי ה-API שמטמיעים את מודל הניווט אחורה מראש. במילים אחרות, כדי שהאנימציות החדשות יפעלו, המערכת צריכה לדעת מראש אם האפליקציה מיירטת את תנועת הניווט אחורה.

מה תפַתחו

ב-codelab הזה תשתמשו בספריות AndroidX API כדי לטפל בתנועות חזרה באפליקציית Sunflower.

מה תלמדו

• איך מיירטים את הקריאה של on-back ב-AndroidX
• איך מחזירים את אירוע החזרה למערכת
• אפשרויות אחרות לטיפול במחוות חזרה
• חוויית המשתמש החדשה שתגיע עם Android 13 ומעלה, עם ניווט באמצעות חיזוי תנועת החזרה

הדרישות

• Android Studio
• מכשיר Android שמופעל בו ניווט באמצעות תנועות
• (אופציונלי) Git

2. תכנון תמיכה בחיזוי תנועת החזרה

חיזוי תנועת החזרה נתמך אוטומטית באפליקציות שמשתמשות בניווט חזרה שמוגדר כברירת מחדל. כדי להפעיל את התכונה, צריך רק להצטרף לניסוי enableOnBackInvokedCallback, כמו שמוסבר במאמר הפעלת חיזוי תנועת החזרה.

כדי להטמיע את התכונה הזו, צריך להשתמש בממשקי AndroidX API

ה-Codelab הזה מיועד לאפליקציות שכבר משתמשות ב-AndroidX.

תטמיעו את OnBackPressedDispatcher ואת OnBackPressedCallback כדי לתמוך בניווט אחורה.

אפשרויות אחרות

יש לנו אפשרויות אחרות לטיפול בתכונה הזו, בהתאם לצרכים השונים של האפליקציה שלך:

• לגבי אפליקציות שלא יכולות להשתמש ב-AndroidX – אם זה המקרה שלכם, אנחנו כאן כדי לעזור. אפשר להשתמש במחלקות הפלטפורמה החדשות OnBackInvokedDispatcher ו-OnBackInvokedCallback שאנחנו משיקים ב-Android 13, שמאפשרות לכם להשתמש בממשקי ה-API של ahead-of-time בלי לדרוש AndroidX. פרטים נוספים זמינים במסמכי התיעוד.
• לגבי אפליקציות שלא ניתן להעביר באופן זמני – אם זה המקרה שלך, אנחנו כאן כדי לעזור לך! אם בשלב הזה אי אפשר לבצע מיגרציה לספריות AndroidX או לממשקי ה-API של הפלטפורמה, אפשר לבטל את ההסכמה לשימוש בתנועת החזרה החזויה. פרטים נוספים זמינים במסמכי התיעוד.

3. לפני שמתחילים

התקנה של Android Studio

מתקינים את Android Studio ואת Android 13 SDK.

קבלת מכשיר

אתם יכולים להשתמש במכשיר Android וירטואלי או פיזי כדי להריץ את האפליקציה שתיצרו באמצעות ה-codelab הזה.

הפעלת ניווט באמצעות תנועות

אם מריצים מופע חדש של אמולטור עם רמת API‏ 29, יכול להיות שהניווט באמצעות מחוות לא יופעל כברירת מחדל. כדי להפעיל ניווט באמצעות תנועות, בוחרים באפשרות הגדרות המערכת > מערכת > ניווט במערכת > ניווט באמצעות תנועות.

קבל את הקוד

אפשר לקבל את הקוד באחת מהדרכים הבאות:

הורדת קובץ ה-ZIP

הורדת קובץ ה-ZIP (התחלה)

הורדה באמצעות Git

אם אתם מעדיפים להוריד את הקוד באמצעות Git, אתם יכולים לפעול לפי השלבים הבאים:

1. מתקינים את Git.
2. משכפלים את הענף starter-code או main כדי לקבל את האפליקציה לתרגיל הזה:

Terminal

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

הפעלת האפליקציה

כך עושים את זה:

1. פותחים את האפליקציה ב-Android Studio ובוחרים באפשרות לבנייה.
2. יוצרים מכשיר וירטואלי חדש ובוחרים באפשרות Tiramisu. אפשר גם לחבר מכשיר פיזי עם API ברמה 33 ומעלה.
3. מפעילים את אפליקציית Sunflower.

לאחר מכן תגדירו נקודת התחלה ותעברו על חוויית שימוש לא טובה שמוצגת באפליקציית Sunflower.

4. הגדרת ערך בסיס

נקודת ההתחלה שלנו היא אפליקציית Sunflower, שכוללת סקר שמוצג ב-WebView ומטפל בצורה לא טובה במחוות חזרה. כשמשתמש מחליק מהקצה השמאלי או הימני כדי לחזור ב-WebView, האפליקציה מחזירה אותו לחלק הקודם במקום לחזור לדף הקודם, וכך הוא מאבד את כל הנתונים שלא נשלחו.

צפייה בהדגמה

נתחיל מהמסך הראשי ונעבור על תהליך העבודה העיקרי של האפליקציה כדי לבדוק את חוויית השימוש הלקויה בפונקציונליות של WebView.

1. במסך ברירת המחדל של אפליקציית Sunflower, מקישים על PLANT LIST (רשימת הצמחים).

2. בקטלוג הצמחים, מקישים על צמח כלשהו. (בדוגמה הזו נשתמש בפרי אבוקדו).

3. במסך המידע של הצמח שלחצתם עליו, לוחצים על סמל הלייק (בפינה השמאלית העליונה) כדי לדרג את הצמח.

4. מתחילים למלא את הסקר, אבל מפסיקים כשמגיעים לשאלה מספר 3.

5. כדי להשתמש בתנועת החזרה, מחליקים פנימה מהקצה השמאלי (או הימני) של המסך. שימו לב: במקום להעביר אתכם לשאלה מספר 2 בסקר, החלקה ימינה תחזיר אתכם לקטע הפרטים של הצמח (בדוגמה הזו, לדף המידע על האבוקדו). כתוצאה מכך, התשובות שלכם יימחקו וחוויית המשתמש תהיה גרועה.

עכשיו נתחיל לפתור את הבעיות האלה.

5. הפעלת חיזוי תנועת החזרה

האפליקציה שלנו כבר משתמשת ב-AndroidX, ולכן תשתמשו בממשקי ה-API של הניווט אחורה. הם כבר תומכים במודל ahead-of-time.

טירגוט ל-Android 13

בפרויקט Studio של האפליקציה, מעדכנים את תצורת ה-build של האפליקציה כך שתכוון ל-Android 13, כמו שמוצג בקטע הקוד הבא.

‫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

...
}

שדרוג ל-AndroidX Activity 1.6.0 ומעלה.

‫build.gradle (מודול)

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

הפעלת חיזוי תנועת החזרה

כדי להפעיל את ממשקי ה-API של חיזוי תנועת החזרה, מגדירים את 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 Studio, בונים ומריצים את האפליקציה שוב.
2. כמו שעשיתם כשצפיתם בהדגמה בפעם הראשונה, מקישים על הצמח הרצוי ואז על סמל הלייק, וממלאים את הסקר עד שמגיעים לשאלה מספר 3.
3. כדי להשתמש בתנועת החזרה, מחליקים פנימה מהקצה השמאלי (או הימני) של המסך. ה-WebView אמור להחזיר אתכם לשאלה מספר 2 בסקר.

זו בדיוק ההתנהגות שאנחנו רוצים. עם זאת, אנחנו רק באמצע הדרך – הבעיה עדיין לא נפתרה לגמרי. כדי להבין למה הכוונה, נמשיך עם הדוגמה:

4. מהשאלה השנייה, מחליקים אחורה לשאלה הראשונה, ואז מחליקים אחורה פעם נוספת כדי לנסות לחזור לקטע עם פרטי הצמח.

שימו לב שאי אפשר לחזור משאלה מספר 1 לקטע של פרטי הצמח. הסיבות לכך הן:

• רכיב ה-WebView מטפל בניווט אחורה על ידי מניעת יציאה מ-WebView כשמשתמשים בניווט אחורה.
• האפליקציה צריכה להחזיר את הניווט אחורה למערכת ברגע שהיא לא צריכה אותו יותר. בואו נעבור לקטע הבא כדי לפתור את הבעיה.

6. תיקון התנועה לחזרה אחורה

בשלב הקודם, האפליקציה שלנו חסמה את תנועת החזרה בלי להחזיר אותה לקטע הפרטים של הצמח בשלבים הקודמים. כתוצאה מכך, המשתמשים שלנו לא יכולים לצאת מהאפליקציה ונתקעים ב-WebView עם חוויית משתמש גרועה.

הפעלה או השבתה של ניווט אחורה באמצעות OnBackPressedCallback

1. מחליפים את השיטה doUpdateVisitedHistory כדי לקבוע אם צריך ליירט את הניווט אחורה. הלוגיקה לטיפול בניווט חזרה היא כדלקמן:
   • אם יש עוד דפים שאפשר לחזור אליהם ב-WebView (webView.canGoBack()), צריך להפעיל את השיטה OnBackPressedCallback.
   • לעומת זאת, אם אין יותר דפים שאפשר לחזור אליהם בתצוגת האינטרנט, צריך להשבית את השיטה OnBackPressedCallback. כתוצאה מכך, מחוות החזרה אחורה תחזיר אתכם אל המקטע (fragment) העליון ביותר במקבץ הפעילויות הקודמות (back stack).

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. מזל טוב

מעולה! התייחסת להרבה תוכן. אנחנו מקווים שהבנתם טוב יותר את האפשרויות ואת ממשקי ה-API שזמינים לכם כדי להתחיל לעדכן את האפליקציה שלכם כך שתתמוך בתכונה 'חיזוי תנועת החזרה' שזמינה ב-Android.

מה נכלל

• איך מאפשרים לאפליקציה להתחיל להשתמש בממשקי ה-API שתומכים בתנועת החזרה החזויה
• איך מיירטים קריאה להפעלה של לחצן החזרה ב-AndroidX
• איך מחזירים את הניווט אחורה למערכת
• אפשרויות אחרות לטיפול בתנועות חזרה
• חוויית המשתמש החדשה שתגיע ב-Android 13, עם חיזוי תנועת החזרה

השלמת Codelab

הורדת קובץ ה-ZIP (הושלם)

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

חומרים נוספים

• מדריך למפתחים

מסמכי עזר

• ‫OnBackPressedDispatcher ו-OnBackPressedCallback
• ‫OnBackInvokedDispatcher ו- OnBackInvokedCallback