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
30 de julho de 2025 - - - 1.0.0-alpha05

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-alpha04"
}

Kotlin

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

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-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 estas confirmações.

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 distribuidores 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 retornos de chamada 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 enviar 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 estas confirmações.

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 estas confirmações.

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

  • Cada NavigationEventCallback agora 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 estas confirmações.

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 estas confirmações.

Novos recursos

  • A biblioteca androidx.navigationevent fornece 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.