Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Eseguire la migrazione da Navigation 2 a Navigation 3

Competenze Android

Visualizza su GitHub

Jetpack Navigation 3

Utilizza una competenza Android per creare e migrare a Jetpack Navigation 3.

Per installare la skill dall'CLI Android, esegui:

android skills add navigation-3

Per eseguire la migrazione dell'app da Navigation 2 a Navigation 3:

Aggiungi le dipendenze di Navigation 3.
Aggiorna le route di navigazione per implementare l'interfaccia NavKey.
Crea classi per contenere e modificare lo stato di navigazione.
Sostituisci NavController con queste classi.
Sposta le destinazioni da NavGraph di NavHost a un entryProvider.
Sostituisci NavHost con NavDisplay.
Rimuovi le dipendenze di Navigation 2.

Preparazione

Le sezioni seguenti descrivono i prerequisiti per la migrazione e le ipotesi sul tuo progetto. Vengono inoltre illustrate le funzionalità supportate per la migrazione e quelle non supportate.

Prerequisiti

Devi utilizzare un compileSdk di 36 o versioni successive.
Dovresti conoscere la terminologia di navigazione.
Le destinazioni sono funzioni componibili. Navigation 3 è progettato esclusivamente per Compose. Per utilizzare Fragment e View in Compose, consulta Utilizzare le visualizzazioni in Compose.
Le route sono fortemente tipizzate. Se utilizzi route basate su stringhe, esegui prima la migrazione alle route con sicurezza dei tipi (esempio).
Facoltativo (ma vivamente consigliato): copertura dei test che verifica il comportamento di navigazione esistente. In questo modo, si verifica che il comportamento di navigazione non sia cambiato al termine della migrazione.

Ipotesi

Questa guida presuppone quanto segue su di te e sul tuo progetto:

Hai una o più route di primo livello (in genere visualizzate in una barra di navigazione in basso) e ognuna ha il proprio back stack.
Quando passi da un back stack all'altro, lo stato dello stack e di tutte le relative destinazioni viene mantenuto.
Esci sempre dall'app tramite la schermata Home, che è la prima schermata visualizzata all'avvio dell'app.
Vuoi eseguire la migrazione da Navigation 2 a Navigation 3 in un'unica modifica atomica. Non stai eseguendo una migrazione incrementale in cui il codice di Navigation 2 viene utilizzato insieme al codice di Navigation 3.

Funzionalità supportate

Questa guida ti consente di eseguire la migrazione delle seguenti funzionalità:

Destinazioni definite come funzioni componibili
Finestre di dialogo (una destinazione mostrata sopra un'altra destinazione)

Funzionalità supportate tramite le ricette

Il repository delle ricette di codice mostra casi d'uso più sfumati, tra cui:

Fogli inferiori (le istruzioni sono fornite in questa guida)
Codice di navigazione modularizzato e destinazioni inserite
Utilizzo e passaggio di argomenti a ViewModel
Restituzione dei risultati da una schermata

Se il tuo progetto include una di queste funzionalità, consulta la ricetta pertinente per capire come implementarla.

Funzionalità non supportate

Questa guida alla migrazione e le ricette di codice non supportano ancora le seguenti funzionalità. Ciò non significa che non puoi implementarle utilizzando Navigation 3, ma non sono trattate qui.

Più di un livello di navigazione nidificata
Destinazioni condivise: schermate che possono spostarsi tra diversi back stack
Tipi di destinazione personalizzati

Passaggio 1: aggiungi le dipendenze di Navigation 3

Utilizza la pagina Guida introduttiva per aggiungere le dipendenze di Navigation 3 al tuo progetto. Le dipendenze principali sono fornite per la copia.

lib.versions.toml

[versions]
nav3Core = "1.1.7"

# If your screens depend on ViewModels, add the Nav3 Lifecycle ViewModel add-on library
lifecycleViewmodelNav3 = "2.11.0"

[libraries]
# Core Navigation 3 libraries
androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "nav3Core" }
androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "nav3Core" }

