הוספת תמיכה בתנועת החזרה החזויה

איור 1. הדמיה של העיצוב והסגנון של חיזוי תנועת החזרה בטלפון

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

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

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

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

כדי לתמוך בחיזוי תנועת החזרה, צריך לעדכן את האפליקציה באמצעות OnBackPressedCallback התואם לדורות קודמים ב-AndroidX Activity 1.6.0 או ב-API גבוה יותר, או באמצעות ה-API החדש של פלטפורמת OnBackInvokedCallback. רוב האפליקציות משתמשות ב-AndroidX API שתואם לדורות קודמים.

העדכון הזה מספק נתיב העברה כדי ליירט כראוי את הניווט לאחור, שכולל החלפה של יירוטי החזרה מ-KeyEvent.KEYCODE_BACK ומכל המחלקות עם שיטות onBackPressed כמו Activity ו-Dialog בממשקי ה-API החדשים של המערכת לחזרה.

‫Codelab וסרטון מ-Google I/O

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

אתם יכולים גם לצפות בסרטון שלנו מ-Google I/O, שכולל דוגמאות נוספות להטמעה של AndroidX ושל ממשקי ה-API של הפלטפורמה.

טיפול בתנועות חזרה בהתאמה אישית ב-Compose

ב-Compose יש את ה-composable‏ PredictiveBackHandler לטיפול בתנועות חזרה בהתאמה אישית. ה-API הזה מאפשר להגיב לתנועת החזרה ומספק Flow של אובייקטים מסוג BackEventCompat שאפשר להשתמש בהם כדי להטמיע אנימציות או מעברים בהתאמה אישית כשהמשתמש מחליק.

כדי להשתמש ב-PredictiveBackHandler, צריך לוודא שהאפליקציה כוללת את התלות androidx.activity:activity-compose (גרסה 1.8.0 ואילך):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}


PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}

אם אתם צריכים רק ליירט את תנועת החזרה בלי לעקוב אחרי ההתקדמות, השתמשו ב-BackHandler.

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

התכונה "חיזוי החזרה" מופעלת כברירת מחדל.

אם האפליקציה משתמשת במקטעים (fragments) או ברכיב הניווט, צריך לשדרג גם ל-AndroidX Activity 1.6.0 ואילך.

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

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

איך האפליקציה מטפלת בניווט לאחור תהליך ההעברה המומלץ (קישור בדף הזה)
ממשקי API של AndroidX העברה של הטמעה קיימת של AndroidX back
ממשקי API של פלטפורמות לא נתמכות איך להעביר אפליקציית AndroidX שמכילה ממשקי API לא נתמכים של ניווט לאחור אל ממשקי API של AndroidX

העברת הטמעה של ניווט לאחור ב-AndroidX

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

כדי לוודא שממשקי API שכבר משתמשים ב-OnBackPressedDispatcher (כמו Fragments ו-Navigation Component) פועלים בצורה חלקה עם חיזוי תנועת החזרה, צריך לשדרג ל-AndroidX Activity מגרסה 1.6.0 ואילך.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

איך מעבירים אפליקציית AndroidX שמכילה ממשקי API לא נתמכים של ניווט לאחור אל ממשקי API של AndroidX

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

כדי להעביר ממשקי API לא נתמכים לממשקי AndroidX API:

  1. מעבירים את הלוגיקה של המערכת לטיפול בפעולת החזרה אל OnBackPressedDispatcher של AndroidX באמצעות הטמעה של OnBackPressedCallback. הנחיות מפורטות זמינות במאמר הוספת ניווט לאחור בהתאמה אישית.

  2. כדי להפסיק את ההתערבות בתנועת החזרה, משביתים את OnBackPressedCallback.

  3. מפסיקים ליירט אירועי חזרה באמצעות OnBackPressed או KeyEvent.KEYCODE_BACK.

  4. חשוב לשדרג לגרסה 1.6.0 של AndroidX Activity או לגרסה חדשה יותר.

    ‫
    // In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

ביטול ההסכמה לשימוש בחיזוי החזרה

כדי לבטל את ההסכמה, בקובץ AndroidManifest.xml, בתג <application>, מגדירים את הדגל android:enableOnBackInvokedCallback לערך false.

<application
    ...
    android:enableOnBackInvokedCallback="false"
    ... >
...
</application>

אם מגדירים את המדיניות כ-False:

  • ההגדרה משביתה את אנימציית המערכת של חיזוי תנועת החזרה.
  • המערכת מתעלמת מ-OnBackInvokedCallback, אבל קריאות ל-OnBackPressedCallback ממשיכות לפעול.

ביטול ההסכמה ברמת הפעילות

הדגל 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, חשוב לזכור את הדברים הבאים:

  • ההגדרה android:enableOnBackInvokedCallback=false משביתה את האנימציות של חיזוי החזרה ברמת הפעילות או ברמת האפליקציה, בהתאם למקום שבו מגדירים את התג, ומורה למערכת להתעלם מקריאות ל-API של הפלטפורמה OnBackInvokedCallback. עם זאת, הקריאות ל-OnBackPressedCallback ממשיכות לפעול כי OnBackPressedCallback תואם לדורות קודמים וקורא ל-API‏ onBackPressed, שלא נתמך בגרסאות שקודמות ל-Android 13.
  • הגדרת הדגל enableOnBackInvokedCallback ברמת האפליקציה קובעת את ערך ברירת המחדל לכל הפעילויות באפליקציה. אפשר לשנות את ברירת המחדל לכל פעילות על ידי הגדרת הדגל ברמת הפעילות, כמו שמוצג בדוגמת הקוד שלמעלה.

