navigationevent

  
ספריית Navigation Event מספקת API שמתמקד ב-KMP לטיפול בתנועת החזרה במערכת, וגם בחיזוי של תנועת החזרה.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
‫23 בספטמבר 2026 1.1.2 ‎1.2.0-rc01 - -

הצהרה על יחסי תלות

כדי להוסיף תלות ב-navigationevent, צריך להוסיף את מאגר Google Maven לפרויקט. מידע נוסף זמין במאמר בנושא מאגר Maven של Google.

אתם יכולים להוסיף את יחסי התלות של הארטיפקטים שאתם צריכים בקובץ build.gradle של האפליקציה או המודול:

גרוב

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.2.0"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.2.0")
}

מידע נוסף זמין במאמר הוספת יחסי תלות ב-build.

משוב

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

יצירת דיווח על בעיה חדשה

מידע נוסף זמין במאמרי העזרה בנושא Issue Tracker.

גרסה 1.2

גרסה ‎1.2.0-rc01

‫23 בספטמבר 2026

‫androidx.navigationevent:navigationevent-*:1.2.0-rc01 מופץ. גרסה ‎1.2.0-rc01 מכילה את השמירות האלה.

עדכונים של יחסי תלות

  • התלות ב-androidx.lifecycle:lifecycle-runtime עודכנה ל-2.10.0. הגרסה הזו נדרשת כדי להריץ בדיקות lint של זמן ריצה של מחזור חיים בחבילה עם AGP בגרסה 9.5.0-alpha04 ואילך. (I99bfd, ‏ b/556807521)

גרסה ‎1.2.0-alpha04

‫12 באוגוסט 2026

‫androidx.navigationevent:navigationevent-*:1.2.0-alpha04 מופץ. גרסה ‎1.2.0-alpha04 מכילה את השמירות האלה.

שינויים ב-API

  • הוספנו ל-NavigationEventInput ממשקי API חדשים, hasEnabledBackHandlers ו-hasEnabledForwardHandlers, כדי לאפשר מעקב נפרד אחרי יכולות כיווניות. (I772bf, b/123456789)

תיקוני באגים

  • הוספנו חיפוש חלופי של הקשר כדי לפתור את הבעיה LocalNavigationEventDispatcherOwner כשבעלי עץ התצוגה לא זמינים. (I51e30, ‏ b/530641649)

גרסה ‎1.2.0-alpha03

‫29 ביולי 2026

‫androidx.navigationevent:navigationevent-*:1.2.0-alpha03 מופץ. גרסה ‎1.2.0-alpha03 מכילה את השמירות האלה.

שינויים ב-API

  • מוסיפים את התגים title ו-url ל-NavigationEventInfo כדי לאפשר התאמה אישית של שם היעד וכתובת ה-URL של המיקום. (Ie5619)
  • הוספת פקטורי (factory) של NavigationEventDispatcherOwner ב-navigationevent. (I740d3)
  • מוסיפים את ההערה ExperimentalNavigationEventApi כדי לאפשר הסכמה מפורשת לשימוש בממשקי API חדשים ולא יציבים. (Ia5d25)

תיקוני באגים

  • הפיכת BrowserInput לזמין לציבור ביעדי wasmJs כ-API ניסיוני. (Icc2a8)

גרסה ‎1.2.0-alpha02

‫15 ביולי 2026

‫androidx.navigationevent:navigationevent-*:1.2.0-alpha02 מופץ. גרסה ‎1.2.0-alpha02 מכילה את השמירות האלה.

שינויים ב-API

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

תיקוני באגים

  • צריך לתקן את ההפצה של ערכי ברירת המחדל ב-NavigationEventDispatcher. (I015f8, ‏ b/531988076)

גרסה ‎1.2.0-alpha01

‫1 ביולי 2026

‫androidx.navigationevent:navigationevent-*:1.2.0-alpha01 מופץ. גרסה ‎1.2.0-alpha01 מכילה את השמירות האלה.

שינויים ב-API

  • מעכשיו יש ל-androidx.benchmark מינוי ל-minSdk עם מכסת אחסון של 24GB. (Ic2a85)
  • מוסיפים את onForwardCompletedFallback אל TestNavigationEventDispatcherOwner כדי להפעיל מעקב ובדיקה של אירועי ניווט קדימה שלא טופלו. (I6bbd7)
  • הוספנו את navigationEventInput ל-TestNavigationEventDispatcherOwner כדי לפשט את הסימולציה של אירועי ניווט בבדיקות. (I3ef48)

תיקוני באגים

  • ניקוי פרטי ה-API (Ia8066)
  • התעלמות מאירועי ניווט שנשלחים לקלט מנותק. בעבר, שליחת אירועים לקלט שהוסר הייתה גורמת לשגיאה IllegalStateException. ‫(I1a8bc, ‏ b/515890298)
  • מניעת כפילויות של סמלים בגרסאות ישנות יותר של JetBrains fork כשמשדרגים ל-Compose Multiplatform 1.11.0. (I4cc4d)

אין הערות לגבי הגרסה של הארטיפקט הזה.

גרסה 1.1

גרסה 1.1.2

‫17 ביוני 2026

‫androidx.navigationevent:navigationevent-*:1.1.2 מופץ. גרסה 1.1.2 מכילה את השמירות האלה.

תיקוני באגים

  • מעדכנים את יחסי התלות של Compose לגרסה 1.11.2. (a5e9259)

גרסה 1.1.1

‫6 במאי 2026