# Add-on libraries (only add if you need them)
androidx-lifecycle-viewmodel-navigation3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycleViewmodelNav3" }

app/build.gradle.kts

dependencies {
    implementation(libs.androidx.navigation3.ui)
    implementation(libs.androidx.navigation3.runtime)

    // If using the ViewModel add-on library
    implementation(libs.androidx.lifecycle.viewmodel.navigation3)
}

Aggiorna anche minSdk del progetto a 23 e compileSdk a 36. In genere, questi valori si trovano in app/build.gradle.kts o lib.versions.toml.

Passaggio 2: aggiorna le route di navigazione per implementare l'interfaccia `NavKey`

Aggiorna ogni route di navigazione in modo che implementi l'NavKeyinterfaccia. In questo modo, puoi utilizzare rememberNavBackStack per salvare lo stato di navigazione.

Prima:

@Serializable data object RouteANavigationMigrationBefore.kt

Dopo:

@Serializable data object RouteA : NavKeyNavigationMigrationAfter.kt

Passaggio 3: crea classi per contenere e modificare lo stato di navigazione

Passaggio 3.1: crea un contenitore dello stato di navigazione

Copia il seguente codice in un file denominato NavigationState.kt. Aggiungi il nome del pacchetto in modo che corrisponda alla struttura del progetto.

// package com.example.project

import androidx.compose.runtime.Composable
import androidx.compose.runtime.MutableState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSerializable
import androidx.compose.runtime.setValue
import androidx.compose.runtime.snapshots.SnapshotStateList
import androidx.compose.runtime.toMutableStateList
import androidx.navigation3.runtime.NavBackStack
import androidx.navigation3.runtime.NavEntry
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.rememberDecoratedNavEntries
import androidx.navigation3.runtime.rememberNavBackStack
import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
import androidx.navigation3.runtime.serialization.NavKeySerializer
import androidx.savedstate.compose.serialization.serializers.MutableStateSerializer

/**
 * Create a navigation state that persists config changes and process death.
 */
@Composable
fun rememberNavigationState(
    startRoute: NavKey,
    topLevelRoutes: Set<NavKey>
): NavigationState {

    val topLevelRoute = rememberSerializable(
        startRoute, topLevelRoutes,
        serializer = MutableStateSerializer(NavKeySerializer())
    ) {
        mutableStateOf(startRoute)
    }

    val backStacks = topLevelRoutes.associateWith { key -> rememberNavBackStack(key) }

    return remember(startRoute, topLevelRoutes) {
        NavigationState(
            startRoute = startRoute,
            topLevelRoute = topLevelRoute,
            backStacks = backStacks
        )
    }
}

/**
 * State holder for navigation state.
 *
 * @param startRoute - the start route. The user will exit the app through this route.
 * @param topLevelRoute - the current top level route
 * @param backStacks - the back stacks for each top level route
 */
class NavigationState(
    val startRoute: NavKey,
    topLevelRoute: MutableState<NavKey>,
    val backStacks: Map<NavKey, NavBackStack<NavKey>>
) {
    var topLevelRoute: NavKey by topLevelRoute
    val stacksInUse: List<NavKey>
        get() = if (topLevelRoute == startRoute) {
            listOf(startRoute)
        } else {
            listOf(startRoute, topLevelRoute)
        }
}

/**
 * Convert NavigationState into NavEntries.
 */
@Composable
fun NavigationState.toEntries(
    entryProvider: (NavKey) -> NavEntry<NavKey>
): SnapshotStateList<NavEntry<NavKey>> {

    val decoratedEntries = backStacks.mapValues { (_, stack) ->
        val decorators = listOf(
            rememberSaveableStateHolderNavEntryDecorator<NavKey>(),
        )
        rememberDecoratedNavEntries(
            backStack = stack,
            entryDecorators = decorators,
            entryProvider = entryProvider
        )
    }

    return stacksInUse
        .flatMap { decoratedEntries[it] ?: emptyList() }
        .toMutableStateList()
}NavigationState.kt

