navigationevent

  
ספריית Navigation Event מספקת API שמתמקד ב-KMP לטיפול בתנועת החזרה במערכת וגם בחיזוי של תנועת החזרה.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
‫8 באוקטובר 2025 - - ‎1.0.0-beta01 -

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

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

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

גרוב

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.0.0-beta01"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-beta01")
}

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

משוב

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

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

מידע נוסף זמין במאמרי העזרה בנושא כלי המעקב אחר בעיות.

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

גירסה 1.0

גרסה 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. ה-constructor הוא עכשיו פנימי. (Ie143c, b/444734264)
  • משתמשים ב-onBackCompletedFallback במקום ב-fallbackOnBackPressed ובפרמטר של בנאי. ההתנהגות לא משתנה. הפונקציה מופעלת רק באירועי חזרה שהושלמו ולא טופלו. (Idabe9, b/444734264)
  • הבונה הראשי של NavigationEventHistory(mergedHistory, currentIndex) הוא עכשיו internal. צרכנים חיצוניים צריכים להשתמש בבנאים הציבוריים (בנאי ריק או בנאי מבוסס-מחיצות) כדי ליצור מופעים. (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(...) מוחלפת. מטמיעים את הקריאה החוזרת החדשה onHistoryChanged(history: NavigationEventHistory) כדי לקבל עדכונים כאובייקט NavigationEventHistory יחיד. (I23e0b, ‏ b/444734264)
  • השקת NavigationEventDispatcher.history StateFlow גלובלי חדש. התהליך הזה לא גנרי, והוא מאפשר לצופים להירשם רק לשינויים במערך הניווט. הוא נשאר יציב במהלך התקדמות המחוות. זהו המקבילה של transitionState. (I1db10, b/444734264)
  • השקת NavigationEventDispatcher.transitionState StateFlow גלובלי חדש. התהליך הזה לא גנרי, והוא מאפשר לצופים להירשם רק למצב של תנועת היד (במצב סרק או בתהליך), בנפרד מההיסטוריה. (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. מעכשיו, רכיבי ה-handler שומרים על מצב המעבר שלהם, ומערכות חיצוניות יכולות לעקוב אחריו. (I9acd2, b/444734264)
  • הצגת מחלקה חדשה של TransitionState. ה-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)
  • תכין את NavigationEvent's swipeEdge בתור @IntDef (Icee54, ‏ b/443950342)
  • מוסיפים פרמטר 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 מבוסס-הזרימה ועוברים לשיטות הקריאה החוזרות החדשות. (I23bac, b/436248277)
  • מאפשרת למאזינים פסיביים לגשת לכל היסטוריית הניווט באמצעות מידע משולב על חזרה. מאפשרת לממשקי משתמש לעבד תצוגות מקדימות והיסטוריית ניווט מוטמעת במקום להיות מוגבלים לקריאה החוזרת העליונה ביותר. ‫(I7a510, ‏ b/436248277)
  • הוספת מודל מפורש של חזרה, נוכחיות והתקדמות כדי להבהיר את מצב הניווט ולתמוך בניווט קדימה באמצעות רכיבי handler מוטמעים. (Ib86da, ‏ b/420443609)
  • הוספת שיטות 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. השינוי הזה משקף טוב יותר את המטרה של המחלקה, שהיא טיפול במחוות ניווט מרובות שלבים. השיטה המתאימה addCallback היא עכשיו addHandler. (I2492a, b/443040331)

תיקוני באגים

  • למנוע את ההפעלה של חזרה לגיבוי בניווט קדימה. (I74814, ‏ b/436248290)
  • הוספת תמיכה בניווט חיזוי קדימה. NavigationEvent ממשקי ה-API מטפלים עכשיו בתנועות של חזרה ושל מעבר קדימה, ומאפשרים אנימציות עקביות לשני כיווני הניווט. (Idc98c, b/436248290)
  • למנוע קריסה של IllegalStateException במהלך הרכבה מחדש כשמסירים רכיב צאצא NavigationEventDispatcherOwner. (Iff50c, ‏ b/412629020)
  • מאזינים פסיביים יכולים עכשיו לגשת לכל היסטוריית הניווט באמצעות מידע משולב על חזרה, וכך ממשקי משתמש יכולים להציג תצוגות מקדימות והיסטוריית ניווט מוטמעת במקום להיות מוגבלים לקריאה החוזרת העליונה ביותר. ‫(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. Consuming State – משתמשים ב-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 כך שנדרש מפיץ ראשי שבו צריך להעביר במפורש את null כדי ליצור מפיץ בסיסי. (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 יכולים להיות עכשיו מפיצים ראשיים ומפיצים משניים, שיוצרים מבנה עץ היררכי. האפשרות הזו מאפשרת לאירועי ניווט להתפשט ולנוהל בצורה גמישה יותר ברכיבי ממשק משתמש מורכבים של Compose, על ידי שיקוף ההיררכיה המבנית של ממשק המשתמש באמצעות משגרים משורשרים. (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 כדי להתאים למוסכמות של כתיבת תוכן. שינוי שנתבקש על ידי JetBrains. (f60c79)
  • בוצע תיקון של היישום של התוסף Compose compiler ל-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 אחד בכל פעם. הוספה של NavigationEventCallback למספר משגרים תגרום להצגת 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

  • מחליפים את בנאי המשנה של 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, והיא נועדה להיות תחליף פחות דעתני לשימוש בממשקי ה-API של Activity ברכיבים ברמה גבוהה יותר או לשימוש ישיר בממשקי ה-API של Android framework OnBackInvokedDispatcher. ממשקי ה-API של androidx.activity נכתבו מחדש על בסיס ממשקי ה-API של אירועי הניווט כחלק מ-Activity 1.12.0-alpha01.