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

Библиотека Navigation Event предоставляет API, ориентированный на KMP, для обработки как системного возврата, так и предиктивного возврата .
Последнее обновление Стабильный релиз Предварительная версия релиза Бета-версия Альфа-версия
28 января 2026 г. 1.0.2 - - -

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

Чтобы добавить зависимость от navigationevent, необходимо добавить репозиторий Google Maven в ваш проект. Для получения дополнительной информации ознакомьтесь с информацией в репозитории Google Maven .

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

Круто 

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

Котлин 

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

Для получения дополнительной информации о зависимостях см. раздел «Добавление зависимостей сборки» .

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

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

Создать новую задачу

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

Для этого артефакта отсутствуют примечания к выпуску.

Версия 1.0

Версия 1.0.2

28 января 2026 г.

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

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

  • Исправлена ​​ошибка, приводящая к сбою при использовании NavigationEventHandler в режиме предварительного просмотра Android Studio. Теперь обработчик определяет режим проверки и ничего не делает, позволяя предварительному просмотру отображаться без предоставленного диспетчера. ( I370f2 , b/454313986 ).

Версия 1.0.1

3 декабря 2025 г.

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

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

  • Исправлена ​​ошибка ConcurrentModificationException при освобождении ресурсов дочернего NavigationEventDispatcher , например, созданного с помощью rememberNavigationEventDispatcherOwner() . ( ec68a9 , b/454363524 )

Версия 1.0.0

19 ноября 2025 г.

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

Основные особенности версии 1.0.0:

Библиотека Navigation Event теперь стабильна! Navigation Event — это библиотека AndroidX для обработки взаимодействий на системном уровне, таких как системный возврат и предиктивный возврат в Android (и других платформах).

  • Для обработки событий NavigationEvent вы можете реализовать собственный NavigationEventHandler , который переопределяет необходимые функции. Затем вам нужно добавить обработчик в NavigationEventDispatcher . Начиная с версии Activity 1.12.0 , ComponentActivity реализует новый интерфейс NavigationEventDispatcherOwner , который предоставляет готовый к использованию диспетчер событий:

    // 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)

  • Модуль navigationevent:navigationevent-compose предоставляет удобную функцию NavigationBackHandler , которая автоматически связывает обработчик с ближайшим объектом NavigationEventDispatcher из класса LocalNavigationEventDispatcherOwner и позволяет разработчикам передавать желаемое поведение в качестве параметров:

    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 } ,
)

Использование этого шаблона в Compose значительно упрощает перенос состояния NavigationEventState и позволяет отслеживать его различными компонентами Composable (например, в случае Navigation3, где можно перенести состояние из NavDisplay ).

  • Каждый NavigationEventDispatcher может указывать родительский диспетчер как в случае использования конструкции, так и без неё. Это позволяет разработчикам создавать иерархическую структуру, в которой несколько диспетчеров могут управляться одним родительским диспетчером. Наличие родительского диспетчера значительно упрощает обработку групп диспетчеров, которые могут нуждаться в отключении или освобождении ресурсов:

    // 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() 
)

  • Библиотека также позволяет передавать сигналы непосредственно в NavigationEventDispatcher через NavigationEventInput . NavigationEventInput выступает в качестве «входной» части системы навигации, преобразуя специфичные для платформы события (например, системные жесты возврата или нажатия кнопок) в стандартизированные события, которые могут быть отправлены в NavigationEventDispatcher . Модуль navigationevent:navigationevent в настоящее время предоставляет 2 NavigationEventInput : более универсальный DirectNavigationEventInput , позволяющий отправлять любые события, и специфичный для Android OnBackInvokedInput , который позволяет NavigationEventDispatcher поддерживать системный жест возврата и предиктивный жест возврата. Если вы реализуете собственный диспетчер (вместо использования диспетчера, предоставляемого ComponentActivity ), вам необходимо вручную добавить свой вход:

    val dispatcher = NavigationEventDispatcher()

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

Версия 1.0.0-rc01

5 ноября 2025 г.

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

Версия 1.0.0-beta01

8 октября 2025 г.

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

Изменения в API

  • Исправьте аннотацию FloatRange для NavigationEvent.touchX и NavigationEvent.touchY . Эти значения представляют собой абсолютные координаты пикселей и не имеют верхней границы 1.0 . ( I4b205 , b/445989313 )
  • Переработайте составной объект NavigationEventDispatcherOwner добавив в него rememberNavigationEventDispatcherOwner . Теперь функция возвращает NavigationEventDispatcherOwner напрямую. Чтобы предоставить этот владелец подкомпозиции, используйте CompositionLocalProvider . ( I874b2 , b/444446629 )