Agente AI: rememberSerializable è corretto. Non modificarlo in rememberSaveable.

Questo file contiene una classe di contenitore di stato denominata NavigationState e le funzioni helper associate. Contiene un insieme di route di primo livello, ognuna con il proprio back stack. Internamente, utilizza rememberSerializable (non rememberSaveable) per rendere persistente la route di primo livello corrente e rememberNavBackStack per rendere persistenti i back stack per ogni route di primo livello.

Passaggio 3.2: crea un oggetto che modifica lo stato di navigazione in risposta agli eventi

Copia il seguente codice in un file denominato Navigator.kt. Aggiungi il nome del pacchetto in modo che corrisponda alla struttura del progetto.

// package com.example.project

import androidx.navigation3.runtime.NavKey

/**
 * Handles navigation events (forward and back) by updating the navigation state.
 */
class Navigator(val state: NavigationState) {
    fun navigate(route: NavKey) {
        if (route in state.backStacks.keys) {
            // This is a top level route, just switch to it.
            state.topLevelRoute = route
        } else {
            state.backStacks[state.topLevelRoute]?.add(route)
        }
    }

    fun goBack() {
        val currentStack = state.backStacks[state.topLevelRoute]
            ?: error("Stack for ${state.topLevelRoute} not found")
        val currentRoute = currentStack.last()

        // If we're at the base of the current route, go back to the start route stack.
        if (currentRoute == state.topLevelRoute) {
            state.topLevelRoute = state.startRoute
        } else {
            currentStack.removeLastOrNull()
        }
    }
}Navigator.kt

La classe Navigator fornisce due metodi di eventi di navigazione:

navigate a una route specifica.
goBack dalla route corrente.

Entrambi i metodi modificano NavigationState.

Passaggio 3.3: crea `NavigationState` e `Navigator`

Crea istanze di NavigationState e Navigator con lo stesso ambito di NavController.

val navigationState = rememberNavigationState(
    // ...
    startRoute = <Insert your starting route>,
    topLevelRoutes = <Insert your set of top level routes>
    // ...
)

val navigator = remember { Navigator(navigationState) }NavigationMigrationAfter.kt

Passaggio 4: sostituisci `NavController`

Sostituisci i metodi di eventi di navigazione NavController con gli equivalenti di Navigator.

Campo o metodo `NavController`	Equivalente di `Navigator`
`navigate()`	`navigate()`
`popBackStack()`	`goBack()`

Sostituisci i campi NavController con i campi NavigationState.

Campo o metodo `NavController`	Equivalente di `NavigationState`
`currentBackStack`	`backStacks[topLevelRoute]`
`currentBackStackEntry` `currentBackStackEntryAsState()` `currentBackStackEntryFlow` `currentDestination`	`backStacks[topLevelRoute].last()`
Ottieni la route di primo livello: percorri la gerarchia dalla voce del back stack corrente per trovarla.	`topLevelRoute`

Campo o metodo NavController

Equivalente di NavigationState

currentBackStack

backStacks[topLevelRoute]

currentBackStackEntry

currentBackStackEntryAsState()

currentBackStackEntryFlow

currentDestination

backStacks[topLevelRoute].last()

Ottieni la route di primo livello: percorri la gerarchia dalla voce del back stack corrente per trovarla.

topLevelRoute

Utilizza NavigationState.topLevelRoute per determinare l'elemento attualmente selezionato in una barra di navigazione.

Prima:

// ...
val isSelected = navController.currentBackStackEntryAsState().value?.destination.isRouteInHierarchy(key::class)
// ...

fun NavDestination?.isRouteInHierarchy(route: KClass<*>) =
    this?.hierarchy?.any {
        it.hasRoute(route)
    } ?: falseNavigationMigrationBefore.kt

