Esegui la migrazione di Jetpack Navigation a Navigation Compose

L'API Navigation Compose ti consente di spostarti tra i composabili in un'app Compose, sfruttando al contempo il componente, l'infrastruttura e le funzionalità di Jetpack Navigation.

Questa pagina descrive come eseguire la migrazione da Jetpack Navigation basato su frammenti a Navigation Compose, nell'ambito della migrazione più ampia dell'interfaccia utente basata su visualizzazioni a Jetpack Compose.

Prerequisiti per la migrazione

Puoi eseguire la migrazione a Navigation Compose quando riesci a sostituire tutti i frammenti con composabili dello schermo corrispondenti. I composabili della schermata possono contenere un insieme di contenuti di Compose e View, ma tutte le destinazioni di navigazione devono essere composabili per abilitare la migrazione di Compose di navigazione. Fino ad allora, devi continuare a utilizzare il componente di navigazione basato su frammenti nel codice base di View e Compose per l'interoperabilità. Per ulteriori informazioni, consulta la documentazione sull'interoperabilità di navigazione.

L'utilizzo di Componi navigazione in un'app solo di Componi non è un prerequisito. Puoi continuare a utilizzare il componente di navigazione basato su frammenti, a condizione di mantenere i frammenti per ospitare i tuoi contenuti componibili.

Passaggi per la migrazione

Che tu segua la nostra strategia di migrazione consigliata o un altro approccio, arriverai a un punto in cui tutte le destinazioni di navigazione sono composabili dello schermo, con i frammenti che fungono solo da contenitori composabili. A questo livello, puoi eseguire la migrazione a Scrittura con navigazione.

Se la tua app segue già un pattern di progettazione UDF e la nostra guida all'architettura, la migrazione a Jetpack Compose e Navigation Compose non dovrebbe richiedere ristrutturazioni importanti di altri livelli dell'app, a parte il livello dell'interfaccia utente.

Per eseguire la migrazione a Componi navigazione:

  1. Aggiungi la dipendenza Navigation Compose alla tua app.

  2. Crea un composable App-level e aggiungilo a Activity come punto di accesso di Compose, sostituendo la configurazione del layout della vista:

    class SampleActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
        setContent {
            SampleApp(/* ... */)
        }
    }
}
    MigrationCommonScenariosSnippets.kt

  3. Crea tipi per ogni destinazione di navigazione. Utilizza un data object per le destinazioni che non richiedono dati e data class o class per le destinazioni che richiedono dati.

    @Serializable data object First
@Serializable data class Second(val id: String)
@Serializable data object Third

    MigrationCommonScenariosSnippets.kt

  4. Configura NavController in un punto a cui hanno accesso tutti i composabili che devono farvi riferimento (di solito all'interno del composable App). Questo approccio segue i principi dell'elevazione dello stato e ti consente di utilizzare NavController come fonte attendibile per spostarti tra le schermate composable e mantenere la pila di ritorno:

    @Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}
    MigrationCommonScenariosSnippets.kt

  5. Crea l'elemento NavHost della tua app all'interno del composable App e passa il navController:

    @Composable
