navigationevent

  
Navigation Event 程式庫提供 KMP 優先的 API，可處理系統返回鍵和預測返回。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2026 年 9 月 23 日 1.1.2 1.2.0-rc01 - -

宣告依附元件

如要為 navigationevent 新增依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

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

Kotlin

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

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.2 版本

1.2.0-rc01 版本

2026 年 9 月 23 日

發布 androidx.navigationevent:navigationevent-*:1.2.0-rc01。1.2.0-rc01 版包含這些修訂項目。

依附元件更新

  • androidx.lifecycle:lifecycle-runtime 依附元件已更新至 2.10.0 版。如要使用 AGP 9.5.0-alpha04 以上版本執行隨附的生命週期執行階段 Lint 檢查，就必須使用這個版本。(I99bfd、b/556807521)

1.2.0-alpha04 版本

2026 年 8 月 12 日

發布 androidx.navigationevent:navigationevent-*:1.2.0-alpha04。1.2.0-alpha04 版包含這些修訂項目。

API 變更

  • 在 NavigationEventInput 中新增 hasEnabledBackHandlers 和 hasEnabledForwardHandlers API，以便獨立追蹤方向功能。(I772bf、b/123456789)

修正錯誤

  • 導入回溯脈絡遍歷查詢，以解決檢視區塊樹狀結構擁有者無法使用的問題。LocalNavigationEventDispatcherOwner(I51e30、b/530641649)

1.2.0-alpha03 版本

2026 年 7 月 29 日

發布 androidx.navigationevent:navigationevent-*:1.2.0-alpha03。1.2.0-alpha03 版包含這些修訂項目。

API 變更

  • 在 NavigationEventInfo 中新增 title 和 url，即可自訂目的地標題和位置網址。(Ie5619)
  • 在 navigationevent 中新增 NavigationEventDispatcherOwner 工廠。(I740d3)
  • 新增 ExperimentalNavigationEventApi 註解，允許明確選擇加入新的不穩定 API。(Ia5d25)

修正錯誤

  • 在 wasmJs 目標中，將 BrowserInput 做為實驗性 API 公開提供。(Icc2a8)

1.2.0-alpha02 版本

2026 年 7 月 15 日

發布 androidx.navigationevent:navigationevent-*:1.2.0-alpha02。1.2.0-alpha02 版包含這些修訂項目。

API 變更

  • 在 NavigationEventInput 中新增 hasEnabledHandlers 屬性，讓開發人員可直接查詢目前的處理常式狀態，而不必依賴回呼。(I8ecec)

修正錯誤

1.2.0-alpha01 版本

2026 年 7 月 1 日

發布 androidx.navigationevent:navigationevent-*:1.2.0-alpha01。1.2.0-alpha01 版包含這些修訂項目。

API 變更

  • 「androidx.benchmark」現在的 minSdk 為 24。(Ic2a85)
  • 將 onForwardCompletedFallback 新增至 TestNavigationEventDispatcherOwner，即可追蹤及測試未處理的轉送導覽事件。(I6bbd7)
  • 將 navigationEventInput 新增至 TestNavigationEventDispatcherOwner，簡化測試中的模擬導覽事件。(I3ef48)

修正錯誤

  • 清除 API 資訊 (Ia8066)
  • 忽略傳送至已中斷連線輸入裝置的導覽事件。先前，將事件分派至已移除的輸入內容會擲回 IllegalStateException。(I1a8bc、b/515890298)
  • 升級至 Compose Multiplatform 1.11.0 時，避免與舊版 JetBrains 分支版本重複使用符號。(I4cc4d)

這個構件沒有任何版本資訊。

1.1 版本

1.1.2 版本

2026 年 6 月 17 日

發布 androidx.navigationevent:navigationevent-*:1.1.2。1.1.2 版包含這些修訂項目。

修正錯誤

  • 將 Compose 依附元件更新至 1.11.2 版。(a5e9259)

1.1.1 版

2026 年 5 月 6 日

發布 androidx.navigationevent:navigationevent-*:1.1.1。1.1.1 版包含這些修訂項目。

