navigationevent

  
A biblioteca Navigation Event fornece uma API KMP-first para processar o retorno do sistema e o retorno preditivo.
Atualização mais recente Versão estável Versão candidata a lançamento Versão Beta Versão Alfa
19 de novembro de 2025 1.0.0 - - -

Declarar dependências

Para adicionar uma dependência a navigationevent, adicione o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários ao arquivo build.gradle do seu app ou módulo:

Groovy

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

Kotlin

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

Para mais informações sobre dependências, consulte Adicionar dependências de build.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Não há notas de versão para este artefato.

Versão 1.0

Versão 1.0.0

19 de novembro de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0. A versão 1.0.0 contém estes commits.

Principais recursos da versão 1.0.0:

A biblioteca Navigation Event agora está na versão estável. Navigation Event é a biblioteca AndroidX para processar interações no nível do sistema, como voltar e voltar de forma preditiva no Android (e em outras plataformas).

  • Para processar NavigationEvents, implemente seu próprio NavigationEventHandler que substitui as funções desejadas. Em seguida, adicione o manipulador a um NavigationEventDispatcher. A partir da versão Activity 1.12.0, o ComponentActivity implementa a nova interface NavigationEventDispatcherOwner, que fornece um dispatcher pronto para uso :

    // The NavigationEventInfo provides information about a navigation state
object CurrentInfo : NavigationEventInfo()

// you can retrieve this from any component that is a NavigationEventDispatcherOwner
// or you can instantiate your own custom dispatcher
val dispatcher = myActivity.navigationEventDispatcher

val myHandler = object : NavigationEventHandler<NavigationEventInfo>(
            initialInfo = CurrentInfo,
            isBackEnabled = true
        ) {
            override fun onBackStarted(event: NavigationEvent) {
                // Prepare for the back event
            }

            override fun onBackProgressed(event: NavigationEvent) {
                // Use event.progress for predictive animations
            }

            // This is the required method for final event handling
            override fun onBackCompleted() {
                // Complete the back event
            }

            override fun onBackCancelled() {
                // Cancel the back event
            }
        }

dispatcher.addHandler(myHandler)

  • O módulo navigationevent:navigationevent-compose fornece uma função de composição conveniente NavigationBackHandler que conecta automaticamente o manipulador ao NavigationEventDispatcher do LocalNavigationEventDispatcherOwner mais próximo e permite que os desenvolvedores forneçam o comportamento desejado como parâmetros:

    object CurrentInfo : NavigationEventInfo()
object PreviousInfo : NavigationEventInfo()

val navEventState = rememberNavigationEventState(
  currentInfo = CurrentInfo,
  backInfo = PreviousInfo
)

