設定調度員

如要實作穩固的導覽系統，應用程式需要以集中方式處理返回手勢和其他導覽信號。本頁說明如何使用 NavigationEventDispatcher 協調及發布應用程式中的導覽事件。

宣告 NavigationEventDispatcher

NavigationEventDispatcher 是 NavigationEvent 程式庫的核心元件。這個元件可做為事件中樞，將返回手勢和導覽轉場等導覽相關事件，調度至應用程式中已註冊的事件監聽器。元件可以訂閱這些事件，以便對導覽變更或其他系統導覽動作做出反應。

您應透過 NavigationEventDispatcherOwner 提供 NavigationEventDispatcher 執行個體。這樣一來，應用程式的不同部分就能存取同一個調度工具，並以一致且協調的方式觀察導覽事件。

class MyComponent: NavigationEventDispatcherOwner {
    override val navigationEventDispatcher: NavigationEventDispatcher =
        NavigationEventDispatcher()
}
NavEventSnippets.kt

如果您位於 ComponentActivity 內，則可以擷取為您提供的調度工具，而不必實作自己的調度工具。

class MyCustomActivity : ComponentActivity() {
    fun addMyHandler() {
        // navigationEventDispatcher provided by the ComponentActivity
        navigationEventDispatcher.addHandler(myNavigationEventHandler)
    }
}
NavEventSnippets.kt

新增NavigationEventInput

註冊處理常式後，您就可以接收事件了。不過，您必須使用 NavigationEventInput 提供事件的來源。

NavigationEventInput 是平台專屬元件，可接收原始系統輸入內容，並將其轉譯為標準 NavigationEvent，以便傳送至 NavigationEventDispatcher。

以下範例是 NavigationEventInput 的自訂實作：

public class MyInput : NavigationEventInput() {
    @MainThread
    public fun backStarted(event: NavigationEvent) {
        dispatchOnBackStarted(event)
    }

    @MainThread
    public fun backProgressed(event: NavigationEvent) {
        dispatchOnBackProgressed(event)
    }

    @MainThread
    public fun backCancelled() {
        dispatchOnBackCancelled()
    }

    @MainThread
    public fun backCompleted() {
        dispatchOnBackCompleted()
    }
}
NavEventSnippets.kt

接著，將該輸入內容提供給調度工具：

navigationEventDispatcher.addInput(MyInput())
NavEventSnippets.kt

使用 dispose() 清除資源

為避免動態 UI 發生記憶體流失，每當建立的 NavigationEventDispatcher 執行個體所連結的元件遭到刪除時，都必須使用 dispose() 方法，明確從階層中移除該執行個體：

navigationEventDispatcher.dispose()
NavEventSnippets.kt

dispose() 方法會反覆移除調度工具及其所有子系 (子項和孫項)，確保串聯清除，保證所有相關聯的處理常式都會從共用系統取消註冊。

調度工具階層和控制

NavigationEventDispatcher 支援父項-子項階層，可讓巢狀結構深層的 UI 元件 (例如巢狀 NavHost 或對話方塊) 參與導覽事件處理。

建立子調度工具

在建構期間傳遞對其父項調度工具的參照，即可建立子項調度工具。階層中的所有調度工具都會共用相同的 NavigationEventProcessor，以根據優先順序維護全域後進先出 (LIFO) 事件排序。

階層式啟用

調度工具包含 isEnabled 屬性，可讓開發人員一次啟用或停用整個處理常式子樹。

如果停用父項調度工具 (isEnabled = false)，系統會忽略與該父項及其任何子項相關聯的所有處理常式，無論個別啟用狀態為何。