本頁面由 Cloud Translation API 翻譯而成。

navigationevent

Navigation Event 程式庫提供 KMP 優先的 API，可處理系統返回鍵和預測返回手勢。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2025 年 8 月 13 日	-	-	-	1.0.0-alpha06

宣告依附元件

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

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

Groovy

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

Kotlin

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

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 文件。

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

1.0 版本

1.0.0-alpha06 版本

2025 年 8 月 13 日

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

新功能

被動監聽器 API

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

這項功能包含兩部分：

提供資訊 - 使用 NavigationEventInfo 傳送自訂資料。
消耗狀態 - 使用 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、 Ifed40 I3897c、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)

Google 文件更新

KDocs for 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 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)
在 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 編譯器外掛程式應用程式，確保正確產生存根。不會影響公開 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 可組合函式，可處理 (預測返回手勢) 事件。提供 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 版

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 已在 Navigation Event API 的基礎上重新編寫，成為 Activity 1.12.0-alpha01 的一部分。