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

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

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

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

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

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

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

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

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

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

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

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

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 או ב-Navigation Component, צריך לשדרג גם ל-AndroidX Activity 1.6.0-alpha05 או לגרסה מתקדמת יותר.

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

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

העברה של הטמעה של ניווט לדף הקודם ב-AndroidX

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

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

```xml
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```

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

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

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

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

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

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

4. חשוב לשדרג לגרסה 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"
   

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

כדי לבטל את ההסכמה, בתג <application> ב-AndroidManifest.xml, מגדירים את הדגל 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

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

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

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

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

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

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

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

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

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

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

• אפשר להשתמש ב-OnBackInvokedCallback עם PRIORITY_SYSTEM_NAVIGATION_OBSERVER במכשירים עם Android מגרסה 16 ואילך. הפעולה הזו יוצרת observer-callback שלא צורך את אירוע החזרה. לדוגמה, אפשר לרשום את הקריאה החוזרת הזו כשמשתמש מחליק אחורה מהפעילות הבסיסית, או במילים אחרות, כשהמשתמש יוצא מהאפליקציה. במקרה כזה, אפשר לרשום ביומן את אירוע החזרה או להפעיל לוגיקה עסקית אחרת, והאנימציה של החזרה למסך הבית עדיין תפעל.
• במקרים של פעילות לפעילות או של קטע לפעילות, מתבצעת רישום ביומן אם isFinishing בתוך onDestroy הוא true בתוך מחזור החיים של הפעילות.
• במקרים של מעבר ממקטע למקטע, מתבצע רישום ביומן אם isRemoving בתוך onDestroy הוא true במחזור החיים של התצוגה של המקטע. אפשר גם להתחבר באמצעות השיטות onBackStackChangeStarted או onBackStackChangeCommitted בתוך FragmentManager.OnBackStackChangedListener.
• במקרה של יצירת הודעה, צריך לבצע רישום ביומן בתוך הקריאה החוזרת (callback) onCleared() של ViewModel שמשויך ליעד של יצירת ההודעה. זהו האות הכי טוב לדעת מתי יעד של Compose מוצא מהמחסנית האחורית ונהרס.

יצירת קריאות חוזרות עם אחריות יחידה

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

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

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

הקריאה החוזרת השנייה יכולה לכלול רכיב Material שתומך בחזרה עם חיזוי, מעבר של AndroidX באמצעות Progress APIs או קריאה חוזרת מותאמת אישית אחרת.

אותו עיקרון של מחסנית חל ב-Compose: לרכיב הפנימי ביותר PredictiveBackHandler או BackHandler יש עדיפות.

באופן דומה, הקריאה החוזרת של childFragmentManager מופעלת אם הקריאות החוזרות שלמעלה מושבתות ומקבץ הפעילויות הקודמות (back stack) של FragmentManager הזו לא ריק. בדוגמה הזו, הקריאה החוזרת הפנימית הזו מושבתת.

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

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

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

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

כדי לבדוק את האנימציה הזו, מבצעים את השלבים הבאים:

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

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

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