修正錯誤

  • 在檢查模式下移除無運算元的 NavigationEventHandler，以便在 Android Studio 預覽版中啟用預測返回功能。

1.1.0 版本

2026 年 4 月 22 日

發布 androidx.navigationevent:navigationevent-*:1.1.0。1.1.0 版包含這些修訂項目。

1.1.0-rc01 版本

2026 年 4 月 8 日

發布 androidx.navigationevent:navigationevent-*:1.1.0-rc01。1.1.0-rc01 版包含這些修訂項目。

修正錯誤

  • 將 Compose compileSdk 更新至 API 37。也就是說，使用 Compose 時，AGP 最低版本必須為 9.2.0。(Id45cd、b/413674743)

1.1.0-beta01 版本

2026 年 3 月 27 日

發布 androidx.navigationevent:navigationevent-*:1.1.0-beta01。1.1.0-beta01 版包含這些修訂項目。

API 變更

  • 在 NavigationEventDispatcher 中新增 OnForwardCompletedFallback，針對未處理的轉送導覽事件啟用預設系統行為。(Iac620、b/489138116)

1.1.0-alpha01 版本

2026 年 2 月 25 日

發布 androidx.navigationevent:navigationevent-*:1.1.0-alpha01。1.1.0-alpha01 版包含這些修訂項目。

新功能

  • 在 NavigationEvent-Compose 中支援所有 Kotlin Multiplatform (KMP) 目標。將擁有者解析與 LocalView 解除連結，讓平台主機提供預設 LocalNavigationEventDispatcherOwner，同時將 LocalView 維持為 Android 上的安全備援。(Iae980、b/434940570、Iccf58)

API 變更

  • 新增 NavigationEvent.toBackEvent() 和 BackEvent.toNavigationEvent() 擴充功能函式，在 Android 的 BackEvent 和 NavigationEvent 之間轉換。(Ie3b71、b/477001292)

1.0 版本

1.0.2 版

2026 年 1 月 28 日

發布 androidx.navigationevent:navigationevent-*:1.0.2。1.0.2 版包含這些修訂項目。

修正錯誤

  • 修正在 Android Studio 預先發布版中使用 NavigationEventHandler 時發生的當機問題。處理常式現在會偵測檢查模式，且不會執行任何動作，因此 Preview 可以在沒有提供調度器的情況下進行算繪。(I370f2、b/454313986)。

1.0.1 版

2025 年 12 月 3 日

發布 androidx.navigationevent:navigationevent-*:1.0.1。1.0.1 版包含這些修訂項目。

修正錯誤

  • 修正處置子項 NavigationEventDispatcher (例如使用 rememberNavigationEventDispatcherOwner() 建立的項目) 時的 ConcurrentModificationException。(ec68a9、b/454363524)

1.0.0 版

2025 年 11 月 19 日

發布 androidx.navigationevent:navigationevent-*:1.0.0。1.0.0 版包含這些修訂項目。

1.0.0 版的主要功能：

Navigation Event 程式庫現已穩定運作！Navigation Event 是 AndroidX 程式庫，用於處理系統層級的互動，例如 Android (和其他平台) 中的系統返回和預測返回手勢。

  • 如要處理 NavigationEvent，您可以實作自己的 NavigationEventHandler，覆寫所需函式。接著，您需要將處理常式新增至 NavigationEventDispatcher。從 Activity 1.12.0 版本開始，ComponentActivity 會實作新的 NavigationEventDispatcherOwner 介面，提供可供使用的調度器：

    // 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 模組提供方便的 Compose 函式 NavigationBackHandler，可自動將處理常式連結至最接近的 LocalNavigationEventDispatcherOwner 的 NavigationEventDispatcher，並允許開發人員以參數形式提供所需行為：

    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 中提升出來)。

  • 無論是 Compose 或非 Compose 案例，每個 NavigationEventDispatcher 都能提供父項調度器。開發人員可藉此建立階層式結構，由單一父項管理多個調度員。有了父項，處理可能需要停用或處置的調度員群組就相對簡單：

    // 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() 
)

  • 程式庫也支援透過 NavigationEventInput 直接向 NavigationEventDispatcher 提供信號。NavigationEventInput 可做為導覽系統的「輸入」端，將平台專屬事件 (例如系統返回手勢或按鈕點擊) 轉換為可傳送至 NavigationEventDispatcher 的標準化事件。navigationevent:navigationevent 模組目前提供 2 個 NavigationEventInput：更通用的 DirectNavigationEventInput，可分派任何事件；以及 Android 專用的 OnBackInvokedInput，可讓 NavigationEventDispatcher 支援系統返回和預測返回手勢。如果您實作自己的調度器 (而非使用 ComponentActivity 提供的調度器)，則必須手動新增輸入內容：

    val dispatcher = NavigationEventDispatcher()

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