הנחיות לגבי קריאות חוזרות (callback)

כשמשתמשים בקריאות החוזרות (callback) הנתמכות של המערכת לפעולת החזרה, צריך לפעול לפי ההנחיות הבאות: PredictiveBackHandler או BackHandler (ל-Compose), OnBackPressedCallback או OnBackInvokedCallback.

קביעת מצב ממשק המשתמש שמפעיל ומשבית כל קריאה חוזרת (callback)

מצב ממשק המשתמש הוא מאפיין שמתאר את ממשק המשתמש. מומלץ לפעול לפי השלבים הכלליים הבאים.

  1. קובעים את מצב ממשק המשתמש שמפעיל ומשבית כל קריאה חוזרת (callback).

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

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

שימוש בקריאות חוזרות (callback) של המערכת לחזרה אחורה בשביל לוגיקת ממשק המשתמש

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

אם האפליקציה מפעילה OnBackPressedCallback או OnBackInvokedCallback עם PRIORITY_DEFAULT או PRIORITY_OVERLAY, האנימציות של חיזוי החזרה לא פועלות וצריך לטפל באירוע החזרה. אל תיצרו את הקריאות החוזרות האלה כדי להפעיל לוגיקה עסקית או כדי לתעד ביומן.

אם האפליקציה צריכה להפעיל לוגיקה עסקית או לתעד ביומן כשהמשתמש מחליק אחורה, אפשר להשתמש בגישות הבאות:

  • ב-Compose: מתעדים ביומן בתוך הקריאה החוזרת (callback) של onCleared() של ViewModel שמשויך ליעד של Compose. זה האות הכי טוב כדי לדעת מתי יעד של Compose נשלף ממקבץ הפעילויות הקודמות ונהרס.
  • באנדרואיד 16 ומעלה: לְהִשְׁתַמֵשׁOnBackInvokedCallback עִםPRIORITY_SYSTEM_NAVIGATION_OBSERVER. הפעולה הזו יוצרת קריאה חוזרת (callback) של צופה שלא צורכת את אירוע החזרה. לדוגמה, אתם יכולים לרשום את הקריאה החוזרת הזו כשהמשתמש מחליק חזרה מהפעילות ברמה הבסיסית (יציאה מהאפליקציה) כדי לתעד את אירוע החזרה או להפעיל לוגיקה עסקית, ועדיין לאפשר את הפעלת האנימציה של החזרה למסך הבית.
  • באפליקציות שמבוססות על תצוגה: מתעדים ביומן בתוך קריאות חוזרות (callbacks) של מחזור החיים או של מקבץ פעילויות קודמות (back stack), במקום לצרוך אירועי חזרה:
    • כדי לבדוק אם יש מעברים בין פעילויות, בודקים אם isFinishing הוא true בתוך Activity.onDestroy().
    • במעברים בין מקטעים, צריך לבדוק אם isRemoving הוא true במחזור החיים של התצוגה של המקטע onDestroy(), או להשתמש ב-FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

יצירת קריאות חוזרות (callbacks) עם אחריות אחת

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

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

סדר הקריאות החוזרות (callback) במחסנית ב-Compose.
איור 2. תרשים של מחסנית קריאה חוזרת (callback) בפיתוח נייטיב.

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

  • ההודעה "האם ברצונך..." האפשרות PredictiveBackHandler מופעלת כשהמשתמש מזין נתונים בטופס, ומושבתת במקרים אחרים. כשהתכונה מופעלת, היא מזהה את תנועת החזרה ומציגה תיבת דו-שיח לאישור או אנימציה מותאמת אישית בתוך האפליקציה.
  • הפונקציה BackHandler ברמת המסך פועלת אם פונקציית ה-callback הקודמת מושבתת. בדוגמה הזו, הוא מושבת.
  • הקריאה החוזרת (callback) NavHost מטפלת בניווט לאחור כדי להסיר יעדים ממקבץ הפעילויות הקודמות (back stack) אם הקריאות החוזרות הקודמות בהתאמה אישית מושבתות.
  • לבסוף, המערכת מטפלת בתנועת החזרה אם כל הקריאות החוזרות הקודמות מושבתות. כשהמקבץ פעילויות קודמות (back stack) נמצא ביעד הבסיס, המערכת מפעילה אנימציות ברמת המערכת, כמו חזרה למסך הבית, מעבר בין פעילויות ומעבר בין משימות.

אותה התנהגות של מקבץ חלה על אפליקציות מבוססות-תצוגה: העדיפות ניתנת ל-OnBackPressedCallback האחרון שנוסף והופעל, ואז ל-FragmentManager ובסופו של דבר לטיפול של המערכת בחזרה.

בדיקת האנימציה של חיזוי תנועת החזרה

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

במכשירים עם Android 13 או Android 14, אפשר להפעיל את אפשרות המפתחים כדי לבדוק את האנימציה של החזרה למסך הבית שמוצגת באיור 1:

  1. במכשיר, עוברים אל הגדרות > מערכת > אפשרויות למפתחים.

  2. בוחרים באפשרות אנימציות של חיזוי החזרה.

  3. מפעילים את האפליקציה המעודכנת ומשתמשים בתנועת החזרה כדי לראות אותה בפעולה.