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

איור 1. Mockup של המראה והתחושה של התנועה החזרה החזוי בטלפון

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. כדי לוודא שממשקי API שכבר משתמשים בממשקי API מסוג 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"

  2. מאשרים את השימוש בתכונה 'חיזוי תנועת החזרה', כפי שמתואר בדף הזה.

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

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

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

  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"

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

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

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

כדי להעביר ממשקי API שלא נתמכים ל-API של הפלטפורמה:

  1. משתמשים ב-API החדש OnBackInvokedCallback במכשירים עם Android מגרסה 13 ואילך, ומשתמשים בממשקי ה-API ללא תמיכה במכשירים עם Android מגרסה 12 ומטה.

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

  3. כשרוצים להפסיק ליירט את תנועת החזרה, מבטלים את הרישום של 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)
           */
        }
    );
  }
}

  4. הפסקת ניתוב אירועי Back דרך OnBackPressed או KeyEvent.KEYCODE_BACK ב-Android 13 ואילך.

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

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

המצב הזה רלוונטי כשעוברים מ-onKeyPreIme() והקריאה החוזרת צריכה לקבל את תנועת החזרה אחורה במקום IME פתוח. כשמפתחים IME, הוא רושם קריאות חזרה (callbacks) עם PRIORITY_DEFAULT. כדי לוודא ש-OnBackInvokedDispatcher יפנה את תנועת החזרה לאחור לשיחה החוזרת במקום ל-IME הפתוח, צריך לרשום את השיחה החוזרת ב-PRIORITY_OVERLAY.

הבעת הסכמה לשימוש בתכונה 'חיזוי תנועת החזרה'

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

כדי להביע הסכמה, מגדירים את הדגל android:enableOnBackInvokedCallback לערך true בתג <application> ב-AndroidManifest.xml.

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

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

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

הצטרפות ברמת הפעילות

החל מגרסה 14 של Android, הדגל android:enableOnBackInvokedCallback מאפשר לכם להביע הסכמה לשימוש באנימציות מערכת חזויות ברמת הפעילות. בזכות ההתנהגות הזו, קל יותר להעביר אפליקציות גדולות עם הרבה פעילויות לתנועות חיזוי החזרה. בגרסה 15 של Android, האפשרות 'חזרה חזותית' כבר לא נמצאת באפשרויות למפתחים. אפליקציות יכולות להביע הסכמה לחיזוי מלא או ברמת הפעילות.

הקוד הבא מציג דוגמה לשימוש ב-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 משביתה את האנימציות החזרה החזויות ברמת הפעילות או ברמת האפליקציה, בהתאם למיקום שבו מגדירים את התג, ומורה למערכת להתעלם מקריאות ל-API של פלטפורמת OnBackInvokedCallback. עם זאת, הקריאות ל-OnBackPressedCallback ממשיכות לפעול כי OnBackPressedCallback תואם לאחור וקורא ל-API‏ onBackPressed, שאין תמיכה בו לפני Android 13.
  • הגדרת הדגל enableOnBackInvokedCallback ברמת האפליקציה קובעת את ערך ברירת המחדל לכל הפעילויות באפליקציה. אפשר לשנות את ברירת המחדל לכל פעילות בנפרד על ידי הגדרת הדגל ברמת הפעילות, כפי שמתואר בדוגמת הקוד שלמעלה.

שיטות מומלצות לשיחות חוזרות

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

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

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

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

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

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

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

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

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

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

  • במקרים של פעילות לפעילות או מקרים של קטע לפעילות, מתעדים אם isFinishing בתוך onDestroy הוא true במחזור החיים של הפעילות.
  • במקרים של אירועים מ-fragment ל-fragment, מתעדים אם הערך של isRemoving ב-onDestroy הוא true במהלך מחזור החיים של תצוגת ה-Fragment. לחלופין, אפשר להשתמש בשיטות onBackStackChangeStarted או onBackStackChangeCommitted בתוך FragmentManager.OnBackStackChangedListener.

בבקשה ליצירת קובץ, מתעדים בקריאה החוזרת (callback) של ViewModel המשויך ליעד של Compose.onCleared() זהו האות הטוב ביותר לדעת מתי יעד של יצירת תוכן מוסר מהמקבץ האחורי ונמחק.

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

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

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

סדר הקריאות החוזרות בערימה.
איור 2. תרשים של סטאק קריאה חוזרת.

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

הקריאה החוזרת (callback) השנייה יכולה לכלול רכיב מהותי שתומך בחיזוי חזרה, מעבר ל-AndroidX באמצעות ממשקי Progress API או קריאה חוזרת (callback) אחרת בהתאמה אישית.

פונקציית ה-callback של childFragmentManager פועלת אם פונקציות ה-callback שלמעלה מושבתות וסטאק החזרה לאחור של FragmentManager הזה לא ריק, כאשר childFragmentManager מצורף ל-Fragment. בדוגמה הזו, הקריאה החוזרת הפנימית הזו מושבתת.

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

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

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

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

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

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

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

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