1.0.0-rc01 版

2025 年 11 月 5 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-rc01。1.0.0-rc01 版包含這些修訂項目。

1.0.0-beta01 版

2025 年 10 月 8 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-beta01。1.0.0-beta01 版包含這些修訂項目。

API 變更

  • 修正 NavigationEvent.touchX 和 NavigationEvent.touchY 的 FloatRange 註解。這些值代表絕對像素座標，沒有 1.0 上限。(I4b205、b/445989313)
  • 將 NavigationEventDispatcherOwner 可組合函式重構為 rememberNavigationEventDispatcherOwner。函式現在會直接傳回 NavigationEventDispatcherOwner。如要將這個擁有者提供給子組合，請使用 CompositionLocalProvider。(I874b2、b/444446629)

1.0.0-alpha09 版本

2025 年 9 月 24 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha09。1.0.0-alpha09 版包含這些修訂項目。

API 變更

  • 請直接使用 NavigationEventTransitionState.Idle 單例模式物件，而非例項化 Idle()。(Ic7d9e、b/444734264)
  • 將便利建構函式設為內部函式；透過公開 NavigationEventDispatcher.history 取得例項，而非直接建構。(I3b7e0、b/444734264)
  • 必須透過 rememberNavigationEventState 建立 NavigationEventState；建構函式現在是內部函式。(Ie143c、b/444734264)
  • 採用 onBackCompletedFallback，並取代 fallbackOnBackPressed 用法和建構函式參數。行為不變，只會在完成且未處理的返回事件上叫用。(Idabe9、b/444734264)
  • NavigationEventHistory(mergedHistory, currentIndex) 的主要建構函式現在是 internal。外部消費者必須使用公開建構函式 (空白建構函式或以分割區為基礎的建構函式)，才能建立例項。(I1c047、b/444734264)
  • 讓 View.setViewTreeNavigationEventDispatcherOwner 接受可為空值的擁有者 (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 編譯器最佳化重組作業。(If78c7、b/444734264)
  • 已更新 navigationevent-compose 處理常式 API，NavigationEventHandler 和 NavigationBackHandler (以及變體) 現在支援新的多載，可接受升高的 NavigationEventState。簡單的超載 (採用 currentInfo) 會保留，並在內部使用這個新的狀態模型。(Ic3251、b/444734264)
  • 將新的 @Stable NavigationEventState<T> 狀態容器新增至 navigationevent-compose 程式庫。這個物件會結合本機記錄和本機手勢狀態，並成為 rememberNavigationEventState 和 NavigationEventHandler 之間的主要連結。(Ifb69f、b/444734264)
  • 在 NavigationEventHandler 中新增公開的唯讀 transitionState: TransitionState 屬性。處理常式現在會維護自己的轉移狀態，外部系統可以觀察。(I9acd2、b/444734264)
  • 導入新的 TransitionState 密封類別。這會做為觀察手勢狀態的核心 API，與瀏覽記錄分開。(Id4beb、b/444734264)
  • 在 NavigationEventHandler 上，將 currentInfo、backInfo 和 forwardInfo 公開為唯讀屬性。(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 編譯器最佳化重組作業。(I7c112)
  • 透過有趣的介面改善 Java 人體工學，以進行後續完成回溯。(I8a860)
  • 將 onHasEnabledHandlerChanged 重新命名為 onHasEnabledHandlersChanged。這項說明指出，回呼會回報所有處理常式的集體啟用狀態，而不只是其中一個。(I1af61、b/443711297)
  • 從 NavigationEventDispatcher; 移除 hasEnabledHandler()，改用 NavigationEventInput.onHasEnabledHandlersChanged。(Idef72、b/443711297)
  • 在 NavigationEventInput 中新增 onInfoChanged 回呼，通知監聽器導覽記錄的變更。這會提供目前、返回和轉送堆疊的完整脈絡，讓「輸入」可對脈絡資訊做出反應。(I69a8b、b/443282983)
  • 將 NavigationEvent's swipeEdge 設為 @IntDef (Icee54、b/443950342)
  • 在 NavigationEventDispatcher.addInput 中新增 priority 參數，將調度器範圍限定為一個優先順序；現在只有在該優先順序的回呼變更時，才會觸發 onHasEnabledCallbacksChanged 等事件。(I3e488、b/443711297)
  • 為求明確起見，將 NavigationEventDispatcher 參數從 parentDispatcher 重新命名為父項。(Id4f1f、b/443801782)
  • 為 Java 使用者移除 NavigationEventPriority，改用 @IntDef (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 版本

2025 年 9 月 10 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha08。1.0.0-alpha08 版包含這些修訂項目。

新功能

  • 推出以 Lambda 為主的 NavigationEventHandler API，取代以 Flow 為主的處理常式。使用簡單的回呼處理返回和前進手勢，不必收集流程，減少樣板並避免取消問題。提供 NavigationBackHandler 和 NavigationForwardHandler 做為目標便利 API。移除以 Flow 為基礎的 NavigationEventHandler，然後遷移至新的回呼。(I23bac、b/436248277)
  • 允許被動接聽程式透過合併的返回資訊存取完整的返回導覽堆疊。啟用 UI 即可轉譯預覽畫面和巢狀導覽記錄，而不僅限於最上層的回呼。(I7a510、b/436248277)
  • 導入明確的返回/目前/前進模型，釐清導覽狀態，並支援使用巢狀處理常式進行前進導覽。(Ib86da、b/420443609)
  • 將 onForward* 方法和 isForwardEnabled 新增至 NavigationEventCallback。(Ic100f、b/436248290)
  • 在 NavigationEventInput 中新增向前導覽支援。(I5734b)

API 變更

  • 使用 TestNavigationEventCallback 啟用正向導覽事件測試。使用 isForwardEnabled 和 onForward* 勾點。(I21fb5、b/420443609)
  • 在 NavEvent 中，將 onEvent* 回呼重新命名為 onBack*。(I228b3、b/436248290)
  • 將 SwipeEdge 轉換為內嵌類別。(Id5e01)
  • 讓 navigationevent 程式庫與 Java 互通。現在可透過 Java 程式碼完整存取所有公開 API，完美整合至混合語言或僅使用 Java 的專案。(Ibc944、I5465f、I9fb1e、b/440532890、b/443040294)
  • 將 NavigationEventCallback 重新命名為 NavigationEventHandler，以釐清 API 角色。這項變更可更貼切地反映類別用途，也就是處理多階段導覽手勢。對應的 addCallback 方法現在是 addHandler。(I2492a、b/443040331)

修正錯誤

  • 防止在向前瀏覽時執行返回後備。(I74814、b/436248290)
  • 新增對預測前向導覽的支援。NavigationEvent API 現在可處理返回和前進手勢，為兩種導覽方向提供一致的動畫。(Idc98c、b/436248290)
  • 防止在移除子項 NavigationEventDispatcherOwner 時，導致重組期間發生 IllegalStateException 異常終止。(Iff50c、b/412629020)
  • 被動式事件監聽器現在可以透過合併的返回資訊存取完整的返回堆疊，讓 UI 顯示預覽畫面和巢狀導覽記錄，而不僅限於最頂端的回呼。(I7a510、b/436248277)

1.0.0-alpha07 版本

2025 年 8 月 27 日

發布 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)
  • 在 NavigationEventInput.onHasEnabledCallbacksChanged 中新增 @EmptySuper。(If9853)
  • 在 NavigationEventInputHandler 中實作 onAttach。(I03648)
  • 在 NavigationEventInputHandler 中實作 onDetach。(I03648)
  • 建立時預設啟用 NavigationEventCallback。(Ic0188)
  • 以 NavigationEventInput.onHasEnabledCallbacksChanged 取代 NavigationEventInput.addOnHasEnabledCallbacksChangedCallback。 (I64e93)
  • 要求 NavigationEventDispatcher.addInput 的主執行緒。(Ic2930)
  • 要求 NavigationEventDispatcher.removeInput 的主執行緒。(Ic2930)
  • 移除 Dispatcher.addOnHasEnabledCallbacksChangedCallback。以 Dispatcher.onHasEnabledCallbacksChanged 取代。(Ida3e3、b/436530096)

修正錯誤

  • 修正錯誤：新增已附加的處理常式或移除未附加的處理常式時，會觸發不正確的生命週期邏輯。(I9e47b)

1.0.0-alpha06 版本

2025 年 8 月 13 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha06。1.0.0-alpha06 版包含這些修訂項目。

新功能

被動監聽器 API

您現在可以從任何導覽主機傳遞自訂脈絡資訊，並從 UI 中的任何位置被動監聽手勢狀態變化。這項設定會啟用預測返回和其他手勢導覽的脈絡感知動畫。

這項功能包含兩個部分：

  1. 提供資訊 - 使用 NavigationEventInfo 傳送自訂資料。
  2. 消耗狀態 - 使用 dispatcher.state (NavigationEventState) 觀察手勢進度和情境。
  • NavigationEventCallback 現在會公開 setInfo(currentInfo, previousInfo) 方法，以便在一次呼叫中設定手勢內容 (I1d5e7、b/424470518)。
  • NavigationEventHandler 新增了接受 currentInfo 和 previousInfo 的新多載，成為在 Compose 應用程式中提供內容的主要 API (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)。這些以 StateFlow 為基礎的 API 可讓任何 UI 觀察手勢進度和情境資料，不必直接處理事件。

範例：

  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 */ }
  }

  • 在 NavigationEventState 中新增 progress 屬性 (I7b196)，該屬性會在進行中時傳回 latestEvent.progress，否則傳回 0F：

    val progress = state.progress

  • 新增 NavigationEventDispatcherOwner 可組合項，以階層方式建立、連結及處置 NavigationEventDispatcher 執行個體。啟用動態控制調度器的啟用狀態和自動清除作業。

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

