Стабильная версия Jetpack Navigation 3

Выпущена стабильная версия 1.0 Jetpack Navigation 3 🎉. Вы можете использовать ее в своих рабочих приложениях. JetBrains уже использует его в своем приложении KotlinConf.

Navigation 3 – это новая библиотека навигации, созданная с нуля для поддержки состояния Jetpack Compose. Она дает вам полный контроль над обратным стеком, помогает сохранять состояние навигации и позволяет легко создавать адаптивные макеты (например, список и подробные сведения). Есть даже кросс-платформенная версия от JetBrains.

Зачем нужна новая библиотека?

Оригинальная библиотека Jetpack Navigation (теперь Nav2) была разработана семь лет назад. Она хорошо справляется со своими задачами и постоянно улучшается, но за это время подход к созданию приложений кардинально изменился.

Реактивное программирование с декларативным пользовательским интерфейсом теперь является нормой. Nav3 использует этот подход. Например, NavDisplay (компонент пользовательского интерфейса Nav3, который отображает ваши экраны) просто наблюдает за списком ключей (каждый из которых представляет экран), поддерживаемым состоянием Compose, и обновляет свой пользовательский интерфейс при изменении этого списка.

Nav2 также может затруднить создание единого источника достоверных данных для состояния навигации, поскольку у него есть собственное внутреннее состояние. В Nav3 вы сами задаете состояние, что дает вам полный контроль.

Наконец, вы просили сделать интерфейс более гибким и настраиваемым. Вместо одного монолитного API в Nav3 используются небольшие независимые API (или "строительные блоки"), которые можно комбинировать для создания сложных функций. Nav3 использует эти строительные блоки, чтобы обеспечить разумные значения по умолчанию для четко определенных вариантов использования навигации. 

Этот подход позволяет: 

• Настраивать анимацию экрана как для всех, так и для отдельных контактов.
• Показывайте несколько панелей одновременно и создавайте гибкие макеты с помощью Scenes API.
• Легко заменяйте компоненты Nav3 собственными реализациями, если вам нужно настроить поведение.

Подробнее о дизайне и функциях можно узнать в блоге. 

Переход с Navigation 2

Если вы уже используете Nav2, в частности Navigation Compose, рекомендуем перейти на Nav3. Чтобы помочь вам с этим, мы подготовили руководство по переносу. Основные этапы: 

1. Добавьте зависимости Navigation 3.
2. Обновите маршруты навигации, чтобы реализовать NavKey. Чтобы использовать Nav3, вашим маршрутам не нужно реализовывать этот интерфейс, но если они это сделают, вы сможете воспользоваться функцией rememberNavBackStack в Nav3 для создания постоянного обратного стека.
3. Создайте классы для хранения и изменения состояния навигации – именно здесь хранятся ваши обратные стеки.
4. Замените NavController этими классами.
5. Перенесите пункты назначения из NavGraph в NavHost в entryProvider.
6. Замените NavHost на NavDisplay.

Эксперименты с переносом ИИ-агентов

Вы можете попробовать использовать ИИ-агента, чтобы он прочитал руководство по переносу и выполнил необходимые действия в вашем проекте. Чтобы попробовать эту функцию в режиме агента в Gemini в Android Studio:

• Сохраните эту версию руководства в формате Markdown в своем проекте.
• Вставьте в поле ввода следующий запрос (но не нажимайте Enter): "Migrate this project to Navigation 3 using ".
• Введите @migration-guide.md, чтобы предоставить агенту руководство в качестве контекста. 

Как всегда, внимательно проверяйте изменения, внесенные ИИ-агентом, – он может ошибаться.

Мы будем рады узнать, как вы или ваш агент справились с задачей. Отправьте отзыв.

Рецепты навигации для распространенных сценариев

Для распространенных, но сложных сценариев использования у нас есть репозиторий рецептов. В нем показано, как комбинировать API Nav3 определенным образом, что позволяет вам выбрать или изменить рецепт в соответствии с вашими конкретными потребностями. Если рецепт окажется популярным, мы рассмотрим возможность "переноса" его частей, не имеющих нюансов, в основную библиотеку Nav3 или дополнительные библиотеки. 

Сейчас доступно 19 рецептов, в том числе: 

• Несколько обратных стеков
• Модуляризация и внедрение зависимостей
• Передача аргументов навигации в ViewModel (в том числе с помощью Koin)
• Возврат результатов с экранов по событиям и по общему состоянию.

Сейчас мы работаем над рецептом для ссылок на контент и интеграцией Koin. В планах у нас ещё много других рецептов. Разработчик из JetBrains также опубликовал кроссплатформенную версию рецептов Compose.

Если вы хотите, чтобы мы добавили рецепт для распространенного варианта использования, отправьте запрос. 

Общая информация

Чтобы начать работу с Nav3, ознакомьтесь с документацией и рецептами. Кроме того, в течение недели мы будем публиковать технический контент, в том числе: 

• Подробное видео об API, в котором рассказывается о модульности, анимации и адаптивных макетах.
• Прямой эфир в формате «вопрос – ответ» с разработчиками, которые создали Nav3.

Неделя Nav3 Spotlight начнется 1 декабря 2025 г. 

Если вы обнаружите какие-либо проблемы, сообщите нам о них.