навигационное событие

Библиотека событий навигации предоставляет API KMP-first для обработки системных возвратов, а также предиктивных возвратов .
Последнее обновление Стабильный релиз Кандидат на релиз Бета-версия Альфа-релиз
13 августа 2025 г. - - - 1.0.0-альфа06

Объявление зависимостей

Чтобы добавить зависимость от navigationevent, необходимо добавить репозиторий Google Maven в свой проект. Подробнее см. в репозитории Google Maven .

Добавьте зависимости для необходимых артефактов в файл build.gradle вашего приложения или модуля:

Круто 

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

Котлин 

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

Дополнительные сведения о зависимостях см. в разделе Добавление зависимостей сборки .

Обратная связь

Ваши отзывы помогают улучшить Jetpack. Сообщите нам, если вы обнаружите новые проблемы или у вас есть идеи по улучшению этой библиотеки. Пожалуйста, ознакомьтесь с уже существующими проблемами в этой библиотеке, прежде чем создавать новую. Вы можете проголосовать за существующую проблему, нажав на кнопку со звёздочкой.

Создать новый выпуск

Более подробную информацию см. в документации по системе отслеживания проблем .

Заметок о выпуске для этого артефакта нет.

Версия 1.0

Версия 1.0.0-альфа06

13 августа 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha06 . Версия 1.0.0-alpha06 содержит следующие коммиты .

Новые функции

API пассивных слушателей

Теперь вы можете передавать пользовательскую контекстную информацию из любого навигационного хоста и пассивно отслеживать изменения состояния жестов из любой точки вашего пользовательского интерфейса. Это позволяет использовать контекстно-зависимые анимации для предиктивной навигации «Назад» и других функций, управляемых жестами.

Эта функция состоит из двух частей:

  1. Предоставление информации — используйте NavigationEventInfo для передачи пользовательских данных.
  2. Состояние потребления — используйте dispatcher.state ( NavigationEventState ) для наблюдения за ходом выполнения жеста и контекстом.
  • NavigationEventCallback теперь предоставляет метод setInfo(currentInfo, previousInfo) для установки контекста жеста за один вызов ( I1d5e7 , b/424470518 ).
  • NavigationEventHandler добавляет новую перегрузку, которая принимает currentInfo и previousInfo , что делает его основным API для предоставления контекста в приложениях Compose ( I6ecd3 , b/424470518 ).

Пример:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher теперь предоставляет dispatcher.state и dispatcher.getState<T>() ( If7fae , Ia90ca , b/424470518 ). Эти API на основе StateFlow позволяют любому пользовательскому интерфейсу отслеживать ход выполнения жестов и контекстные данные без непосредственной обработки события.

Пример:

  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 */ }
  }

  • Добавьте свойство progress в NavigationEventState ( I7b196 ), которое возвращает latestEvent.progress , если процесс выполняется, или 0F в противном случае:

    val progress = state.progress

  • Добавьте компонуемый объект NavigationEventDispatcherOwner для иерархического создания, связывания и удаления экземпляров NavigationEventDispatcher . Включите динамическое управление состоянием включённого диспетчера и автоматическую очистку.

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

Изменения API

  • Параметр isPassthrough был удален из NavigationEventCallback . ( I99028 , b/424470518 )
  • Конструкторы NavigationEventState теперь внутренние. Для тестирования обновите состояние (по умолчанию Idle ) через DirectNavigationEventInputHandler . Вызовите handleOnStarted или handleOnProgressed , чтобы установить состояние InProgress , и handleOnCompleted или handleOnCancelled , чтобы вернуть его в Idle . Для обновления NavigationEventInfo используйте NavigationEventCallback.setInfo . ( I93dca , b/424470518 )
  • Добавлены параметры по умолчанию для NavigationEvent , чтобы упростить создание экземпляров и тестирование, которые следует использовать вместо TestNavigationEvent . ( I5dc49 , I232f4 )
  • Добавлен TestNavigationEventCallback для тестирования событий навигации с определенными текущими/предыдущими состояниями. ( Idd22e , b/424470518 )
  • NavigationEventInputHandler был преобразован в абстрактный класс, чтобы заменить предыдущий AbstractNavigationEventInputHandler с реализацией в DirectNavigationEventInputHandler ( Iadde5 , Ifed40 I3897c , b/432616296 , b/435416924 ).
  • Префиксы функций send* в NavigationEventInputHandler были переименованы в handle* . ( Iffcaf )
  • OnBackInvokedInputHandler теперь расширяет новый abstract NavigationInputHandler . ( Ib45aa )
  • Изменен NavigationEventDispatcherOwner так, чтобы требовался родительский диспетчер, тогда как для создания корневого диспетчера необходимо явно передать null . ( Ia6f64 , b/431534103 )