// Inside composition
NavigationBackHandler(
    State = navEventState,
    isBackEnabled = true,
    // optional
    onBackCancelled = { // Cancel the back event },
    // required
    onBackCompleted = { // Complete the back event } ,
)

Usar esse padrão no Compose facilita muito a elevação do NavigationEventState e permite que ele seja observado por diferentes elementos combináveis (por exemplo, no caso do Navigation3, em que é possível elevar o estado do NavDisplay).

  • Cada NavigationEventDispatcher pode fornecer um dispatcher principal, tanto para os casos de composição quanto para os de não composição. Isso permite que os desenvolvedores criem uma estrutura hierárquica em que vários despachantes podem ser gerenciados por um único pai. Ter um pai torna o processamento de grupos de distribuidores que podem precisar ser desativados ou descartados relativamente simples:

    // Non-Compose
val parentDispatcher = NavigationEventDispatcher()
val childDispatcher = NavigationEventDispatcher(parent = parentDispatcher)

// Compose
val composeChildDispatcher = rememberNavigationEventDispatcher(
    // This defaults to `LocalNavigationEventDispatcherOwner.current`
    // Must explicitly provide null to have an unparented dispatcher created here
    parent = NavigationEventDispatch() 
)

  • A biblioteca também permite fornecer indicadores diretamente ao NavigationEventDispatcher usando um NavigationEventInput. O NavigationEventInputs atua como o lado de "entrada" do sistema de navegação, traduzindo eventos específicos da plataforma (como gestos de retorno do sistema ou cliques de botão) em eventos padronizados que podem ser enviados a um NavigationEventDispatcher. No momento, o módulo navigationevent:navigationevent oferece dois NavigationEventInputs: um DirectNavigationEventInput mais genérico para permitir que qualquer evento seja enviado e um OnBackInvokedInput específico do Android que permite que um NavigationEventDispatcher seja compatível com o retorno do sistema e o gesto de retorno preditivo. Se você implementar seu próprio dispatcher (em vez de usar o fornecido por ComponentActivity), adicione manualmente sua entrada:

    val dispatcher = NavigationEventDispatcher()

dispatcher.addInput(DirectNavigationEventInput())
dispatcher.addInput(OnBackInvokedDefaultInput(invoker))

Versão 1.0.0-rc01

5 de novembro de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-rc01. A versão 1.0.0-rc01 contém estes commits.

Versão 1.0.0-beta01

8 de outubro de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-beta01. A versão 1.0.0-beta01 contém estes commits.

Mudanças na API

  • Correção da anotação FloatRange para NavigationEvent.touchX e NavigationEvent.touchY. Esses valores representam coordenadas de pixel absolutas e não têm um limite superior de 1.0. (I4b205, b/445989313).
  • Refatore o elemento combinável NavigationEventDispatcherOwner para rememberNavigationEventDispatcherOwner. Agora, a função retorna o NavigationEventDispatcherOwner diretamente. Para fornecer esse proprietário a uma subcomposição, use CompositionLocalProvider. (I874b2, b/444446629)

Versão 1.0.0-alpha09

24 de setembro de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha09. A versão 1.0.0-alpha09 contém estes commits.

Mudanças na API

  • Use o objeto singleton NavigationEventTransitionState.Idle diretamente em vez de instanciar Idle(). (Ic7d9e, b/444734264).
  • Torne os construtores de conveniência internos e obtenha instâncias usando NavigationEventDispatcher.history público em vez de construção direta. (I3b7e0, b/444734264)
  • É necessário criar NavigationEventState usando rememberNavigationEventState. O construtor agora é interno. (Ie143c, b/444734264).
  • Adote onBackCompletedFallback e substitua os usos de fallbackOnBackPressed e o parâmetro do construtor. O comportamento não muda. É invocado apenas em eventos de retorno concluídos e não processados. (Idabe9, b/444734264)
  • O construtor principal de NavigationEventHistory(mergedHistory, currentIndex) agora é internal. Os consumidores externos precisam usar os construtores públicos (o vazio ou o baseado em partição) para criar instâncias. (I1c047, b/444734264)
  • Fazer com que View.setViewTreeNavigationEventDispatcherOwner aceite um proprietário anulável (Ic9eb6, b/444436762).
  • NavigationEventInfo agora é um abstract class em vez de um interface. Atualize todas as implementações personalizadas para herdar da classe (por exemplo, data class MyInfo : NavigationEventInfo()). (I1e59c, b/444734264)
  • A propriedade NavigationEventDispatcher.state e a função getState<T>() legadas foram removidas. Use os novos fluxos separados dispatcher.transitionState (para progresso do gesto) e dispatcher.history (para a pilha de navegação). (Ic2ceb, b/444734264)
  • O callback NavigationEventInput.onInfoChanged(...) é substituído. Implemente o novo callback onHistoryChanged(history: NavigationEventHistory) para receber atualizações como um único objeto NavigationEventHistory. (I23e0b, b/444734264)
  • Introduzir um novo NavigationEventDispatcher.history global StateFlow. Esse fluxo não genérico permite que os observadores se inscrevam apenas para receber mudanças na pilha de navegação e permanece estável durante o progresso do gesto. É a contrapartida de transitionState. (I1db10, b/444734264).
  • Introduzir um novo NavigationEventDispatcher.transitionState global StateFlow. Esse fluxo não genérico permite que os observadores se inscrevam apenas no estado do gesto físico (Idle/InProgress), separado do histórico. (I171fa, b/444734264)
  • Apresente a classe NavigationEventHistoryState. Essa será a API principal para observar o histórico de informações de navegação, separada do estado do gesto. (I81ca5, b/444734264)
  • Agora, NavigationEvent está marcado como @Immutable, permitindo que o Compose Compiler otimize recomposições. (If78c7, b/444734264).
  • As APIs de manipulador navigationevent-compose foram atualizadas. NavigationEventHandler e NavigationBackHandler (e variantes) agora são compatíveis com uma nova sobrecarga que aceita NavigationEventStates içados. As sobrecargas simples (que usam currentInfo) são preservadas e agora usam esse novo modelo de estado internamente. (Ic3251, b/444734264)
  • Adicione o novo @Stable NavigationEventState<T> ao navigationevent-compose. Esse objeto combina o histórico local com o estado do gesto local e será o link principal entre rememberNavigationEventState e NavigationEventHandler. (Ifb69f, b/444734264)
  • Adicione uma nova propriedade transitionState: TransitionState pública e somente leitura a NavigationEventHandler. Os manipuladores agora mantêm o próprio estado de transição, que pode ser observado por sistemas externos. (I9acd2, b/444734264).
  • Apresente a nova classe sealed TransitionState. Essa será a API principal para observar o estado do gesto, separada do histórico de navegação. (Id4beb, b/444734264).
  • Exponha currentInfo, backInfo e forwardInfo como propriedades públicas somente leitura em NavigationEventHandler. (Ia7636, b/444734264)
  • As implementações de NavigationEventHandler agora precisam fornecer um valor initialInfo: T ao construtor de base. (Idcfea, b/444734264)
  • Substitua OnBackInvokedInput por OnBackInvokedOverlayInput ou OnBackInvokedDefaultInput. (I5323f, b/428948766).
  • Marque NavigationEventState como @Immutable. Isso melhora a performance do Compose, garantindo que os combináveis que observam esse estado possam pular a recomposição corretamente. (I399c8)
  • Renomeie NavigationEventInfo.NotProvided para NavigationEventInfo.None; e atualize as referências. Nenhuma mudança de comportamento. (I5e2d4).
  • Agora, NavigationEventInfo está marcado como @Immutable, permitindo que o Compose Compiler otimize recomposições. (I7c112)
  • Melhorar a ergonomia do Java com uma interface divertida para substituição de conclusão de volta. (I8a860).
  • onHasEnabledHandlerChanged foi renomeado como onHasEnabledHandlersChanged. Isso esclarece que o callback informa o estado de ativação coletiva de todos os manipuladores, não apenas um. (I1af61, b/443711297)
  • Remova hasEnabledHandler() de NavigationEventDispatcher; e use NavigationEventInput.onHasEnabledHandlersChanged. (Idef72, b/443711297)
  • Adicione o callback onInfoChanged ao NavigationEventInput para notificar os listeners sobre mudanças no histórico de navegação. Isso fornece o contexto completo das pilhas atuais, de volta e para frente, permitindo que as entradas reajam às informações contextuais. (I69a8b, b/443282983)
  • Transformar o swipeEdge do NavigationEvent em um @IntDef (Icee54, b/443950342)
  • Adicione um parâmetro priority a NavigationEventDispatcher.addInput para limitar um dispatcher a uma prioridade. Eventos como onHasEnabledCallbacksChanged agora são acionados apenas quando os callbacks nessa prioridade mudam. (I3e488, b/443711297).
  • Renomeie o parâmetro NavigationEventDispatcher de parentDispatcher para parent para maior clareza. (Id4f1f, b/443801782)
  • Remoção de NavigationEventPriority em favor de @IntDef para usuários do Java (I10a9f, b/440514265).
  • Aplicar o contrato do gerenciador de navegação. Se o NavigationEventHandler definir isBackEnabled ou isForwardEnabled como true, agora você precisará substituir onBackCompleted ou onForwardCompleted, respectivamente. As implementações padrão agora geram uma exceção para evitar falhas silenciosas. (I17c62).
  • Impor valores de prioridade válidos ao adicionar manipuladores de eventos de navegação. Chamar addHandler com uma prioridade não compatível agora vai gerar um IllegalArgumentException, fornecendo feedback imediato para uso incorreto em todas as plataformas de destino. (I3c474).

Correções de bugs

  • Faça addHandler ser idempotente e ignore registros duplicados. (I052aa, b/444734264)
  • Mantenha as propriedades NavigationEventState sincronizadas durante a recomposição. (Ib3b4d, b/444734264)
  • Garanta que NavigationEventInputs receba as informações contextuais atuais (atual, voltar, avançar) imediatamente após o registro. (Ie65bf, b/443282983).

Versão 1.0.0-alpha08

10 de setembro de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha08. A versão 1.0.0-alpha08 contém estes commits.

Novos recursos

  • Introduzir uma API NavigationEventHandler baseada em lambda que substitui o manipulador baseado em fluxo. Use gestos para trás e para frente com callbacks simples em vez de coletar fluxos, reduzindo o texto clichê e evitando problemas de cancelamento. Forneça NavigationBackHandler e NavigationForwardHandler como APIs de conveniência segmentadas. Remova o NavigationEventHandler baseado em fluxo e migre para os novos callbacks. (I23bac, b/436248277).
  • Permite que ouvintes passivos acessem a pilha de retorno de navegação completa usando informações combinadas. Permite que as UIs renderizem prévias e histórico de navegação aninhado em vez de se limitarem ao callback mais alto. (I7a510, b/436248277).
  • Introduza um modelo explícito de retorno/atual/avanço para esclarecer o estado da navegação e oferecer suporte à navegação para frente com gerenciadores aninhados. (Ib86da, b/420443609)
  • Adicione métodos onForward* e isForwardEnabled a NavigationEventCallback. (Ic100f, b/436248290)
  • Adicione suporte à navegação para frente a NavigationEventInput. (I5734b).

Mudanças na API

  • Ative o teste de eventos de navegação para frente com TestNavigationEventCallback. Use os hooks isForwardEnabled e onForward*. (I21fb5, b/420443609)
  • Renomeie os callbacks onEvent* para onBack* em NavEvent. (I228b3, b/436248290)
  • Converter SwipeEdge em uma classe in-line. (Id5e01).
  • Faça com que a biblioteca navigationevent seja interoperável com Java. Todas as APIs públicas agora estão totalmente acessíveis no código Java, permitindo a integração perfeita em projetos de linguagem mista ou somente em Java. (Ibc944,I5465f, I9fb1e, b/440532890b/443040294)
  • Esclarecemos as funções da API renomeando NavigationEventCallback para NavigationEventHandler. Essa mudança reflete melhor a finalidade da classe de processar gestos de navegação em várias etapas. O método addCallback correspondente agora é addHandler. (I2492a, b/443040331)

Correções de bugs

  • Impedir que o retorno de fallback seja executado na navegação para frente. (I74814, b/436248290).
  • Adição de suporte à navegação preditiva para frente. As APIs NavigationEvent agora processam gestos para trás e para frente, permitindo animações consistentes para as duas direções de navegação. (Idc98c, b/436248290)
  • Evitar uma falha de IllegalStateException durante a recomposição quando um NavigationEventDispatcherOwner filho é removido. (Iff50c, b/412629020)
  • Os ouvintes passivos agora podem acessar a pilha de volta completa usando informações combinadas. Isso permite que as UIs renderizem prévias e histórico de navegação aninhado em vez de se limitarem ao callback mais alto. (I7a510, b/436248277).

Versão 1.0.0-alpha07

27 de agosto de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha07. A versão 1.0.0-alpha07 contém estes commits.

Mudanças na API

  • O NavigationEventDispatcher.onHasEnabledCallbacksChanged foi removido. (I50e97).
  • Tornamos NavigationEventCallback.onEventCompleted() abstrato. (I36b38).
  • Mude os métodos NavigationEventCallback#on* para protected. Atualize o código de chamada para substituir esses valores. (I6b691).
  • Renomeie as funções DirectNavigationEventInput. (Iffb62).
  • NavigationEventInput.onAttach foi renomeado como onAdded. (I2d0b8).
  • NavigationEventInput.onDetach foi renomeado como onRemoved. (I2d0b8).
  • NavigationEventInputHandler foi renomeado como NavigationEventInput. (I676a4).
  • @EmptySuper foi adicionada a NavigationEventInput.onHasEnabledCallbacksChanged. (If9853).
  • Implemente onAttach no NavigationEventInputHandler. (I03648)
  • Implemente onDetach no NavigationEventInputHandler. (I03648)
  • Ativar o NavigationEventCallback por padrão após a criação. (Ic0188).
  • NavigationEventInput.addOnHasEnabledCallbacksChangedCallback foi substituída por NavigationEventInput.onHasEnabledCallbacksChanged. (I64e93).
  • Exigir a linha de execução principal para NavigationEventDispatcher.addInput. (Ic2930).
  • Exigir a linha de execução principal para NavigationEventDispatcher.removeInput. (Ic2930).
  • O Dispatcher.addOnHasEnabledCallbacksChangedCallback foi removido. Substitua pelo Dispatcher.onHasEnabledCallbacksChanged (Ida3e3, b/436530096)

Correções de bugs

  • Correção de um bug em que adicionar um manipulador já anexado ou remover um não anexado acionava uma lógica de ciclo de vida incorreta. (I9e47b).

Versão 1.0.0-alpha06

13 de agosto de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha06. A versão 1.0.0-alpha06 contém estes commits.

Novos recursos

API Passive Listeners

Agora, é possível transmitir informações contextuais personalizadas de qualquer host de navegação e ouvir passivamente mudanças de estado de gestos em qualquer lugar da sua interface. Isso permite animações contextuais para volta preditiva e outras navegações baseadas em gestos.

Esse recurso tem duas partes:

  1. Fornecimento de informações: use NavigationEventInfo para transmitir dados personalizados.
  2. Estado de consumo: use dispatcher.state (NavigationEventState) para observar o progresso e o contexto do gesto.
  • NavigationEventCallback agora expõe o método setInfo(currentInfo, previousInfo) para definir o contexto de gestos em uma chamada (I1d5e7, b/424470518).
  • O NavigationEventHandler adiciona uma nova sobrecarga que aceita currentInfo e previousInfo, tornando-o a API principal para fornecer contexto em apps do Compose (I6ecd3, b/424470518).

Exemplo:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher agora expõe dispatcher.state e dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). Essas APIs baseadas em StateFlow permitem que qualquer interface observe o progresso do gesto e os dados contextuais sem processar o evento diretamente.

Exemplo:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • Adicione a propriedade progress a NavigationEventState (I7b196) que retorna latestEvent.progress quando em andamento ou 0F caso contrário:

    val progress = state.progress

  • Adicione o elemento combinável NavigationEventDispatcherOwner para criar, vincular e descartar instâncias de NavigationEventDispatcher de maneira hierárquica. Ative o controle dinâmico do estado ativado do dispatcher e a limpeza automática.

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

Mudanças na API

  • O parâmetro isPassthrough foi removido da NavigationEventCallback. (I99028, b/424470518).
  • Os construtores NavigationEventState agora são internos. Para testes, atualize o estado (o padrão é Idle) usando o DirectNavigationEventInputHandler. Chame handleOnStarted ou handleOnProgressed para definir o estado como InProgress e handleOnCompleted ou handleOnCancelled para retornar a Idle. Para atualizar NavigationEventInfo, use NavigationEventCallback.setInfo. (I93dca, b/424470518)
  • Adição de parâmetros padrão a NavigationEvent para facilitar a instanciação e simplificar os testes, que devem ser usados no lugar de TestNavigationEvent. (I5dc49, I232f4)
  • Adicionamos um TestNavigationEventCallback para testar eventos de navegação com estados atuais/anteriores específicos. (Idd22e, b/424470518)
  • NavigationEventInputHandler foi transformado em uma classe abstrata para substituir o AbstractNavigationEventInputHandler anterior por uma implementação em DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924).
  • Os prefixos das funções send* em NavigationEventInputHandler foram renomeados como handle*. (Iffcaf).
  • OnBackInvokedInputHandler agora estende o NavigationInputHandler abstract recém-criado. (Ib45aa).
  • Mudança de NavigationEventDispatcherOwner para exigir um dispatcher principal em que você precisa transmitir explicitamente null para criar um dispatcher raiz. (Ia6f64, b/431534103)