API 變更

  • isPassthrough 參數已從 NavigationEventCallback 中移除。(I99028、b/424470518)
  • NavigationEventState 建構函式現在是內部函式。如要進行測試，請透過 DirectNavigationEventInputHandler 更新狀態 (預設為 Idle)。呼叫 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)
  • NavigationEventInputHandler 中的 send* 函式已將前置字元重新命名為 handle*。(Iffcaf)
  • OnBackInvokedInputHandler 現在會擴充新推出的 abstract NavigationInputHandler。(Ib45aa)
  • 變更 NavigationEventDispatcherOwner，要求使用父項調度器，您必須明確傳遞 null 才能建立根調度器。(Ia6f64、b/431534103)

修正錯誤

  • 避免在 NavigationEventDispatcher.dispose() 中複製集合，藉此提升效率。(I4ab09)
  • 修正 NavigationEventHandler 無法正確回應啟用狀態變更的問題。(Ia5268、I19bec、I5be5c、b/431534103)

文件更新

  • KDocs 擴充功能：NavigationEvent 擴充功能，說明其做為統一事件包裝函式的角色，以及不同導覽類型 (手勢、點擊) 的詳細屬性行為。(I91e8d)
  • 更新系統返回處理 Compose API (BackHandler、PredictiveBackHandler、NavigationEventHandler) 的說明文件，特別說明回呼順序相關行為。(I7ab94)