Исправления ошибок

  • Повышение эффективности за счет исключения копирования коллекций в NavigationEventDispatcher.dispose() . ( I4ab09 )
  • Исправлена ошибка, из-за которой NavigationEventHandler некорректно реагировал на изменения своего включенного состояния. ( Ia5268 , I19bec , I5be5c , b/431534103 )

Обновления документов

  • Расширение KDocs для NavigationEvent с целью прояснить его роль как единой оболочки событий и подробно описать поведение свойств при различных типах навигации (жесты, щелчки). ( I91e8d )
  • Обновлена документация по системной обработке API Compose ( BackHandler , PredictiveBackHandler , NavigationEventHandler ) для описания поведения, связанного с порядком обратного вызова. ( I7ab94 ,)

Обновление зависимостей

  • NavigationEvent теперь зависит от Compose Runtime 1.9.0-beta03, что позволяет артефакту navigationevent-compose поддерживать все цели KMP. ( Ia1b87 )

Версия 1.0.0-альфа05

30 июля 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha05 . Версия 1.0.0-alpha05 содержит следующие коммиты .

Поддержка иерархии «родитель-ребенок»:

NavigationEventDispatcher теперь может иметь родительские и дочерние диспетчеры, образуя иерархическую древовидную структуру. Это позволяет более гибко распространять события навигации и управлять ими в сложных компонентах пользовательского интерфейса Compose, отражая структурную иерархию пользовательского интерфейса посредством цепочек диспетчеров. ( 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)

Иерархическое свойство isEnabled позволяет управлять диспетчером сверху вниз. Если для диспетчера isEnabled значение false , он автоматически отключает все дочерние диспетчеры. Эта функция позволяет эффективно отключать целые ветви системы навигационных событий. ( I9e985 )

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