Correções de bugs

  • Melhoria da eficiência ao evitar cópias de coleta em NavigationEventDispatcher.dispose(). (I4ab09).
  • Correção de um problema em que o NavigationEventHandler não respondia corretamente às mudanças no estado ativado. (Ia5268,I19bec, I5be5c, b/431534103)

Atualizações do Google Docs

  • KDocs para NavigationEvent expandido para esclarecer sua função como um wrapper de eventos unificado e detalhar o comportamento das propriedades em diferentes tipos de navegação (gestos, cliques). (I91e8d)
  • Atualizamos a documentação para APIs do Compose de processamento de volta do sistema (BackHandler, PredictiveBackHandler, NavigationEventHandler) para destacar o comportamento especificamente em relação à ordem de callback. (I7ab94, )

Atualização de dependências

  • O NavigationEvent agora depende do Compose Runtime 1.9.0-beta03, que permite que o artefato navigationevent-compose ofereça suporte a todas as metas do KMP. (Ia1b87).

Versão 1.0.0-alpha05

30 de julho de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha05. A versão 1.0.0-alpha05 contém estes commits.

Suporte à hierarquia pai-filho:

Um NavigationEventDispatcher agora pode ter despachantes pai e filho, formando uma estrutura de árvore hierárquica. Isso permite que os eventos de navegação sejam propagados e gerenciados de maneira mais flexível em componentes complexos da interface do Compose, refletindo a hierarquia estrutural da interface por meio de despachantes encadeados. (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)

