Configurar um agente

Para implementar um sistema de navegação robusto, o app precisa de uma maneira centralizada de processar gestos de retorno e outros indicadores de navegação. Nesta página, descrevemos como usar o NavigationEventDispatcher para coordenar e distribuir esses eventos de navegação no seu aplicativo.

Declarar um NavigationEventDispatcher

O NavigationEventDispatcher é o componente central da biblioteca NavigationEvent. Ele funciona como um hub de eventos que envia eventos relacionados à navegação, como gestos de retorno e transições de navegação, para listeners registrados no seu app. Os componentes podem se inscrever nesses eventos para reagir a mudanças de navegação ou outras ações de navegação orientadas pelo sistema.

Forneça instâncias NavigationEventDispatcher usando um NavigationEventDispatcherOwner. Isso garante que diferentes partes do seu app possam acessar o mesmo dispatcher e observar eventos de navegação de maneira consistente e coordenada.

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

Se você estiver em um ComponentActivity, em vez de implementar seu próprio dispatcher, recupere o que foi fornecido.

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

Adicionar um NavigationEventInput

Agora que você registrou o manipulador, está tudo pronto para receber eventos. No entanto, é necessário fornecer uma fonte de onde os eventos são gerados com NavigationEventInput.

NavigationEventInput é o componente específico da plataforma que recebe a entrada bruta do sistema e a traduz em um NavigationEvent padrão para ser enviado ao NavigationEventDispatcher.

O exemplo a seguir é uma implementação personalizada de um 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

Em seguida, forneça essa entrada ao seu dispatcher:

navigationEventDispatcher.addInput(MyInput())
NavEventSnippets.kt

Limpar recursos com dispose()

Para evitar vazamentos de memória em uma interface dinâmica, cada instância NavigationEventDispatcher criada precisa ser removida explicitamente da hierarquia usando o método dispose() quando o componente a que ela está vinculada é destruído:

navigationEventDispatcher.dispose()
NavEventSnippets.kt

O método dispose() garante uma limpeza em cascata removendo de forma iterativa o dispatcher e todos os descendentes dele (filhos e netos), garantindo que todos os gerenciadores associados sejam removidos do registro do sistema compartilhado.

Hierarquia e controle do dispatcher

O NavigationEventDispatcher oferece suporte a uma hierarquia pai-filho, permitindo que componentes aninhados em uma interface (como NavHosts ou caixas de diálogo aninhadas) participem do processamento de eventos de navegação.

Criar um dispatcher secundário

Um dispatcher filho é criado transmitindo uma referência ao dispatcher pai durante a construção. Todos os distribuidores em uma hierarquia compartilham o mesmo NavigationEventProcessor para manter uma ordenação global de eventos último a entrar, primeiro a sair (LIFO) com base na prioridade.

Ativação hierárquica

O dispatcher inclui uma propriedade isEnabled que permite aos desenvolvedores ativar ou desativar uma subárvore inteira de manipuladores de uma só vez.

Quando um dispatcher principal é desativado (isEnabled = false), todos os manipuladores associados a ele e a qualquer um dos filhos são ignorados, independente do estado ativado individual.