Навигация 3

Navigation 3 – это библиотека навигации, разработанная специально для Jetpack Compose. В этом руководстве рассказывается, как реализовать навигацию 3 в приложениях для Wear OS.

Основные понятия

  • NavKey – типобезопасный сериализуемый идентификатор пункта назначения (экрана) в приложении.
  • NavBackStack – изменяемый список объектов NavKey, представляющих историю навигации. Вы добавляете и удаляете элементы непосредственно из этого списка.
  • rememberNavBackStack – composable-функция, которая создает и сохраняет обратный стек при изменении конфигурации и завершении процесса.
  • NavDisplay – основной компонент интерфейса, который отслеживает стек возврата и отрисовывает активный экран.
  • EntryProvider – язык описания домена, который связывает NavKey с его фактическим интерфейсом @Composable.
  • SwipeDismissableSceneStrategy – стратегия для Wear OS, которая позволяет закрывать экраны с помощью жеста пролистывания и обрабатывает встроенные анимации возврата.

Шаг 1. Добавьте зависимости

Добавьте в проект необходимые зависимости Navigation 3, Wear Compose и Serialization.

Яркий

dependencies {
    // Core Navigation 3 APIs
    implementation "androidx.navigation3:navigation3-runtime:1.3.0-alpha02"
    implementation "androidx.navigation3:navigation3-ui:1.3.0-alpha02"

    // Wear OS specific Navigation 3 integration
    implementation "androidx.wear.compose:compose-navigation3:1.7.1"

    // Kotlinx Serialization for type-safe routing
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0"
}

Kotlin

dependencies {
    // Core Navigation 3 APIs
    implementation("androidx.navigation3:navigation3-runtime:1.3.0-alpha02")
    implementation("androidx.navigation3:navigation3-ui:1.3.0-alpha02")

    // Wear OS specific Navigation 3 integration
    implementation("androidx.wear.compose:compose-navigation3:1.7.1")

    // Kotlinx Serialization for type-safe routing
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
}

Шаг 2. Укажите пункты назначения (NavKey)

Экраны – это строго типизированные сериализуемые объекты или классы данных, которые реализуют интерфейс NavKey.

@Serializable
sealed interface Screen : NavKey {
    @Serializable
    data object Home : Screen

    @Serializable
    data class Details(val itemId: String) : Screen
}

Шаг 3. Настройте NavDisplay и стек возврата

В корне приложения инициализируйте стратегию для стека возврата и сцены Wear OS, а затем подключите их к NavDisplay.

// 1. Create the persistent back stack starting at the Home screen
val backStack = rememberNavBackStack(Screen.Home)

// 2. Initialize the Wear OS swipe-to-dismiss strategy
val strategy = rememberSwipeDismissableSceneStrategy<NavKey>()

// 3. Render the NavDisplay
NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryProvider = entryProvider {
        // 4. Map keys to Composables
        entry<Screen.Home> {
            HomeScreen(
                onNavigateToDetails = { id -> backStack.add(Screen.Details(id)) }
            )
        }
        entry<Screen.Details> { key ->
            DetailsScreen(
                itemId = key.itemId,
                onBack = { backStack.removeAt(backStack.lastIndex) }
            )
        }
    }
)

Шаг 4. Выполните действия навигации

Поскольку обратный стек – это просто измененный MutableList, навигация становится очень простой. Выполняйте операции непосредственно в экземпляре backStack:

  • Перейти вперед: backStack.add(Screen.Details("123")).
  • Назад: backStack.removeLast() или backStack.removeLastOrNull().
  • Очистить и сбросить: backStack.clear(); backStack.add(Screen.Home) (или используйте операции со списками, чтобы заменить стек).

Шаг 5. Область действия ViewModels (необязательно)

По умолчанию ViewModels относятся к Activity. Navigation 3 предоставляет специальный артефакт (lifecycle-viewmodel-navigation3), чтобы безопасно ограничить область действия ViewModel до NavEntry в стеке возврата. Когда целевой объект удаляется из стека, ViewModel очищается.

  1. Добавьте зависимость:

    implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:...")

  2. Добавьте декоратор хранилища ViewModel в NavDisplayentryDecorators. При использовании специальных декораторов для сохранения состояния rememberSaveable в Compose необходимо явно указать SaveableStateHolderNavEntryDecorator:

    NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberViewModelStoreNavEntryDecorator()
    ),
    entryProvider = entryProvider {
        entry<Screen.Home> {
            // Any viewModel() requested here will be scoped to this NavEntry
            val viewModel: HomeViewModel = viewModel()
        }
    }
)