Dopo:

val isSelected = key == navigationState.topLevelRouteNavigationMigrationAfter.kt

Verifica di aver rimosso tutti i riferimenti a NavController, inclusi gli import.

Passaggio 4.1: esegui la migrazione della logica con riconoscimento del ciclo di vita

In Navigation 2, NavBackStackEntry implementa LifecycleOwner, consentendoti di ascoltare gli eventi del ciclo di vita o di raccogliere i flussi in modo da riconoscere il ciclo di vita utilizzando navController.currentBackStackEntry.

In Navigation 3, NavDisplay fornisce un LifecycleOwner con ambito di voce tramite LocalLifecycleOwner.current al contenuto componibile di ogni destinazione. Per ulteriori informazioni, consulta Ciclo di vita della destinazione.

Devi eseguire le operazioni con riconoscimento del ciclo di vita direttamente all'interno del contenuto componibile della destinazione facendo riferimento a LocalLifecycleOwner.current.

Ad esempio, se raccogli un flusso in modo da riconoscere il ciclo di vita utilizzando la voce del back stack:

Prima:

// In your destination screen or host
val lifecycleOwner = navController.currentBackStackEntry!!
val state by flow.collectAsStateWithLifecycle(lifecycleOwner = lifecycleOwner)NavigationMigrationBefore.kt

Dopo:

// Inside the destination composable
val state by flow.collectAsStateWithLifecycle()NavigationMigrationAfter.kt

Passaggio 5: sposta le destinazioni da `NavGraph` di `NavHost` a un `entryProvider`

In Navigation 2, definisci le destinazioni utilizzando il DSL NavGraphBuilder, in genere all'interno della lambda finale di NavHost. È comune utilizzare le funzioni di estensione qui come descritto in Incapsula il codice di navigazione.

In Navigation 3, definisci le destinazioni utilizzando un entryProvider. Questo entryProvider risolve una route in un NavEntry. È importante sottolineare che entryProvider non definisce le relazioni padre-figlio tra le voci.

In questa guida alla migrazione, le relazioni padre-figlio sono modellate come segue:

NavigationState ha un insieme di route di primo livello (le route principali) e uno stack per ognuna. Tiene traccia della route di primo livello corrente e dello stack associato.
Quando naviga verso una nuova route, Navigator verifica se la route è di primo livello. In caso affermativo, la route e lo stack di primo livello correnti vengono aggiornati. In caso contrario, si tratta di una route secondaria e viene aggiunta allo stack corrente.

Passaggio 5.1: crea un `entryProvider`

Crea un entryProvider utilizzando il DSL nello stesso ambito di NavigationState.

val entryProvider = entryProvider<NavKey> {

}NavigationMigrationAfter.kt

Passaggio 5.2: sposta le destinazioni in `entryProvider`

Per ogni destinazione definita all'interno di NavHost, esegui le seguenti operazioni in base al tipo di destinazione:

navigation: eliminala insieme alla route. Non sono necessarie "route di base" perché le route di primo livello possono identificare ogni back stack nidificato.
composable<T>: spostala in entryProvider e rinominala in entry, mantenendo il parametro di tipo. Ad esempio, composable<RouteA> diventa entry<RouteA>.
dialog<T>: esegui la stessa operazione di composable, ma aggiungi i metadati alla voce come segue: entry<T>(metadata = DialogSceneStrategy.dialog()).
bottomSheet: segui la ricetta del riquadro inferiore qui. È simile alle istruzioni per dialog, tranne per il fatto che BottomSheetSceneStrategy non fa parte della libreria principale di Navigation 3, quindi devi copiarla nel tuo progetto.