fun SampleApp() {
    val navController = rememberNavController()

    SampleNavHost(navController = navController)
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  6. Aggiungi le destinazioni composable per creare il grafo di navigazione. Se per ogni schermata è stata eseguita in precedenza la migrazione a Compose, questo passaggio consiste solo nell'estrarre questi composabili della schermata dai frammenti nelle composable destinazioni:

    class FirstFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            setContent {
                // FirstScreen(...) EXTRACT FROM HERE
            }
        }
    }
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(/* ... */) // EXTRACT TO HERE
        }
        composable<Second> {
            SecondScreen(/* ... */)
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  7. Se hai seguito le indicazioni per creare l'architettura dell'interfaccia utente di Compose, in particolare su come devono essere trasmessi i ViewModel e gli eventi di navigazione ai composabili, il passaggio successivo consiste nel modificare il modo in cui fornisci il ViewModel a ogni composable della schermata. Spesso puoi utilizzare l'iniezione Hilt e il relativo punto di integrazione con Compose e Navigation tramite hiltViewModel:

    @Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}
    MigrationCommonScenariosSnippets.kt

  8. Sostituisci tutte le chiamate di navigazione findNavController() con quelle navController e passale come eventi di navigazione a ogni schermata componibile, anziché passare l'intero navController. Questo approccio segue le best practice di esposizione degli eventi delle funzioni componibili agli utenti chiamanti e mantiene navController come unica fonte attendibile.

    I dati possono essere passati a una destinazione creando un'istanza della classe route definita per quella destinazione. Può quindi essere ottenuto direttamente dalla voce dello stack precedente nella destinazione o da un ViewModel utilizzando SavedStateHandle.toRoute().

    @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate(Second(id = "ABC"))
                }
            )
        }
        composable<Second> { backStackEntry ->
            val secondRoute = backStackEntry.toRoute<Second>()
            SecondScreen(
                id = secondRoute.id,
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate(Third)
                }
            )
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  9. Rimuovi tutti i frammenti, i layout XML pertinenti, la navigazione e altre risorse non necessarie, nonché le dipendenze obsolete di Fragment e Jetpack Navigation.

Puoi trovare gli stessi passaggi con ulteriori dettagli relativi a Composizione di navigazione nella documentazione di configurazione.

Casi d'uso comuni

Indipendentemente dal componente di navigazione utilizzato, si applicano gli stesse linee guida di navigazione.

I casi d'uso comuni durante la migrazione includono:

Per informazioni più dettagliate su questi casi d'uso, consulta Navigare con Compose.

Recuperare dati complessi durante la navigazione

Ti consigliamo vivamente di non passare oggetti di dati complessi durante la navigazione. Passa invece le informazioni minime necessarie, ad esempio un identificatore univoco o un'altra forma di ID, come argomenti quando esegui azioni di navigazione. Devi memorizzare gli oggetti complessi come dati in un'unica fonte attendibile, ad esempio il livello di dati. Per ulteriori informazioni, vedi Recupero di dati complessi durante la navigazione.

Se i tuoi frammenti passano oggetti complessi come argomenti, ti consigliamo di eseguire prima il refactoring del codice in modo da poter memorizzare e recuperare questi oggetti dal livello dati. Consulta il repository Ora su Android per alcuni esempi.

Limitazioni

Questa sezione descrive le limitazioni attuali di Componi navigazione.

Migrazione incrementale a Navigation Compose

Al momento, non puoi utilizzare Navigation Compose continuando a utilizzare i frammenti come destinazioni nel codice. Per iniziare a utilizzare la composizione di navigazione, tutte le destinazioni devono essere composable. Puoi monitorare questa richiesta di funzionalità nell'Issue Tracker.

Animazioni di transizione

A partire da Navigation 2.7.0-alpha01, il supporto per l'impostazione di transizioni personalizzate, precedentemente disponibile in AnimatedNavHost, è ora supportato direttamente in NavHost. Per maggiori informazioni, leggi le note di rilascio.

Scopri di più

Per ulteriori informazioni sulla migrazione a Composizione di navigazione, consulta le seguenti risorse:

  • Codelab Navigation Compose: scopri le nozioni di base di Navigation Compose con un codelab pratico.
  • Ora nel repository Android: un'app Android completamente funzionale realizzata interamente con Kotlin e Jetpack Compose, che segue le best practice di progettazione e sviluppo di Android e include Navigation Compose.
  • Migrazione di Sunflower a Jetpack Compose: un post del blog che documenta il percorso di migrazione dell'app di esempio Sunflower da Views a Compose, che include anche la migrazione a Navigation Compose.
  • Jetnews per ogni schermo: un post del blog che descrive il refactoring e la migrazione del Sample Jetnews per supportare tutte le schermate con Jetpack Compose e Navigation Compose.