Версия 1.0.0-alpha09

24 сентября 2025 г.

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

Изменения в API

  • Используйте объект-синглтон NavigationEventTransitionState.Idle напрямую, вместо создания экземпляра Idle() . ( Ic7d9e , b/444734264 )
  • Сделайте конструкторы вспомогательными внутренними; получайте экземпляры через публичный класс NavigationEventDispatcher.history вместо прямого создания. ( I3b7e0 , b/444734264 )
  • Требуется создание NavigationEventState через rememberNavigationEventState ; конструктор теперь является внутренним. ( IE143c , b/444734264 )
  • Замените использование метода fallbackOnBackPressed и параметр конструктора onBackCompletedFallback . Поведение остается неизменным; метод вызывается только при завершенных, необработанных событиях возврата. ( Idabe9 , b/444734264 )
  • Основной конструктор NavigationEventHistory(mergedHistory, currentIndex) теперь является internal . Внешние потребители должны использовать открытые конструкторы (либо пустой конструктор, либо конструктор на основе разделов) для создания экземпляров. ( I1c047 , b/444734264 )
  • Заставить View.setViewTreeNavigationEventDispatcherOwner принимать значение nullable owner ( Ic9eb6 , b/444436762 )
  • NavigationEventInfo теперь является abstract class а не interface . Обновите все пользовательские реализации, чтобы они наследовали от этого класса (например, data class MyInfo : NavigationEventInfo() ). ( I1e59c , b/444734264 )
  • Устаревшее свойство NavigationEventDispatcher.state и функция getState<T>() были удалены. Используйте новые, отдельные потоки dispatcher.transitionState (для отслеживания прогресса жестов) и dispatcher.history (для стека навигации). ( Ic2ceb , b/444734264 )
  • Заменен коллбэк NavigationEventInput.onInfoChanged(...) . Реализован новый коллбэк onHistoryChanged(history: NavigationEventHistory) для получения обновлений в виде единого объекта NavigationEventHistory . ( I23e0b , b/444734264 )
  • Вводится новый глобальный StateFlow NavigationEventDispatcher.history . Этот негенерический поток позволяет наблюдателям подписываться только на изменения в стеке навигации и остается стабильным на протяжении всего выполнения жеста. Это аналог transitionState . ( I1db10 , b/444734264 )
  • Вводится новый глобальный StateFlow NavigationEventDispatcher.transitionState . Этот негенерический поток позволяет наблюдателям подписываться только на физическое состояние жеста (Idle/InProgress), отдельно от истории. ( I171fa , b/444734264 )
  • Вводится класс NavigationEventHistoryState . Он будет служить основным API для отслеживания истории навигационной информации, отдельно от состояния жестов. ( I81ca5 , b/444734264 )
  • Теперь NavigationEvent помечен как @Immutable , что позволяет компилятору Compose оптимизировать перекомпозиции. ( If78c7 , b/444734264 )
  • API обработчиков navigationevent-compose обновлены. NavigationEventHandler и NavigationBackHandler (и их варианты) теперь поддерживают новую перегрузку, которая принимает поднятое состояние NavigationEventState . Простые перегрузки (принимающие currentInfo ) сохранены и теперь используют эту новую модель состояния внутри. ( Ic3251 , b/444734264 )
  • Добавьте новый объект @Stable NavigationEventState<T> в библиотеку navigationevent-compose . Этот объект объединяет локальную историю с локальным состоянием жестов и будет основным связующим звеном между rememberNavigationEventState и NavigationEventHandler . ( Ifb69f , b/444734264 )
  • В NavigationEventHandler добавлено новое общедоступное свойство transitionState: TransitionState , доступное только для чтения. Теперь обработчики поддерживают собственное состояние перехода, которое могут отслеживать внешние системы. ( I9acd2 , b/444734264 )
  • Представляем новый закрытый класс TransitionState . Он будет служить основным API для отслеживания состояния жестов, отдельно от истории навигации. ( Id4beb , b/444734264 )
  • Предоставить currentInfo , backInfo и forwardInfo в качестве общедоступных свойств только для чтения в NavigationEventHandler . ( Ia7636 , b/444734264 )
  • Теперь реализациям NavigationEventHandler необходимо передавать значение initialInfo: T базовому конструктору. ( Idcfea , b/444734264 )
  • Замените OnBackInvokedInput на OnBackInvokedOverlayInput или OnBackInvokedDefaultInput . ( I5323f , b/428948766 )
  • Пометьте NavigationEventState как @Immutable . Это повысит производительность Compose, гарантируя, что Composable-объекты, отслеживающие это состояние, смогут корректно пропускать перекомпозицию. ( I399c8 )
  • Переименовать NavigationEventInfo.NotProvided в NavigationEventInfo.None; обновить ссылки. Изменений в поведении нет. ( I5e2d4 )
  • Теперь NavigationEventInfo помечен как @Immutable , что позволяет компилятору Compose оптимизировать перекомпозиции. ( I7c112 )
  • Улучшите эргономику Java с помощью удобного интерфейса для резервного варианта автозавершения. ( I8a860 )
  • Переименуйте onHasEnabledHandlerChanged в onHasEnabledHandlersChanged . Это уточнит, что функция обратного вызова сообщает о совокупном состоянии включения всех обработчиков, а не только одного. ( I1af61 , b/443711297 )
  • Удалите hasEnabledHandler() из NavigationEventDispatcher; вместо него используйте NavigationEventInput.onHasEnabledHandlersChanged . ( Idef72 , b/443711297 )
  • Добавьте функцию обратного вызова onInfoChanged к NavigationEventInput , чтобы уведомлять слушателей об изменениях в истории навигации. Это обеспечивает полный контекст текущего, предыдущего и следующего стеков, позволяя элементам ввода реагировать на контекстную информацию. ( I69a8b , b/443282983 )
  • Сделайте свойство ` swipeEdge объекта ` NavigationEvent @IntDef ( `Icee54` , b/443950342` )
  • Добавьте параметр priority к NavigationEventDispatcher.addInput , чтобы ограничить диспетчер одним приоритетом; события, такие как onHasEnabledCallbacksChanged теперь срабатывают только при изменении коллбэков с этим приоритетом. ( I3e488 , b/443711297 )
  • Для большей ясности переименуйте параметр NavigationEventDispatcher из parentDispatcher в parent. ( Id4f1f , b/443801782 )
  • Удалите NavigationEventPriority в пользу @IntDef для пользователей Java ( I10a9f , b/440514265 )
  • Необходимо обеспечить соблюдение контракта обработчика навигации. Если ваш NavigationEventHandler устанавливает isBackEnabled или isForwardEnabled в true , теперь необходимо переопределить методы onBackCompleted или onForwardCompleted соответственно. Реализации по умолчанию теперь генерируют исключение, чтобы предотвратить скрытые сбои. ( I17c62 )
  • При добавлении обработчиков событий навигации необходимо обеспечить корректность значений приоритета. Вызов addHandler с неподдерживаемым приоритетом теперь будет вызывать исключение IllegalArgumentException , обеспечивая немедленную обратную связь при некорректном использовании на всех целевых платформах. ( I3c474 )

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

  • Сделать addHandler идемпотентным; игнорировать повторяющиеся регистрации. ( I052aa , b/444734264 )
  • Поддерживайте синхронизацию свойств NavigationEventState во время перекомпозиции. ( Ib3b4d , b/444734264 )
  • Убедитесь, что NavigationEventInputs получают текущую контекстную информацию (текущая, назад, вперед) сразу после регистрации. ( Ie65bf , b/443282983 )

Версия 1.0.0-alpha08

10 сентября 2025 г.

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

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

  • Ввести API NavigationEventHandler на основе лямбда-функций, заменяющий обработчик на основе потоков. Обработка жестов "назад" и "вперед" с помощью простых коллбэков вместо сбора потоков, что уменьшит шаблонный код и позволит избежать проблем с отменой. Предоставить NavigationBackHandler и NavigationForwardHandler в качестве целевых удобных API. Удалить NavigationEventHandler на основе потоков; перейти к новым коллбэкам. ( I23bac , b/436248277 )
  • Разрешить пассивным слушателям доступ к полному стеку возврата навигации через объединенную информацию о возврате. Разрешить пользовательским интерфейсам отображать предварительный просмотр и вложенную историю навигации, вместо того чтобы ограничиваться самым верхним коллбэком. ( I7a510 , b/436248277 )
  • Ввести явную модель "назад/текущее/вперед" для уточнения состояния навигации и поддержки навигации вперед с вложенными обработчиками. ( Ib86da , b/420443609 )
  • Добавьте методы onForward* и isForwardEnabled в NavigationEventCallback . ( Ic100f , b/436248290 )
  • Добавить поддержку навигации вперед в NavigationEventInput . ( I5734b )

Изменения в API

  • Включите тестирование событий прямой навигации с помощью TestNavigationEventCallback . Используйте хуки isForwardEnabled и onForward* . ( I21fb5 , b/420443609 )
  • Переименуйте коллбэки onEvent* в onBack* в NavEvent . ( I228b3 , b/436248290 )
  • Преобразовать SwipeEdge во встроенный класс. ( Id5e01 )
  • Обеспечьте совместимость библиотеки navigationevent с Java. Все общедоступные API теперь полностью доступны из кода Java, что позволяет беспрепятственно интегрировать ее в проекты, использующие разные языки программирования или только Java. ( Ibc944 , I5465f , I9fb1e , b/440532890 b/443040294 )
  • Уточните роли API, переименовав NavigationEventCallback в NavigationEventHandler . Это изменение лучше отражает назначение класса — обработку многоэтапных навигационных жестов. Соответствующий метод addCallback теперь называется addHandler . ( I2492a , b/443040331 )

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

  • Предотвратить запуск резервного варианта при навигации вперед. ( I74814 , b/436248290 )
  • Добавлена ​​поддержка предиктивной навигации вперед. API NavigationEvent теперь обрабатывают жесты как назад, так и вперед, обеспечивая согласованную анимацию для обоих направлений навигации. ( Idc98c , b/436248290 )
  • Предотвращение сбоя IllegalStateException во время перекомпозиции при удалении дочернего NavigationEventDispatcherOwner . ( Iff50c , b/412629020 )
  • Теперь пассивные обработчики событий могут получить доступ ко всему стеку возврата навигации через объединенную информацию о возврате, что позволяет пользовательским интерфейсам отображать предварительный просмотр и вложенную историю навигации, вместо того чтобы ограничиваться самым верхним коллбэком. ( I7a510 , b/436248277 )

Версия 1.0.0-alpha07

27 августа 2025 г.

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

Изменения в API

  • Удалите NavigationEventDispatcher.onHasEnabledCallbacksChanged . ( I50e97 )
  • Сделайте NavigationEventCallback.onEventCompleted() абстрактным. ( I36b38 )
  • Измените методы NavigationEventCallback#on* на protected . Обновите вызывающий код, чтобы он их переопределял. ( I6b691 )
  • Переименуйте функции DirectNavigationEventInput . ( Iffb62 )
  • Переименуйте NavigationEventInput.onAttach в onAdded . ( I2d0b8 )
  • Переименуйте NavigationEventInput.onDetach в onRemoved . ( I2d0b8 )
  • Переименуйте NavigationEventInputHandler в NavigationEventInput . ( I676a4 )
  • Добавьте @EmptySuper в NavigationEventInput.onHasEnabledCallbacksChanged . ( If9853 )
  • Реализуйте onAttach в NavigationEventInputHandler . ( I03648 )
  • Реализуйте onDetach в NavigationEventInputHandler . ( I03648 )
  • NavigationEventCallback по умолчанию включается при создании объекта. ( Ic0188 )
  • Замените NavigationEventInput.addOnHasEnabledCallbacksChangedCallback на NavigationEventInput.onHasEnabledCallbacksChanged . ( I64e93 )
  • Для вызова NavigationEventDispatcher.addInput требуется основной поток. ( IC2930 )
  • Для вызова NavigationEventDispatcher.removeInput требуется основной поток. ( IC2930 )
  • Удалите Dispatcher.addOnHasEnabledCallbacksChangedCallback . Замените на Dispatcher.onHasEnabledCallbacksChanged . ( Ida3e3 , b/436530096 )

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

  • Исправлена ​​ошибка, из-за которой добавление уже прикрепленного обработчика или удаление неприкрепленного приводило к некорректной логике жизненного цикла. ( I9e47b )

Версия 1.0.0-alpha06

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-alpha05

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)
  }

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

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

  • Добавить модуль 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-alpha04

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-alpha03

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-alpha02

4 июня 2025 г.

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

Изменения в API

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

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

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

Версия 1.0.0-alpha01

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 .