navigationevent
最近更新時間 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
2025 年 7 月 30 日 | - | - | - | 1.0.0-alpha05 |
宣告依附元件
如要為 navigationevent 新增依附元件,必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。
在應用程式或模組的 build.gradle
檔案中,新增所需構件的依附元件:
Groovy
dependencies { implementation "androidx.navigationevent:navigationevent:1.0.0-alpha05" }
Kotlin
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 的一部分。