navigationevent

宣告依附元件

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

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

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

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

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 文件。

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

1.0 版本

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 的一部分。