Навигация 3

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

Основные концепции

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

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

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

Классный 

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

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

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

Котлин 

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

    // Wear OS specific Navigation 3 integration
    implementation("androidx.wear.compose:compose-navigation3:1.6.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: (Необязательно) Присвойте ViewModel'ам область действия и направьте их на целевые объекты.

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

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

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

  2. Добавьте декоратор хранилища ViewModel в entryDecorators вашего NavDisplay . Также необходимо явно включить SaveableStateHolderNavEntryDecorator при предоставлении пользовательских декораторов, чтобы сохранить состояние Compose rememberSaveable : 

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