‫androidx.navigationevent:navigationevent-*:1.1.1 מופץ. גרסה 1.1.1 מכילה את השמירות האלה.

תיקוני באגים

  • הוסר ה-no-op‏ NavigationEventHandler כשנמצאים במצב בדיקה, כדי להפעיל את התכונה 'חזרה עם חיזוי' בתצוגות המקדימות של Android Studio.

גרסה 1.1.0

‫22 באפריל 2026

‫androidx.navigationevent:navigationevent-*:1.1.0 מופץ. גרסה 1.1.0 מכילה את השמירות האלה.

גרסה ‎1.1.0-rc01

‫8 באפריל 2026

‫androidx.navigationevent:navigationevent-*:1.1.0-rc01 מופץ. גרסה ‎1.1.0-rc01 מכילה את השמירות האלה.

תיקוני באגים

  • ‫compileSdk של Compose עודכן ל-API 37. כלומר, כשמשתמשים ב-Compose, נדרשת גרסת AGP מינימלית של 9.2.0. ‫(Id45cd, ‏ b/413674743)

גרסה ‎1.1.0-beta01

‫27 במרץ 2026

‫androidx.navigationevent:navigationevent-*:1.1.0-beta01 מופץ. גרסה ‎1.1.0-beta01 מכילה את השמירות האלה.

שינויים ב-API

  • מוסיפים OnForwardCompletedFallback ל-NavigationEventDispatcher כדי להפעיל התנהגות ברירת מחדל של המערכת לאירועי ניווט קדימה שלא טופלו. (Iac620, ‏ b/489138116)

גרסה ‎1.1.0-alpha01

‫25 בפברואר 2026

‫androidx.navigationevent:navigationevent-*:1.1.0-alpha01 מופץ. גרסה ‎1.1.0-alpha01 מכילה את השמירות האלה.

תכונות חדשות

  • תמיכה בכל יעדי Kotlin Multiplatform‏ (KMP) ב-NavigationEvent-Compose. הפרדת ההחלטה לגבי הבעלים מ-LocalView כדי לאפשר למארחי פלטפורמות לספק LocalNavigationEventDispatcherOwner כברירת מחדל, תוך שמירה על LocalView כגיבוי בטוח ב-Android. (Iae980, ‏ b/434940570, ‏ Iccf58)

שינויים ב-API

  • מוסיפים את פונקציות ההרחבה NavigationEvent.toBackEvent() ו-BackEvent.toNavigationEvent() כדי להמיר בין BackEvent ל-NavigationEvent ב-Android. (Ie3b71, b/477001292)

גירסה 1.0

גרסה 1.0.2

‫28 בינואר 2026

‫androidx.navigationevent:navigationevent-*:1.0.2 מופץ. גרסה 1.0.2 מכילה את השמירות האלה.

תיקוני באגים

  • תוקנה קריסה שמתרחשת כשמשתמשים ב-NavigationEventHandler בתצוגות מקדימות של Android Studio. ה-handler מזהה עכשיו את מצב הבדיקה ולא עושה כלום, וכך מאפשר להציג את התצוגה המקדימה בלי שסופק dispatcher. ‪(I370f2, b/454313986).

גרסה 1.0.1

‫3 בדצמבר 2025

‫androidx.navigationevent:navigationevent-*:1.0.1 מופץ. גרסה 1.0.1 מכילה את השמירות האלה.

תיקוני באגים

  • תוקן באג ConcurrentModificationException כשמסירים רכיב צאצא NavigationEventDispatcher כמו אלה שנוצרו באמצעות rememberNavigationEventDispatcherOwner(). ‫(ec68a9, ‏ b/454363524)

גרסה 1.0.0

‫19 בנובמבר 2025

‫androidx.navigationevent:navigationevent-*:1.0.0 מופץ. גרסה 1.0.0 מכילה את השמירות האלה.

התכונות העיקריות של גרסה 1.0.0:

הספרייה Navigation Event יציבה עכשיו. ‫Navigation Event היא ספריית AndroidX לטיפול באינטראקציות ברמת המערכת, כמו חזרה מהמערכת וחזרה עם חיזוי ב-Android (ובפלטפורמות אחרות).

  • כדי לטפל ב-NavigationEvent, אפשר להטמיע NavigationEventHandler משלכם שמבטל את הפונקציות הרצויות. לאחר מכן צריך להוסיף את ה-handler ל-NavigationEventDispatcher. החל מגרסת Activity 1.12.0, ‏ ComponentActivity מטמיע את הממשק החדש NavigationEventDispatcherOwner, שמספק רכיב לשליחת בקשות (dispatcher) שמוכן לשימוש :

    // The NavigationEventInfo provides information about a navigation state
object CurrentInfo : NavigationEventInfo()

// you can retrieve this from any component that is a NavigationEventDispatcherOwner
// or you can instantiate your own custom dispatcher
val dispatcher = myActivity.navigationEventDispatcher

val myHandler = object : NavigationEventHandler<NavigationEventInfo>(
            initialInfo = CurrentInfo,
            isBackEnabled = true
        ) {
            override fun onBackStarted(event: NavigationEvent) {
                // Prepare for the back event
            }

            override fun onBackProgressed(event: NavigationEvent) {
                // Use event.progress for predictive animations
            }

            // This is the required method for final event handling
            override fun onBackCompleted() {
                // Complete the back event
            }

            override fun onBackCancelled() {
                // Cancel the back event
            }
        }