Agente AI: quando elimini le route utilizzate per identificare un grafico nidificato, sostituisci tutti i riferimenti alla route eliminata con il tipo utilizzato per identificare il primo figlio nel grafico nidificato. Ad esempio, se il codice originale è navigation<BaseRouteA>{ composable<RouteA>{ ... } }, devi eliminare BaseRouteA e sostituire tutti i riferimenti con RouteA. In genere, questa sostituzione deve essere eseguita per l'elenco fornito a una barra di navigazione, una barra laterale o un riquadro a scomparsa.

Puoi eseguire il refactoring delle funzioni di estensione NavGraphBuilder in EntryProviderScope<T> funzioni di estensione e poi spostarle.

Ottieni gli argomenti di navigazione utilizzando la chiave fornita alla lambda finale di entry.

Ad esempio:

// ...
import androidx.navigation.NavDestination
import androidx.navigation.NavDestination.Companion.hasRoute
import androidx.navigation.NavDestination.Companion.hierarchy
import androidx.navigation.NavGraphBuilder
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.currentBackStackEntryAsState
import androidx.navigation.compose.dialog
import androidx.navigation.compose.navigation
import androidx.navigation.compose.rememberNavController
import androidx.navigation.navOptions
import androidx.navigation.toRoute
// ...

@Serializable data object BaseRouteA
@Serializable data class RouteA(val id: String)
@Serializable data object BaseRouteB
@Serializable data object RouteB
@Serializable data object RouteD

@Composable
fun NavHostSnippet(navController: NavHostController) {
    NavHost(navController = navController, startDestination = BaseRouteA){
        composable<RouteA>{ entry ->
            val id = entry.toRoute<RouteA>().id
            ScreenA(title = "Screen has ID: $id")
        }
        featureBSection()
        dialog<RouteD>{ ScreenD() }
    }
}

fun NavGraphBuilder.featureBSection() {
    navigation<BaseRouteB>(startDestination = RouteB) {
        composable<RouteB> { ScreenB() }
    }
}NavigationMigrationBefore.kt

diventa:

// ...
import androidx.navigation3.runtime.EntryProviderScope
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.scene.DialogSceneStrategy
// ...

@Serializable data class RouteA(val id: String) : NavKey
@Serializable data object RouteB : NavKey
@Serializable data object RouteD : NavKey

val entryProvider = entryProvider {
    entry<RouteA>{ key -> ScreenA(title = "Screen has ID: ${key.id}") }
    featureBSection()
    entry<RouteD>(metadata = DialogSceneStrategy.dialog()){ ScreenD() }
}

fun EntryProviderScope<NavKey>.featureBSection() {
    entry<RouteB> { ScreenB() }
}NavigationMigrationAfter.kt

Passaggio 6: sostituisci `NavHost` con `NavDisplay`

Sostituisci NavHost con NavDisplay.

Elimina NavHost e sostituiscilo con NavDisplay.
Specifica entries = navigationState.toEntries(entryProvider) come parametro. In questo modo, lo stato di navigazione viene convertito nelle voci che NavDisplay mostra utilizzando entryProvider.
Collega NavDisplay.onBack a navigator.goBack(). In questo modo, navigator aggiorna lo stato di navigazione al termine del gestore di back integrato di NavDisplay.
Se hai destinazioni di dialogo, aggiungi DialogSceneStrategy al parametro sceneStrategies di NavDisplay.

Ad esempio:

NavDisplay(
    entries = navigationState.toEntries(entryProvider),
    onBack = { navigator.goBack() },
    sceneStrategies = remember { listOf(DialogSceneStrategy()) }
)NavigationMigrationAfter.kt

Passaggio 7: esegui la migrazione dei link diretti

In Navigation 2, i link diretti sono stati definiti direttamente all'interno del grafico di navigazione utilizzando il parametro deepLinks delle destinazioni.

In Navigation 3, i link diretti vengono gestiti indipendentemente dall'interfaccia utente di navigazione. Definisci i DeepLinkMatcher e abbina le richieste in entrata nella tua attività per costruire il back stack iniziale.

Prima:

In Navigation 2, potresti aver definito un link diretto come questo:

composable<RouteA>(
    deepLinks = listOf(
        navDeepLink { uriPattern = "www.example.com/user/{id}" }
    )
) {
    // ...
}NavigationMigrationBefore.kt

Dopo:

In Navigation 3, definisci un UriDeepLinkMatcher per la route:

val userMatcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/user/{id}"),
    serializer<RouteA>()
)NavigationMigrationAfter.kt

Poi, in onCreate (e onNewIntent) della tua attività, abbina l'intent in entrata e inizializza il back stack:

val deepLinkMatchers: List<DeepLinkMatcher<*, *>> = listOf(
    userMatcher,
)

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val request = DeepLinkRequest(intent = intent)
        val matchResult = deepLinkMatchers
            .mapNotNull { it.match(request) }
            .maxOrNull()

        val backStack = when (matchResult) {
            null -> listOf(HomeKey)
            is BackStackMatchResult<*, *> -> {
                @Suppress("UNCHECKED_CAST")
                matchResult.backStack as List<NavKey>
            }
            else -> listOf(matchResult.key)
        }

        // Use backStack with NavDisplay
    }
}NavigationMigrationAfter.kt

Tipi di argomenti personalizzati

In Navigation 2, hai gestito i tipi di argomenti personalizzati o di terze parti (ad esempio LocalDateTime) utilizzando implementazioni NavType personalizzate e typeMap.

In Navigation 3, definisci un DeepLinkSerializer per deserializzare i tipi personalizzati o di terze parti dai parametri URI. Per maggiori dettagli, consulta Serializzazione personalizzata con DeepLinkSerializer.

Per casi d'uso più avanzati, inclusi back stack sintetici e matcher personalizzati, consulta la guida Supportare i link diretti.

Passaggio 8: rimuovi le dipendenze di Navigation 2

Rimuovi tutti gli import e le dipendenze della libreria di Navigation 2.

Riepilogo

Complimenti! La migrazione del progetto a Navigation 3 è stata completata. Se tu o il tuo agente AI avete riscontrato problemi durante l'utilizzo di questa guida, segnala un bug qui.

Eseguire la migrazione da Navigation 2 a Navigation 3 Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Preparazione

Prerequisiti

Ipotesi

Funzionalità supportate

Funzionalità supportate tramite le ricette

Funzionalità non supportate

Passaggio 1: aggiungi le dipendenze di Navigation 3

Passaggio 2: aggiorna le route di navigazione per implementare l'interfaccia NavKey

Passaggio 3: crea classi per contenere e modificare lo stato di navigazione

Passaggio 3.1: crea un contenitore dello stato di navigazione

Passaggio 3.2: crea un oggetto che modifica lo stato di navigazione in risposta agli eventi

Passaggio 3.3: crea NavigationState e Navigator

Passaggio 4: sostituisci NavController

Passaggio 4.1: esegui la migrazione della logica con riconoscimento del ciclo di vita

Passaggio 5: sposta le destinazioni da NavGraph di NavHost a un entryProvider

Passaggio 5.1: crea un entryProvider

Passaggio 5.2: sposta le destinazioni in entryProvider

Passaggio 6: sostituisci NavHost con NavDisplay

Passaggio 7: esegui la migrazione dei link diretti

Tipi di argomenti personalizzati

Passaggio 8: rimuovi le dipendenze di Navigation 2

Riepilogo

Eseguire la migrazione da Navigation 2 a Navigation 3

Passaggio 2: aggiorna le route di navigazione per implementare l'interfaccia `NavKey`

Passaggio 3.3: crea `NavigationState` e `Navigator`

Passaggio 4: sostituisci `NavController`

Passaggio 5: sposta le destinazioni da `NavGraph` di `NavHost` a un `entryProvider`

Passaggio 5.1: crea un `entryProvider`

Passaggio 5.2: sposta le destinazioni in `entryProvider`

Passaggio 6: sostituisci `NavHost` con `NavDisplay`