A propriedade hierárquica isEnabled permite o controle de cima para baixo de um dispatcher. Quando isEnabled é definido como false em um dispatcher, ele desativa automaticamente todos os dispatchers descendentes. Esse recurso permite desativar ramificações inteiras do sistema de eventos de navegação de maneira eficiente. (I9e985).

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

Além disso, a propriedade isEnabled em NavigationEventCallback agora respeita o estado ativado do dispatcher associado. Isso significa que um callback é considerado ativado somente se ele e o dispatcher (incluindo os ancestrais) estiverem ativados, garantindo um controle hierárquico consistente sobre a ativação do callback. (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()

Um novo método dispose() foi introduzido para a limpeza adequada de despachantes e filhos deles. Chamar dispose() interrompe os listeners para evitar vazamentos de memória, descarta recursivamente todos os despachantes filhos, remove todos os callbacks registrados no despachante e desvincula do pai. Isso garante que os recursos sejam liberados corretamente quando os despachantes não forem mais necessários. (I9e985).

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

Se um método público for chamado em um dispatcher descartado, uma IllegalStateException será gerada imediatamente. Isso evita falhas silenciosas e ajuda os desenvolvedores a identificar o uso inadequado durante o desenvolvimento. (Ic2dc3).

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

Observação:vamos lançar um novo elemento combinável NavigationEventDispatcherOwner que gerencia automaticamente um dispatcher secundário na interface do Compose em aosp/3692572. No entanto, essa mudança não foi incluída na versão atual e está planejada para a próxima.

Biblioteca de testes de navegação

  • Adição do módulo navigationevent-testing para fornecer utilitários de teste dedicados à biblioteca navigationevent. (0e50b6)
  • Adicione a classe utilitária falsa TestNavigationEventCallback para testes. Ele grava chamadas de método de callback e armazena itens NavigationEvent recebidos para oferecer suporte à verificação. (4a0246)
  • Adicione a função utilitária falsa TestNavigationEvent para criar instâncias NavigationEvent com valores padrão, simplificando os testes de unidade para o processamento de eventos de navegação. (3b63f5).
  • Adicione a classe utilitária falsa TestNavigationEventDispatcherOwner para testes. Ele rastreia contagens de eventos de fallback e de mudança de estado ativado para oferecer suporte à verificação de interação em testes. (c8753e)

Mudanças na API

  • Mova NavigationEventInputHandler de androidMain para commonMain para disponibilizar no código comum do KMP. Adicione novos métodos public send* para despachar eventos. Mude as funções de envio em NavigationEventDispatcher de public para internal. Agora os usuários precisam usar NavigationEventInputHandler para enviar eventos. (Ia7114)
  • NavigationInputHandler foi renomeado como OnBackInvokedInputHandler. (I63405).

Correções de bugs

  • Refatoração de NavigationEventDispatcher para reduzir a sobrecarga, evitando alocações de listas intermediárias e melhorando o desempenho de envio de callback. (I82702, I1a9d9).
  • Adicione anotações @FloatRange aos campos touchX, touchY e progress em NavigationEvent para aplicar intervalos de valores válidos no momento da compilação e melhorar a segurança da API. (Iac0ec).

Versão 1.0.0-alpha04

2 de julho de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha04. A versão 1.0.0-alpha04 contém estes commits.

Correções de bugs

  • Usamos implementedInJetBrainsFork para navigationevent-compose e adicionamos um destino commonStubs para corresponder às convenções do Compose. Mudança solicitada pela JetBrains. (f60c79)
  • Correção da aplicação do plug-in do compilador do Compose para Kotlin/Native para garantir a geração correta de stubs. Não há impacto no comportamento ou nas APIs públicas. (1890c9)

Versão 1.0.0-alpha03

18 de junho de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha03. A versão 1.0.0-alpha03 contém estes commits.

Novos recursos

  • Introduzimos um novo módulo navigationevent-compose para oferecer suporte aos recursos do Jetpack Compose na biblioteca navigationevent. (980d78)
  • O NavigationEvent Compose adicionou uma nova composição local LocalNavigationEventDispatcherOwner. Ele retorna um valor anulável para determinar melhor se ele está disponível na composição atual. NavigationEventHandler vai gerar um erro se o proprietário não for encontrado. (62ffda)
  • O NavigationEvent Compose adicionou um novo elemento combinável NavigationEventHandler para processar eventos (gesto de volta preditivo). Ele fornece um Flow de objetos NavigationEvent que precisam ser coletados na lambda de suspensão fornecida 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
  }
}

