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

מערכת Android 14 (רמת API 34) מוסיפה תמיכה באנימציות מערכת ובממשקי API נוספים כדי ליצור אנימציות בהתאמה אישית. מידע נוסף זמין במאמר הבא: הוספת תמיכה באנימציות מובנות ומותאמות אישית של החזרה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. כדי לוודא שממשקי ה-API כבר משתמשים בממשקי ה-API של OnBackPressedDispatcher (כמו Fragments ורכיב הניווט) פועלים באופן חלק עם תנועת חזרה חזויה, שדרוג ל- פעילות ב-AndroidX מגרסה 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. העברת לוגיקת הטיפול האחורי של המערכת ללוגיקת AndroidX OnBackPressedDispatcher עם הטמעה של OnBackPressedCallback להנחיות מפורטות, ראו לספק ניווט מותאם אישית חזרה.

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

3. להפסיק ליירט אירועים חוזרים דרך OnBackPressed או KeyEvent.KEYCODE_BACK.

4. חשוב לשדרג ל- פעילות ב-AndroidX מגרסה 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. זה מונע מהפעילות הנוכחית תסתיים, והקריאה החוזרת (callback) תהיה זמינה להגיב לפעולת החזרה פעם אחת המשתמש משלים את הניווט 'הקודם' במערכת.

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. הפסקת תיעוד של אירועים חוזרים דרך OnBackPressed או KeyEvent.KEYCODE_BACK ל-Android מגרסה 13 ואילך.

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

אפשר לרשום OnBackInvokedCallback ב-PRIORITY_DEFAULT או PRIORITY_OVERLAY, שלא זמין בגרסאות AndroidX הדומות OnBackPressedCallback רישום קריאה חוזרת (callback) ב-PRIORITY_OVERLAY הוא במקרים מסוימים. הכלל הזה עשוי לחול כאשר מבצעים העברה מ-onKeyPreIme() והקריאה החוזרת צריכה לקבל את תנועת החזרה של IME פתוח. IME רושם קריאות חוזרות (callback) עם PRIORITY_DEFAULT כאשר פותחים אותו. כדי לוודא ש-OnBackInvokedDispatcher יפנה את תנועת החזרה לאחור לשיחה החוזרת במקום ל-IME הפתוח, צריך לרשום את השיחה החוזרת ב-PRIORITY_OVERLAY.

איך מביעים הסכמה לשימוש בתנועת החזרה החזוי

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

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

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

אם לא תציינו ערך, ברירת המחדל תהיה false ויבצעו את הפעולות הבאות:

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

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

החל מ-Android 14, הדגל 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=true עבור ".SecondActivity" מפעיל את האנימציה של המערכת בין הפעילויות.

כדאי להביא בחשבון את השיקולים הבאים כשמשתמשים דגל android:enableOnBackInvokedCallback:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

יצירת קריאות חוזרות (callback) לאחריות יחידה

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

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

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

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

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

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

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