依附元件更新

  • NavigationEvent 現在依附於 Compose Runtime 1.9.0-beta03，可讓 navigationevent-compose 構件支援所有 KMP 目標。(Ia1b87)

1.0.0-alpha05 版本

2025 年 7 月 30 日

發布 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

此外，NavigationEventCallback 上的 isEnabled 屬性現在會遵守相關聯的調度器啟用狀態。也就是說，只有在回呼本身及其調度器 (包括其祖先) 都已啟用時，回呼才會視為已啟用，確保回呼啟動作業的階層式控制項一致。(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() 方法，可正確清理調度器及其子項。呼叫 dispose() 會停止接聽程式，防止記憶體洩漏、遞迴處置所有子項調度器、移除向調度器註冊的所有回呼，並取消連結父項。這可確保在不再需要調度器時，系統會正確釋出資源。(I9e985)

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

如果對已處置的調度器呼叫任何公開方法，系統會立即擲回 IllegalStateException。這樣可避免無聲失敗，並協助開發人員在開發期間找出不當用法。(Ic2dc3)

  val callback2 = TestNavigationEventCallback()

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

注意：我們將在 aosp/3692572 中推出新的 NavigationEventDispatcherOwner Composable，自動管理 Compose UI 中的子項調度器。不過，這項變更並未納入目前版本，預計會在下一個版本中推出。

Navigation 測試程式庫

  • 新增 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)
  • 在 NavigationEvent 中，將 @FloatRange 註解新增至 touchX、touchY 和 progress 欄位，以便在編譯時間強制執行有效的值範圍，並提升 API 安全性。(Iac0ec)