dispatcher.addHandler(myHandler)

  • מודול navigationevent:navigationevent-compose מספק פונקציית קומפוזיציה נוחה NavigationBackHandler שמקשרת אוטומטית את ה-handler ל-NavigationEventDispatcher הקרוב ביותר של LocalNavigationEventDispatcherOwner, ומאפשרת למפתחים לספק את ההתנהגות הרצויה כפרמטרים:

    object CurrentInfo : NavigationEventInfo()
object PreviousInfo : NavigationEventInfo()

val navEventState = rememberNavigationEventState(
  currentInfo = CurrentInfo,
  backInfo = PreviousInfo
)

// Inside composition
NavigationBackHandler(
    State = navEventState,
    isBackEnabled = true,
    // optional
    onBackCancelled = { // Cancel the back event },
    // required
    onBackCompleted = { // Complete the back event } ,
)

שימוש בתבנית הזו ב-Compose מאפשר להעביר בקלות את NavigationEventState למעלה כך שניתן יהיה לצפות בו על ידי רכיבים שניתנים להרכבה שונים (כלומר, במקרה של Navigation3, אפשר להעביר את המצב למעלה מחוץ ל-NavDisplay).

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

    // Non-Compose
val parentDispatcher = NavigationEventDispatcher()
val childDispatcher = NavigationEventDispatcher(parent = parentDispatcher)

// Compose
val composeChildDispatcher = rememberNavigationEventDispatcher(
    // This defaults to `LocalNavigationEventDispatcherOwner.current`
    // Must explicitly provide null to have an unparented dispatcher created here
    parent = NavigationEventDispatch() 
)

  • הספרייה מאפשרת גם לספק אותות ישירות ל-NavigationEventDispatcher באמצעות NavigationEventInput. ‫NavigationEventInputs פועל כצד ה'קלט' של מערכת הניווט, ומתרגם אירועים ספציפיים לפלטפורמה (כמו מחוות חזרה של המערכת או לחיצות על כפתורים) לאירועים סטנדרטיים שאפשר לשלוח אל NavigationEventDispatcher. מודול navigationevent:navigationevent מספק כרגע 2 NavigationEventInputs: ‏ DirectNavigationEventInput כללי יותר שמאפשר שליחה של כל אירוע, ו-OnBackInvokedInput ספציפי ל-Android שמאפשר ל-NavigationEventDispatcher לתמוך בחזרה למערכת ובחיזוי תנועת החזרה. אם אתם מטמיעים רכיב משלכם לשליחת נתונים (במקום להשתמש ברכיב שסופק על ידי ComponentActivity), אתם צריכים להוסיף את הקלט באופן ידני:

    val dispatcher = NavigationEventDispatcher()

dispatcher.addInput(DirectNavigationEventInput())
dispatcher.addInput(OnBackInvokedDefaultInput(invoker))

גרסה ‎1.0.0-rc01

‫5 בנובמבר 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-rc01 מופץ. גרסה ‎1.0.0-rc01 מכילה את השמירות האלה.

גרסה ‎1.0.0-beta01

‫8 באוקטובר 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-beta01 מופץ. גרסה ‎1.0.0-beta01 מכילה את השמירות האלה.

שינויים ב-API

  • מתקנים את ההערה FloatRange ב-NavigationEvent.touchX וב-NavigationEvent.touchY. הערכים האלה מייצגים קואורדינטות פיקסלים מוחלטות ואין להם גבול עליון 1.0. (I4b205, ‏ b/445989313)
  • משנים את השם של הרכיב הקומפוזבילי NavigationEventDispatcherOwner ל-rememberNavigationEventDispatcherOwner. הפונקציה מחזירה עכשיו את הערך NavigationEventDispatcherOwner ישירות. כדי לספק את הבעלים הזה לקומפוזיציה משנית, משתמשים ב-CompositionLocalProvider. (I874b2, b/444446629)

גרסה ‎1.0.0-alpha09

‫24 בספטמבר 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha09 מופץ. גרסה ‎1.0.0-alpha09 מכילה את השמירות האלה.

שינויים ב-API

  • במקום ליצור מופע של Idle(), צריך להשתמש ישירות באובייקט היחיד NavigationEventTransitionState.Idle. ‫(Ic7d9e, ‏ b/444734264)
  • הגדירו את בנאי הנוחות כפנימיים; קבלו מופעים באמצעות NavigationEventDispatcher.history ציבורי במקום בנייה ישירה. (I3b7e0, ‏ b/444734264)
  • נדרשת יצירה של NavigationEventState באמצעות rememberNavigationEventState; הקונסטרוקטור הוא עכשיו פנימי. (Ie143c, ‏ b/444734264)
  • להשתמש ב-onBackCompletedFallback במקום ב-fallbackOnBackPressed ובפרמטר של בנאי. ההתנהגות לא משתנה. הפונקציה מופעלת רק באירועי חזרה לאחור שהושלמו ולא טופלו. (Idabe9, ‏ b/444734264)
  • הבונה הראשי של NavigationEventHistory(mergedHistory, currentIndex) הוא עכשיו internal. צרכנים חיצוניים צריכים להשתמש ב-constructors ציבוריים (או ב-constructor ריק או ב-constructor מבוסס-מחיצות) כדי ליצור מופעים. (I1c047, ‏ b/444734264)
  • Make View.setViewTreeNavigationEventDispatcherOwner accept nullable owner (Ic9eb6, b/444436762)
  • NavigationEventInfo הוא עכשיו abstract class במקום interface. מעדכנים את כל ההטמעות בהתאמה אישית כך שיורשות מהמחלקה (לדוגמה, data class MyInfo : NavigationEventInfo()). (I1e59c, b/444734264)
  • המאפיין NavigationEventDispatcher.state והפונקציה getState<T>() מדור קודם הוסרו. משתמשים בתהליכי העבודה החדשים והנפרדים של dispatcher.transitionState (לגבי התקדמות התנועה) ושל dispatcher.history (לגבי מחסנית הניווט). (Ic2ceb, b/444734264)
  • הפונקציה NavigationEventInput.onInfoChanged(...) callback הוחלפה. מטמיעים את הקריאה החוזרת (callback) החדשה onHistoryChanged(history: NavigationEventHistory) כדי לקבל עדכונים כאובייקט NavigationEventHistory יחיד. ‫(I23e0b, ‏ b/444734264)
  • השקת NavigationEventDispatcher.history StateFlow גלובלי חדש. התהליך הלא-גנרי הזה מאפשר לצופים להירשם רק לשינויים במערך הניווט, והוא נשאר יציב במהלך התקדמות המחוות. זהו המקבילה לtransitionState. (I1db10, b/444734264)
  • השקת NavigationEventDispatcher.transitionState StateFlow גלובלי חדש. התהליך הלא-גנרי הזה מאפשר לצופים להירשם רק למצב של התנועה הפיזית (Idle/InProgress), בנפרד מההיסטוריה. (I171fa, ‏ b/444734264)
  • להציג את הכיתה NavigationEventHistoryState. ה-API הזה ישמש כ-API הליבה לצפייה בהיסטוריית נתוני הניווט, בנפרד ממצב התנועה. (I81ca5, ‏ b/444734264)
  • הפונקציה NavigationEvent מסומנת עכשיו כ-@Immutable, וכך מאפשרת ל-Compose Compiler לבצע אופטימיזציה של הרכבות מחדש. ‫(If78c7, ‏ b/444734264)
  • ממשקי ה-API של navigationevent-compose handler עודכנו. הפונקציות NavigationEventHandler ו-NavigationBackHandler (והווריאציות שלהן) תומכות עכשיו בעומס יתר חדש שמקבל NavigationEventStates שהועברו למעלה. העומסים הפשוטים (שמקבלים currentInfo) נשמרים ועכשיו משתמשים במודל המצב החדש הזה באופן פנימי. (Ic3251, b/444734264)
  • מוסיפים את מחזיק המצב החדש @Stable NavigationEventState<T> לספריית navigationevent-compose. האובייקט הזה משלב היסטוריה מקומית עם מצב תנועה מקומי, והוא יהיה הקישור העיקרי בין rememberNavigationEventState לבין NavigationEventHandler. (Ifb69f, ‏ b/444734264)
  • הוספת נכס חדש מסוג לקריאה בלבדtransitionState: TransitionState אל NavigationEventHandler. מעכשיו, ל-Handlers יש מצב מעבר משלהם, ומערכות חיצוניות יכולות לצפות בו. ‫(I9acd2, ‏ b/444734264)
  • הצגת מחלקה חדשה של TransitionState sealed. ה-API הזה ישמש כ-API הליבה למעקב אחר מצב המחוות, בנפרד מהיסטוריית הניווט. (Id4beb, ‏ b/444734264)
  • הצגת currentInfo,‏ backInfo ו-forwardInfo כמאפיינים ציבוריים לקריאה בלבד ב-NavigationEventHandler. (Ia7636, ‏ b/444734264)
  • בכל הטמעה של NavigationEventHandler צריך עכשיו לספק ערך initialInfo: T לבנאי הבסיסי. (Idcfea, ‏ b/444734264)
  • מחליפים את OnBackInvokedInput ב-OnBackInvokedOverlayInput או ב-OnBackInvokedDefaultInput. (I5323f, ‏ b/428948766)
  • סימון של NavigationEventState כ@Immutable. כך משפרים את הביצועים של Compose, כי אפשר לוודא שפונקציות קומפוזביליות שמתבססות על הערך הדינמי הזה יכולות לדלג על רה-קומפוזיציה בצורה נכונה. (I399c8)
  • שינוי השם של NavigationEventInfo.NotProvided ל-NavigationEventInfo.None; כדי לעדכן את ההפניות. לא יהיה שינוי בהתנהגות. (I5e2d4)
  • הפונקציה NavigationEventInfo מסומנת עכשיו כ-@Immutable, וכך מאפשרת ל-Compose Compiler לבצע אופטימיזציה של הרכבות מחדש. (I7c112)
  • שיפור הארגונומיה של Java באמצעות ממשק מהנה לגיבוי של השלמה לאחור. (I8a860)
  • שינוי השם של onHasEnabledHandlerChanged לonHasEnabledHandlersChanged. ההסבר הזה מבהיר שההתקשרות חזרה מדווחת על מצב ההפעלה המשותף של כל רכיבי ה-handler, ולא רק על אחד מהם. (I1af61, b/443711297)
  • הסרנו את hasEnabledHandler() מ-NavigationEventDispatcher;. במקומה צריך להשתמש ב-NavigationEventInput.onHasEnabledHandlersChanged. (Idef72, ‏ b/443711297)
  • מוסיפים onInfoChanged callback ל-NavigationEventInput כדי להודיע למאזינים על שינויים בהיסטוריית הניווט. כך אפשר לקבל את ההקשר המלא של הערימות הנוכחיות, הקודמות והבאות, ולתת ל-Inputs להגיב למידע ההקשרי. (I69a8b, ‏ b/443282983)
  • יצירת @IntDef של swipeEdge (Icee54, ‏ b/443950342)NavigationEvent
  • מוסיפים פרמטר priority ל-NavigationEventDispatcher.addInput כדי להגדיר את ההיקף של פונקציית dispatcher לעדיפות אחת. אירועים כמו onHasEnabledCallbacksChanged מופעלים עכשיו רק כשמתבצע שינוי בפונקציות callback בעדיפות הזו. (I3e488, ‏ b/443711297)
  • כדי שהפרמטר NavigationEventDispatcher יהיה ברור יותר, צריך לשנות את השם שלו מ-parentDispatcher ל-parent. (Id4f1f, ‏ b/443801782)
  • הסרת NavigationEventPriority לטובת @IntDef למשתמשי Java‏ (I10a9f, ‏ b/440514265)
  • אכיפה של חוזה לטיפול בניווט. אם NavigationEventHandler מגדיר את isBackEnabled או את isForwardEnabled לערך true, עכשיו צריך לעקוף את onBackCompleted או את onForwardCompleted בהתאמה. ההטמעות שמוגדרות כברירת מחדל זורקות עכשיו חריג כדי למנוע כשלים שקטים. (I17c62)
  • הקפדה על ערכי עדיפות תקינים כשמוסיפים מטפלים באירועי ניווט. קריאה ל-addHandler עם עדיפות לא נתמכת תגרום עכשיו להחזרת IllegalArgumentException, ותספק משוב מיידי לגבי שימוש לא נכון בכל פלטפורמות היעד. (I3c474)

תיקוני באגים

  • לוודא ש-addHandler הוא אידמפוטנטי ולהתעלם מרישומים כפולים. (I052aa, ‏ b/444734264)
  • שמירה על סנכרון של מאפייני NavigationEventState במהלך הרכבה מחדש. (Ib3b4d, ‏ b/444734264)
  • חשוב לוודא ש-NavigationEventInputs מקבל את המידע ההקשרי העדכני (נוכחי, קודם, הבא) מיד לאחר ההרשמה. ‫(Ie65bf, ‏ b/443282983)

גרסה ‎1.0.0-alpha08

‫10 בספטמבר 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha08 מופץ. גרסה ‎1.0.0-alpha08 מכילה את השמירות האלה.

תכונות חדשות

  • הוספנו API מבוסס-lambda‏ NavigationEventHandler שמחליף את ה-handler מבוסס-הזרימה. אפשר לטפל בתנועות החלקה קדימה ואחורה באמצעות קריאות חוזרות פשוטות במקום איסוף של תהליכים, וכך לצמצם את כמות הקוד הסטנדרטי ולמנוע בעיות שקשורות לביטול. הוספנו את NavigationBackHandler ו-NavigationForwardHandler כממשקי API נוחים וממוקדים. מסירים את NavigationEventHandler Flow ומבצעים מיגרציה לקריאות החוזרות החדשות. (I23bac, ‏ b/436248277)
  • הגדרה שמאפשרת למאזינים פסיביים לגשת לכל מקבץ הפעילויות הקודמות (back stack) באמצעות מידע משולב על חזרה. ההגדרה הזו מאפשרת לממשקי משתמש לרנדר תצוגות מקדימות והיסטוריית ניווט מוטמעת, במקום להיות מוגבלים לקריאה החוזרת (callback) העליונה ביותר. (I7a510, ‏ b/436248277)
  • הוספת מודל מפורש של חזרה, נוכחיות והתקדמות כדי להבהיר את מצב הניווט ולתמוך בניווט קדימה באמצעות רכיבי handler מוטמעים. (Ib86da, ‏ b/420443609)
  • הוספה של methods מסוג onForward* ו-isForwardEnabled ל-NavigationEventCallback. (Ic100f, ‏ b/436248290)
  • הוספת תמיכה בניווט קדימה אל NavigationEventInput. (I5734b)

שינויים ב-API

  • הפעלת בדיקה של אירועי ניווט קדימה באמצעות TestNavigationEventCallback. משתמשים בווים של isForwardEnabled ושל onForward*. ‫(I21fb5, ‏ b/420443609)
  • שינוי השם של onEvent* בקשות להחזרת שיחה לonBack* בNavEvent. (I228b3, ‏ b/436248290)
  • המרת SwipeEdge למחלקה מוטמעת. (Id5e01)
  • הגדרת הספרייה navigationevent כך שתהיה תואמת ל-Java. עכשיו יש גישה מלאה לכל ממשקי ה-API הציבוריים מקוד Java, כך שאפשר לשלב אותם בצורה חלקה בפרויקטים שמשתמשים בשפות שונות או רק ב-Java. (Ibc944,I5465f, I9fb1e, b/440532890b/443040294)
  • שינוי שם התפקיד NavigationEventCallback ל-NavigationEventHandler כדי להבהיר את התפקידים ב-API. השינוי הזה משקף טוב יותר את המטרה של המחלקה, שהיא לטפל במחוות ניווט מרובות שלבים. ה-method התואם addCallback הוא עכשיו addHandler. (I2492a, b/443040331)

תיקוני באגים

  • למנוע את ההפעלה של חזרה לגרסה קודמת בניווט קדימה. (I74814, ‏ b/436248290)
  • הוספת תמיכה בניווט קדימה עם חיזוי. NavigationEvent ממשקי ה-API מטפלים עכשיו בתנועות החלקה אחורה וקדימה, ומאפשרים אנימציות עקביות לשני כיווני הניווט. (Idc98c, ‏ b/436248290)
  • מונע קריסה של IllegalStateException במהלך הרכבה מחדש כשמסירים רכיב צאצא NavigationEventDispatcherOwner. ‫(Iff50c, ‏ b/412629020)
  • משתמשים בפונקציות קריאה חוזרת פסיביות יכולים עכשיו לגשת לכל מקבץ פעילויות קודמות (back stack) באמצעות מידע משולב על חזרה, וכך ממשקי משתמש יכולים לרנדר תצוגות מקדימות והיסטוריית ניווט מוטמעת במקום להיות מוגבלים לפונקציית הקריאה החוזרת העליונה ביותר. (I7a510, ‏ b/436248277)

גרסה ‎1.0.0-alpha07

‫27 באוגוסט 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha07 מופץ. גרסה ‎1.0.0-alpha07 מכילה את השמירות האלה.

שינויים ב-API

  • הסרה של NavigationEventDispatcher.onHasEnabledCallbacksChanged. (I50e97)
  • יצירת תקציר של NavigationEventCallback.onEventCompleted(). (I36b38)
  • שינוי השיטות NavigationEventCallback#on* לשיטות protected. מעדכנים את קוד החיוג כדי לשנות את ההגדרות. (I6b691)
  • שינוי השם של פונקציות DirectNavigationEventInput. (Iffb62)
  • שינוי השם של NavigationEventInput.onAttach לonAdded. (I2d0b8)
  • שינוי השם של NavigationEventInput.onDetach לonRemoved. (I2d0b8)
  • שינוי השם של NavigationEventInputHandler לNavigationEventInput. (I676a4)
  • הוספת @EmptySuper אל NavigationEventInput.onHasEnabledCallbacksChanged. ‫(If9853)
  • מטמיעים את onAttach ב-NavigationEventInputHandler. (I03648)
  • מטמיעים את onDetach ב-NavigationEventInputHandler. (I03648)
  • ההגדרה NavigationEventCallback מופעלת כברירת מחדל כשיוצרים את המרחב. (Ic0188)
  • מחליפים את NavigationEventInput.addOnHasEnabledCallbacksChangedCallback ב-NavigationEventInput.onHasEnabledCallbacksChanged. (I64e93)
  • הדרישה היא שה-thread הראשי יהיה NavigationEventDispatcher.addInput. (Ic2930)
  • הדרישה היא שה-thread הראשי יהיה NavigationEventDispatcher.removeInput. (Ic2930)
  • הסרה של Dispatcher.addOnHasEnabledCallbacksChangedCallback. החלפה ב-Dispatcher.onHasEnabledCallbacksChanged. (Ida3e3, ‏ b/436530096)

תיקוני באגים

  • תוקן באג שבו הוספה של handler שכבר צורף או הסרה של handler שלא צורף הפעילו לוגיקה שגויה של מחזור החיים. (I9e47b)

גרסה ‎1.0.0-alpha06

‫13 באוגוסט 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha06 מופץ. גרסה ‎1.0.0-alpha06 מכילה את השמירות האלה.

תכונות חדשות

Passive Listeners API

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

התכונה הזו כוללת שני חלקים:

  1. העברת מידע – אפשר להשתמש ב-NavigationEventInfo כדי להעביר נתונים בהתאמה אישית.
  2. מצב צריכה – משתמשים ב-dispatcher.state (NavigationEventState) כדי לראות את ההתקדמות וההקשר של תנועת היד.
  • ‫NavigationEventCallback עכשיו חושף את השיטה setInfo(currentInfo, previousInfo) להגדרת הקשר של תנועת המגע בשיחה אחת (I1d5e7, ‏ b/424470518).
  • ‫NavigationEventHandler מוסיף עומס יתר חדש שמקבל את currentInfo ו-previousInfo, מה שהופך אותו ל-API הראשי לאספקת הקשר באפליקציות Compose‏ (I6ecd3, ‏ b/424470518).

דוגמה:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • ‫NavigationEventDispatcher חושף עכשיו את dispatcher.state ואת dispatcher.getState<T>() (If7fae, ‏ Ia90ca, ‏ b/424470518). ממשקי ה-API האלה שמבוססים על StateFlow מאפשרים לכל ממשק משתמש לעקוב אחרי התקדמות המחוות ונתונים הקשריים בלי לטפל באירוע ישירות.

דוגמה:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • הוספת נכס progress אל NavigationEventState (I7b196) שמחזיר latestEvent.progress אם התהליך מתבצע, או 0F בכל מקרה אחר:

    val progress = state.progress

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

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

שינויים ב-API

  • הפרמטר isPassthrough הוסר מה-NavigationEventCallback. ‫(I99028, ‏ b/424470518)
  • היצרנים של NavigationEventState הם עכשיו פנימיים. לצורך בדיקה, מעדכנים את המצב (ברירת המחדל היא Idle) דרך DirectNavigationEventInputHandler. מתקשרים למספר handleOnStarted או handleOnProgressed כדי להגדיר את המצב לInProgress, ולמספר handleOnCompleted או handleOnCancelled כדי להחזיר אותו למצב Idle. כדי לעדכן את NavigationEventInfo, צריך להשתמש ב-NavigationEventCallback.setInfo. ‫(I93dca, ‏ b/424470518)
  • נוספו פרמטרים שמוגדרים כברירת מחדל ל-NavigationEvent כדי להקל על יצירת מופעים ולפשט את הבדיקות. צריך להשתמש בהם במקום ב-TestNavigationEvent. (I5dc49, I232f4)
  • נוסף TestNavigationEventCallback לבדיקת אירועי ניווט עם מצבים ספציפיים נוכחיים/קודמים. (Idd22e, b/424470518)
  • ‫NavigationEventInputHandler הפך למחלקה מופשטת כדי להחליף את AbstractNavigationEventInputHandler הקודם בהטמעה ב-DirectNavigationEventInputHandler (Iadde5, ‏ Ifed40I3897c, ‏b/432616296, ‏b/435416924)
  • הקידומות של הפונקציות send* ב-NavigationEventInputHandler שונו ל-handle*. (Iffcaf)
  • המינוי OnBackInvokedInputHandler כולל עכשיו את abstract NavigationInputHandler החדש. (Ib45aa)
  • השתנה NavigationEventDispatcherOwner כך שנדרש מפיץ ראשי (parent dispatcher) שבו צריך להעביר במפורש את null כדי ליצור מפיץ ראשי (root dispatcher). (Ia6f64, b/431534103)

תיקוני באגים

  • שיפור היעילות על ידי הימנעות מהעתקת אוספים ב-NavigationEventDispatcher.dispose(). (I4ab09)
  • תוקנה בעיה שבה NavigationEventHandler לא הגיב כמו שצריך לשינויים במצב המופעל שלו. (Ia5268,I19bec, I5be5c, b/431534103)

עדכונים ב-Docs

  • המסמך KDocs עבור NavigationEvent הורחב כדי להבהיר את התפקיד שלו כעטיפת אירועים מאוחדת ואת התנהגות מאפייני הפרטים בסוגי ניווט שונים (מחוות, קליקים). (I91e8d)
  • עדכנו את המסמכים בנושא ממשקי API של Compose לטיפול בחזרה למערכת (BackHandler, ‏ PredictiveBackHandler, ‏ NavigationEventHandler) כדי להסביר את ההתנהגות באופן ספציפי לגבי סדר ההתקשרות חזרה. (I7ab94, )

עדכון תלות

  • ‫NavigationEvent תלוי עכשיו ב-Compose Runtime 1.9.0-beta03, שמאפשר לארטיפקט navigationevent-compose לתמוך בכל יעדי KMP. (Ia1b87)

גרסה ‎1.0.0-alpha05

‫30 ביולי 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha05 מופץ. גרסה ‎1.0.0-alpha05 מכילה את השמירות האלה.

תמיכה בהיררכיה של הורה-צאצא:

ל-NavigationEventDispatcher יכולים להיות עכשיו משגרים ראשיים ומשגרים משניים, שיוצרים מבנה עץ היררכי. כך אירועי הניווט יכולים להתפשט ולנוהל בצורה גמישה יותר ברכיבי UI מורכבים של Compose, על ידי שיקוף ההיררכיה המבנית של ה-UI באמצעות משגרים משורשרים. (I194ac)

  // Create a parent dispatcher that will manage navigation events at a higher level.
  val parentDispatcher = NavigationEventDispatcher()

  // Create a child dispatcher linked to the parent, forming a hierarchy.
  val childDispatcher = NavigationEventDispatcher(parentDispatcher)

הנכס ההיררכי isEnabled מאפשר שליטה במרכז הבקרה מלמעלה למטה. אם המדיניות isEnabled מוגדרת כ-false בשרת הפצה, היא משביתה אוטומטית את כל שרתי ההפצה שנגזרים ממנו. התכונה הזו מאפשרת להשבית ביעילות ענפים שלמים של מערכת אירועי הניווט. (I9e985)

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

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

  // Create a test callback and add it to the child dispatcher.
  val callback1 = TestNavigationEventCallback(isEnabled = true)
  childDispatcher.addCallback(callback1)

  // Since the childDispatcher is disabled, the callback is effectively disabled as well.
  assertThat(callback1.isEnabled).isFalse()

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

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

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

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

הערה: אנחנו נציג רכיב חדש של NavigationEventDispatcherOwner Composable שמנהל באופן אוטומטי את ה-Dispatcher של רכיב צאצא בממשק המשתמש של Compose ב-aosp/3692572. עם זאת, השינוי הזה לא נכלל בגרסה הנוכחית, אבל אנחנו מתכננים לכלול אותו בגרסה הבאה.

Navigation Testing Library

  • הוספת מודול navigationevent-testing כדי לספק כלי בדיקה ייעודיים לספריית navigationevent. (0e50b6)
  • הוספת TestNavigationEventCallback מחלקה פיקטיבית של כלי עזר לבדיקה. הוא מתעד קריאות לשיטות קריאה חוזרת ומאחסן פריטים שהתקבלו NavigationEvent כדי לתמוך באימות. (4a0246)
  • הוספתי פונקציה בסיסית פיקטיבית TestNavigationEvent כדי ליצור מופעים של NavigationEvent עם ערכי ברירת מחדל, וכך לפשט את בדיקות היחידה לעיבוד אירועי ניווט. (3b63f5)
  • הוספת TestNavigationEventDispatcherOwner מחלקה פיקטיבית של כלי עזר לבדיקה. הוא עוקב אחרי מספרים של אירועים של חזרה למצב הקודם ושל שינוי מצב ההפעלה, כדי לתמוך באימות אינטראקציות בבדיקות. (c8753e)

שינויים ב-API

  • מעבירים את NavigationEventInputHandler מ-androidMain אל commonMain כדי שיהיה זמין בקוד המשותף של KMP. להוסיף public send* שיטות חדשות לשליחת אירועים. שינוי פונקציות השליחה ב-NavigationEventDispatcher מ-public ל-internal; המשתמשים צריכים עכשיו להשתמש ב-NavigationEventInputHandler כדי לשלוח אירועים. (Ia7114)
  • שינוי השם של NavigationInputHandler לOnBackInvokedInputHandler. (I63405)

תיקוני באגים

  • מבצעים רפקטורינג (שינוי מבנה הקוד) של NavigationEventDispatcher כדי לצמצם את התקורה על ידי הימנעות מהקצאות של רשימות ביניים ושיפור הביצועים של שליחת קריאות חוזרות. (I82702, ‏ I1a9d9)
  • מוסיפים הערות @FloatRange לשדות touchX,‏ touchY ו-progress ב-NavigationEvent כדי לאכוף טווחי ערכים תקינים בזמן ההידור ולשפר את הבטיחות של ה-API. (Iac0ec)

גרסה ‎1.0.0-alpha04

‫2 ביולי 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha04 מופץ. גרסה ‎1.0.0-alpha04 מכילה את השמירות האלה.

תיקוני באגים

  • השתמשתי ב-implementedInJetBrainsFork כדי navigationevent-compose והוספתי יעד commonStubs כדי להתאים למוסכמות של Compose. בקשת שינוי שנשלחה על ידי JetBrains. (f60c79)
  • בוצע תיקון של ההחלה של התוסף של מהדר Compose ל-Kotlin/Native כדי להבטיח יצירה נכונה של קובץ stub. אין השפעה על ממשקי API ציבוריים או על אופן הפעולה שלהם. (1890c9)

גרסה ‎1.0.0-alpha03

‫18 ביוני 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha03 מופץ. גרסה ‎1.0.0-alpha03 מכילה את השמירות האלה.

תכונות חדשות

  • הוספנו מודול חדש, navigationevent-compose, כדי לתמוך בתכונות של Jetpack Compose בספרייה navigationevent. (980d78)
  • NavigationEvent נוספה לקומפוזיציה LocalNavigationEventDispatcherOwner קומפוזיציה מקומית חדשה. הפונקציה מחזירה ערך שניתן להגדיר כ-null כדי לקבוע בצורה טובה יותר אם היא זמינה בהרכב הנוכחי. ‫NavigationEventHandler יציג עכשיו שגיאה אם לא נמצא הבעלים הבסיסי. (62ffda)
  • NavigationEvent נוסף ל-Compose רכיב NavigationEventHandler Composable חדש לטיפול באירועים (תנועת חזרה עם חיזוי). היא מספקת Flow של אובייקטים מסוג NavigationEvent שצריך לאסוף בפונקציית ה-lambda להשעיה שסיפקת c42ba6: 
NavigationEventHandler { progress: Flow<NavigationEvent> ->
  // This block is executed when the back gesture begins.
  try {
    progress.collect { backEvent ->
      // Handle gesture progress updates here.
    }
    // This block is executed if the gesture completes successfully.
  } catch (e: CancellationException) {
    // This block is executed if the gesture is cancelled
    throw e
  } finally {
    // This block is executed either the gesture is completed or cancelled
  }
}

שינויים ב-API

  • כל NavigationEventCallback יכול להיות רשום רק אצל NavigationEventDispatcher אחד בכל פעם. הוספה של לכמה מרכזי ניהול יוצרת IllegalStateException. שימו לב שההתנהגות הזו שונה מ-OnBackPressedDispatcher, שמאפשרת כמה מרכזי ניהול. (e82c19)
  • הפכנו את isPassThrough ל-val כדי למנוע מוטציה במהלך הניווט, שיכולה לשבש את השליחה של NavigationEvent. (I0b287)

גרסה ‎1.0.0-alpha02

‫4 ביוני 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha02 מופץ. גרסה ‎1.0.0-alpha02 מכילה את השמירות האלה.

שינויים ב-API

  • מחליפים את ה-constructor המשני של NavigationEventDispatcher בארגומנטים שמוגדרים כברירת מחדל. (I716a0)
  • הסרת מאפיין העדיפות מהנכס NavigationEventCallback. עדיף להעביר את העדיפות אל NavigationEventDispatcher.addCallback(). (I13cae)

תיקוני באגים

  • תוקנה בעיה ConcurrentModificationException שיכולה לקרות כשמתבצעת קריאה ל-NavigationEventCallback.remove() בגלל שינוי בו-זמני של הרשימה הפנימית של רכיבים שניתן לסגור. (b/420919815)

גרסה ‎1.0.0-alpha01

‫20 במאי 2025

‫androidx.navigationevent:navigationevent-*:1.0.0-alpha01 מופץ. גרסה 1.0.0-alpha01 מכילה את השמירות האלה.

תכונות חדשות

  • הספרייה androidx.navigationevent מספקת API שמתמקד ב-KMP לטיפול בפעולת החזרה במערכת, וגם בחזרה עם תצוגה מקדימה. ‫NavigationEventDispatcher משמש כממשקי API משותפים לרישום של מופע אחד או יותר של NavigationEventCallback לקבלת אירועים של חזרה למערכת.
  • השכבה הזו נמצאת מתחת לממשקי ה-API שפורסמו בעבר ב-androidx.activity, והיא נועדה להיות תחליף פחות דעתני לשימוש בממשקי Activity API ברכיבים ברמה גבוהה יותר או לשימוש ישיר בממשקי Android framework OnBackInvokedDispatcher API. ממשקי ה-API של androidx.activity נכתבו מחדש על בסיס ממשקי ה-API של אירועי הניווט כחלק מ-Activity 1.12.0-alpha01.