Mudanças na API

  • Agora, cada NavigationEventCallback pode ser registrado com apenas um NavigationEventDispatcher por vez. Adicionar a vários distribuidores gera um IllegalStateException. Esse comportamento é diferente de OnBackPressedDispatcher, que permite vários agentes. (e82c19)
  • Transformamos isPassThrough em um val para evitar mutações durante a navegação, o que poderia interromper o envio de NavigationEvent. (I0b287).

Versão 1.0.0-alpha02

4 de junho de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha02. A versão 1.0.0-alpha02 contém estes commits.

Mudanças na API

  • Substitua o construtor secundário de NavigationEventDispatcher por argumentos padrão. (I716a0)
  • Remova a propriedade de prioridade de NavigationEventCallback. Em vez disso, transmita a prioridade para NavigationEventDispatcher.addCallback(). (I13cae).

Correções de bugs

  • Foi corrigido um ConcurrentModificationException que podia ocorrer quando NavigationEventCallback.remove() era chamado devido à modificação simultânea da lista interna de elementos fecháveis. (b/420919815)

Versão 1.0.0-alpha01

20 de maio de 2025

Lançamento de androidx.navigationevent:navigationevent-*:1.0.0-alpha01. A versão 1.0.0-alpha01 contém estes commits.

Novos recursos

  • A biblioteca androidx.navigationevent oferece uma API KMP-first para processar o retorno do sistema e o retorno preditivo. O NavigationEventDispatcher serve como uma API comum para registrar uma ou mais instâncias NavigationEventCallback para receber eventos de retorno do sistema.
  • Essa camada fica abaixo das APIs lançadas anteriormente em androidx.activity e tem como objetivo ser uma substituição menos opinativa para o uso das APIs Activity em componentes de nível superior ou o uso direto das APIs OnBackInvokedDispatcher do framework Android. As APIs androidx.activity foram reescritas com base nas APIs Navigation Event como parte da Activity 1.12.0-alpha01.