1.0.0-alpha04 版本

2025 年 7 月 2 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha04。1.0.0-alpha04 版包含這些修訂項目。

修正錯誤

  • 使用 implementedInJetBrainsFork 進行 navigationevent-compose，並新增 commonStubs 目標來配合 Compose 慣例。JetBrains 要求變更。(f60c79)
  • 修正 Kotlin/Native 的 Compose 編譯器外掛程式應用程式，確保正確產生 Stub。公用 API 或行為不會受到影響。(1890c9)

1.0.0-alpha03 版本

2025 年 6 月 18 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha03。1.0.0-alpha03 版包含這些修訂項目。

新功能

  • 推出新的 navigationevent-compose 模組，支援 navigationevent 程式庫中的 Jetpack Compose 功能。(980d78)
  • NavigationEvent Compose 新增了 LocalNavigationEventDispatcherOwner 本機組合。並傳回可為空值的值，以更準確地判斷這個值是否可用在目前組合中。如果找不到基礎擁有者，NavigationEventHandler 現在會擲回錯誤。(62ffda)
  • NavigationEvent Compose 新增了 NavigationEventHandler 可組合函式，可處理 (預測返回手勢) 事件。它提供 NavigationEvent 物件的 Flow，這些物件必須在您提供的暫停 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 版

2025 年 6 月 4 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

API 變更

  • 使用預設引數取代 NavigationEventDispatcher 的次要建構函式。(I716a0)
  • 從 NavigationEventCallback 移除優先順序屬性。請改為將優先順序傳遞至 NavigationEventDispatcher.addCallback()。(I13cae)

修正錯誤

  • 修正可能在呼叫 NavigationEventCallback.remove() 時發生的 ConcurrentModificationException，因為同時修改了可關閉項目的內部清單。(b/420919815)

1.0.0-alpha01 版

2025 年 5 月 20 日

發布 androidx.navigationevent:navigationevent-*:1.0.0-alpha01。1.0.0-alpha01 版包含這些修訂項目。

新功能

  • androidx.navigationevent 程式庫提供 KMP 優先的 API，可處理系統返回動作和預測返回。NavigationEventDispatcher 可做為通用 API，用於註冊一或多個 NavigationEventCallback 執行個體，以接收系統返回事件。
  • 這個層級位於 androidx.activity 中先前發布的 API 下方，旨在取代較高層級元件中的 Activity API，或直接使用 Android 架構 OnBackInvokedDispatcher API，且較不具主觀性。androidx.activity API 已在 Activity 1.12.0-alpha01 中，以 Navigation Event API 為基礎重新編寫。