Nawigacja 3

Navigation 3 to biblioteka nawigacji zaprojektowana od podstaw pod kątem Jetpack Compose. Z tego przewodnika dowiesz się, jak wdrożyć Navigation 3 w aplikacjach Wear OS.

Podstawowe pojęcia

  • NavKey: bezpieczny typowo, serializowalny identyfikator miejsca docelowego (ekranu) w aplikacji.
  • NavBackStack: modyfikowalna lista instancji NavKey reprezentująca historię nawigacji. Możesz bezpośrednio dodawać i usuwać elementy z tej listy.
  • rememberNavBackStack: funkcja kompozycyjna, która tworzy i utrwala stos wsteczny w przypadku zmian konfiguracji i śmierci procesu.
  • NavDisplay: podstawowy komponent interfejsu, który obserwuje stos wsteczny i renderuje aktywny ekran.
  • EntryProvider: DSL mapowania, które łączy NavKey z jego rzeczywistym interfejsem @Composable.
  • SwipeDismissableSceneStrategy: strategia specyficzna dla Wear, która otacza ekrany gestem przesunięcia w celu zamknięcia i obsługuje wbudowane animacje wsteczne.

Krok 1. Dodaj zależności

Dodaj do projektu wymagane zależności Navigation 3, Wear Compose i Serialization.

Dynamiczny

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

Kotlin

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

Krok 2. Zdefiniuj miejsca docelowe (NavKey)

Ekrany są definiowane jako silnie typowane, serializowalne obiekty lub klasy danych, które implementują interfejs NavKey.

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

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

Krok 3. Skonfiguruj NavDisplay i stos wsteczny

W głównym katalogu aplikacji zainicjuj stos wsteczny i strategię sceny Wear OS , a następnie podłącz je do 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) }
            )
        }
    }
)

Krok 4. Wykonaj działania nawigacyjne

Ponieważ stos wsteczny jest tylko dostosowaną MutableList, nawigacja jest niezwykle prosta. Operacje wykonujesz bezpośrednio na instancji backStack:

  • Przejdź dalej: backStack.add(Screen.Details("123"))
  • Cofnij się: backStack.removeLast() lub backStack.removeLastOrNull()
  • Wyczyść i zresetuj: backStack.clear(); backStack.add(Screen.Home) (lub użyj operacji na liście, aby zastąpić stos).

Krok 5. (Opcjonalnie) Określ zakres ViewModels dla miejsc docelowych

Domyślnie ViewModel są ograniczone do Activity. Navigation 3 udostępnia konkretny artefakt (lifecycle-viewmodel-navigation3), który umożliwia bezpieczne określenie zakresu ViewModel dla NavEntry w stosie wstecznym. Gdy miejsce docelowe zostanie usunięte ze stosu wstecznego, ViewModel zostanie wyczyszczony.

  1. Dodaj zależność:

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

  2. Dodaj dekorator magazynu ViewModel do NavDisplay's entryDecorators. Aby zachować stan rememberSaveable w Compose, musisz też wyraźnie uwzględnić SaveableStateHolderNavEntryDecorator podczas udostępniania niestandardowych dekoratorów:

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