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 aplicativo.

Declarar um NavigationEventDispatcher

O NavigationEventDispatcher é o componente central da biblioteca NavigationEvent. Ele atua como um hub de eventos que envia eventos relacionados à navegação, como gestos de voltar e transições de navegação, para listeners registrados no 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 de NavigationEventDispatcher usando um NavigationEventDispatcherOwner. Isso garante que diferentes partes do app possam acessar o mesmo agente 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, poderá recuperar o que foi fornecido para você.

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

Adicionar um NavigationEventInput

Agora que você registrou o gerenciador, está tudo pronto para receber eventos. No entanto, é necessário fornecer uma origem 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 a 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 agente:

navigationEventDispatcher.addInput(MyInput())
NavEventSnippets.kt

Limpar recursos com dispose()

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

navigationEventDispatcher.dispose()
NavEventSnippets.kt

O método dispose() garante uma limpeza em cascata ao remover iterativamente o agente de envio e todos os descendentes (filhos e netos), garantindo que todos os gerenciadores associados sejam cancelados do sistema compartilhado.

Hierarquia e controle do agente de envio

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 agente filho

Um dispatcher filho é criado transmitindo uma referência ao dispatcher pai durante a construção. Todos os dispatchers em uma hierarquia compartilham o mesmo NavigationEventProcessor para manter uma ordenação de eventos global LIFO (último a entrar, primeiro a sair) 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 gerenciadores de uma só vez.

Quando um dispatcher pai é desativado (isEnabled = false), todos os gerenciadores associados a ele e aos filhos dele são ignorados, independentemente do estado de ativação individual.