Более того, свойство isEnabled объекта NavigationEventCallback теперь учитывает состояние включённого связанного с ним диспетчера. Это означает, что обратный вызов считается включённым только в том случае, если включены как сам обратный вызов, так и его диспетчер (включая его предков), что обеспечивает согласованный иерархический контроль над активацией обратного вызова. ( 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()

Введён новый метод dispose() для корректной очистки диспетчеров и их дочерних объектов. Вызов dispose() останавливает прослушиватели для предотвращения утечек памяти, рекурсивно удаляет все дочерние диспетчеры, удаляет все обратные вызовы, зарегистрированные для диспетчера, и отсоединяет его от родительского объекта. Это гарантирует корректное освобождение ресурсов, когда диспетчеры больше не нужны. ( I9e985 )

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

При вызове любого открытого метода в ликвидированном диспетчере немедленно генерируется исключение IllegalStateException . Это предотвращает скрытые сбои и помогает разработчикам выявлять некорректное использование в процессе разработки. ( Ic2dc3 )

  val callback2 = TestNavigationEventCallback()

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

Примечание: Мы представим новый компонуемый NavigationEventDispatcherOwner , который автоматически управляет дочерним диспетчером в интерфейсе Compose в aosp/3692572 . Однако это изменение не вошло в текущую версию и запланировано на следующую.

Библиотека навигационного тестирования

  • Добавить модуль navigationevent-testing для предоставления специальных утилит тестирования для библиотеки navigationevent . ( 0e50b6 )
  • Добавлен фиктивный служебный класс TestNavigationEventCallback для тестирования. Он записывает вызовы методов обратного вызова и сохраняет полученные элементы NavigationEvent для поддержки проверки. ( 4a0246 )
  • Добавьте фиктивную служебную функцию TestNavigationEvent для создания экземпляров NavigationEvent со значениями по умолчанию, упрощая модульные тесты для обработки событий навигации. ( 3b63f5 )
  • Добавлен фиктивный служебный класс TestNavigationEventDispatcherOwner для тестирования. Он отслеживает количество событий отката и изменения состояния включения для поддержки проверки взаимодействия в тестах. ( c8753e )

Изменения API

  • Переместить NavigationEventInputHandler из androidMain в commonMain , чтобы сделать его доступным в общем коде KMP. Добавить новые public send* для отправки событий. Измените функции отправки в NavigationEventDispatcher с public на internal ; теперь пользователи должны использовать NavigationEventInputHandler для отправки событий. ( Ia7114 )
  • Переименуйте NavigationInputHandler в OnBackInvokedInputHandler . ( I63405 )

Исправления ошибок

  • Реорганизуйте NavigationEventDispatcher , чтобы сократить накладные расходы за счет исключения промежуточных распределений списков и повышения производительности диспетчеризации обратных вызовов. ( I82702 , I1a9d9 )
  • Добавьте аннотации @FloatRange к полям touchX , touchY и progress в NavigationEvent чтобы обеспечить соблюдение допустимых диапазонов значений во время компиляции и повысить безопасность API. ( Iac0ec )

Версия 1.0.0-альфа04

2 июля 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha04 . Версия 1.0.0-alpha04 содержит следующие коммиты .

Исправления ошибок

  • Использовал implementedInJetBrainsFork для navigationevent-compose и добавил цель commonStubs для соответствия соглашениям Compose. Изменение запрошено JetBrains . ( f60c79 )
  • Исправлено применение плагина компилятора Compose для Kotlin/Native для обеспечения корректной генерации заглушек. Это не влияет на публичные API или поведение. ( 1890c9 )

Версия 1.0.0-альфа03

18 июня 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha03 . Версия 1.0.0-alpha03 содержит следующие коммиты .

Новые функции

  • Представлен новый модуль navigationevent-compose для поддержки функций Jetpack Compose в библиотеке navigationevent . ( 980d78 )
  • NavigationEvent Compose добавлена новая локальная композиция LocalNavigationEventDispatcherOwner . Она возвращает значение, допускающее значение NULL, для более точного определения её доступности в текущей композиции. NavigationEventHandler теперь выдаёт ошибку, если базовый владелец не найден. ( 62ffda )
  • NavigationEvent Compose добавил новый NavigationEventHandler Composable для обработки событий (предиктивного жеста «Назад»). Он предоставляет Flow объектов NavigationEvent , которые необходимо собрать в лямбда-выражении приостановки, которое вы предоставляете 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
  }
}

Изменения API

  • Каждый NavigationEventCallback теперь может быть зарегистрирован только с одним NavigationEventDispatcher одновременно; добавление его к нескольким диспетчерам вызывает исключение IllegalStateException . Обратите внимание, что это поведение отличается от OnBackPressedDispatcher , который допускает несколько диспетчеров. ( e82c19 )
  • isPassThrough сделан val для предотвращения мутаций во время навигации, которые могли бы нарушить диспетчеризацию NavigationEvent . ( I0b287 )

Версия 1.0.0-альфа02

4 июня 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha02 . Версия 1.0.0-alpha02 содержит следующие коммиты .

Изменения API

  • Замените вторичный конструктор NavigationEventDispatcher аргументами по умолчанию. ( I716a0 )
  • Удалите свойство priority из NavigationEventCallback . Вместо этого передайте приоритет в NavigationEventDispatcher.addCallback() . ( I13cae )

Исправления ошибок

  • Исправлено исключение ConcurrentModificationException , которое могло возникнуть при вызове NavigationEventCallback.remove() из-за одновременного изменения внутреннего списка закрываемых объектов. ( b/420919815 )

Версия 1.0.0-альфа01

20 мая 2025 г.

Выпущен androidx.navigationevent:navigationevent-*:1.0.0-alpha01 . Версия 1.0.0-alpha01 содержит следующие коммиты .

Новые функции

  • Библиотека androidx.navigationevent предоставляет API, ориентированный на KMP, для обработки системных событий, а также предиктивных событий . NavigationEventDispatcher служит общим API для регистрации одного или нескольких экземпляров NavigationEventCallback для получения системных событий.
  • Этот уровень располагается ниже ранее выпущенных API в androidx.activity и призван стать более гибкой заменой использованию API Activity в компонентах более высокого уровня или непосредственному использованию API OnBackInvokedDispatcher фреймворка Android. API androidx.activity были переписаны поверх API Navigation Event в рамках Activity 1.12.0-alpha01 .