Jetpack Navigation zu Navigation Compose migrieren

Mit der Navigation Compose API können Sie in einer Compose-App zwischen Composables wechseln und dabei die Komponenten, die Infrastruktur und die Funktionen von Jetpack Navigation nutzen.

Auf dieser Seite wird beschrieben, wie Sie im Rahmen der Migration von View-basierter UI zu Jetpack Compose von der Fragment-basierten Jetpack Navigation zu Navigation Compose migrieren.

Voraussetzungen für die Migration

Sie können zu Navigation Compose migrieren, sobald Sie alle Ihre Fragments durch entsprechende Bildschirm-Composables ersetzen können. Screen-Composables können eine Mischung aus Compose- und View-Inhalten enthalten, aber alle Navigationsziele müssen Composables sein, um die Migration zu Navigation Compose zu ermöglichen. Bis dahin sollten Sie die Fragment-basierte Navigationskomponente in Ihrer Interop-Codebasis für View und Compose weiter verwenden. Weitere Informationen finden Sie in der Dokumentation zur Navigations-Interop-Funktion.

Die Verwendung von Navigation Compose in einer reinen Compose-App ist keine Voraussetzung. Sie können die Fragment-basierte Navigationskomponente weiterhin verwenden, solange Sie Fragmente zum Hosten Ihrer zusammensetzbaren Inhalte verwenden.

Migrationsschritte

Unabhängig davon, ob Sie unserer empfohlenen Migrationsstrategie folgen oder einen anderen Ansatz wählen, erreichen Sie einen Punkt, an dem alle Navigationsziele Bildschirm-Composables sind und Fragments nur als Composable-Container fungieren. An diesem Punkt können Sie zu Navigation Compose migrieren.

Wenn Ihre App bereits einem UDF-Entwurfsmuster und unserem Architekturleitfaden folgt, sollten für die Migration zu Jetpack Compose und Navigation Compose keine größeren Refactorings anderer Ebenen Ihrer App erforderlich sein, abgesehen von der UI-Ebene.

So migrieren Sie zu Navigation Compose:

  1. Fügen Sie Ihrer App die Navigation Compose-Abhängigkeit hinzu.

  2. Erstellen Sie eine App-level-Composable und fügen Sie sie Ihrem Activity als Compose-Einstiegspunkt hinzu. Ersetzen Sie dabei die Einrichtung des View-Layouts:

    class SampleActivity : ComponentActivity() {

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

  3. Erstellen Sie Typen für jedes Navigationsziel. Verwenden Sie data object für Ziele, für die keine Daten erforderlich sind, und data class oder class für Ziele, für die Daten erforderlich sind.

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

    MigrationCommonScenariosSnippets.kt

  4. Richten Sie die NavController an einem Ort ein, an dem alle Composables, die darauf verweisen müssen, darauf zugreifen können. Das ist in der Regel in Ihrem App-Composable. Dieser Ansatz folgt den Prinzipien des State Hoisting und ermöglicht es Ihnen, NavController als Quelle der Wahrheit für die Navigation zwischen zusammensetzbaren Bildschirmen und die Verwaltung des Backstacks zu verwenden:

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

  5. Erstellen Sie die NavHost Ihrer App innerhalb der zusammensetzbaren Funktion App und übergeben Sie navController:

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

    SampleNavHost(navController = navController)
}

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

  6. Fügen Sie die composable-Ziele hinzu, um das Navigationsdiagramm zu erstellen. Wenn jeder Bildschirm bereits zu Compose migriert wurde, besteht dieser Schritt nur darin, diese Bildschirm-Composables aus Ihren Fragments in die composable-Ziele zu extrahieren:

    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. Wenn Sie die Anleitung zum Entwerfen Ihrer Compose-Benutzeroberfläche befolgt haben, insbesondere wie ViewModels und Navigationsereignisse an Composables übergeben werden sollten, besteht der nächste Schritt darin, die Art und Weise zu ändern, wie Sie das ViewModel an jedes Bildschirm-Composable übergeben. Hilt-Injection und der zugehörige Integrationspunkt mit Compose und Navigation über hiltViewModel können oft verwendet werden:

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

  8. Ersetzen Sie alle findNavController()-Navigationsaufrufe durch die navController-Aufrufe und übergeben Sie diese als Navigationsereignisse an jeden zusammensetzbaren Bildschirm, anstatt die gesamte navController zu übergeben. Dieser Ansatz folgt den Best Practices für das Bereitstellen von Ereignissen aus zusammensetzbaren Funktionen für Aufrufer und behält navController als Single Source of Truth bei.

    Daten können an ein Ziel übergeben werden, indem eine Instanz der für dieses Ziel definierten Routenklasse erstellt wird. Sie kann dann entweder direkt über den Backstack-Eintrag am Zielort oder über ein ViewModel mit SavedStateHandle.toRoute() abgerufen werden.

    @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. Entfernen Sie alle Fragmente, relevanten XML-Layouts, unnötigen Navigations- und anderen Ressourcen sowie veraltete Fragment- und Jetpack-Navigationsabhängigkeiten.

Dieselben Schritte mit weiteren Details zu Navigation Compose finden Sie in der Einrichtungsdokumentation.

Häufige Anwendungsfälle

Unabhängig davon, welche Navigationskomponente Sie verwenden, gelten dieselben Navigationsprinzipien.

Häufige Anwendungsfälle für die Migration:

Weitere Informationen zu diesen Anwendungsfällen finden Sie unter Navigation mit Compose.

Komplexe Daten während der Navigation abrufen

Wir raten dringend davon ab, beim Navigieren komplexe Datenobjekte zu übergeben. Übergeben Sie stattdessen die minimal erforderlichen Informationen, z. B. eine eindeutige Kennung oder eine andere Form von ID, als Argumente, wenn Sie Navigationsaktionen ausführen. Komplexe Objekte sollten als Daten in einer einzigen Source of Truth gespeichert werden, z. B. im Data Layer. Weitere Informationen finden Sie unter Komplexe Daten beim Navigieren abrufen.

Wenn in Ihren Fragmenten komplexe Objekte als Argumente übergeben werden, sollten Sie Ihren Code zuerst so umgestalten, dass diese Objekte in der Datenschicht gespeichert und abgerufen werden können. Beispiele finden Sie im Now in Android-Repository.

Beschränkungen

In diesem Abschnitt werden die aktuellen Einschränkungen für Navigation Compose beschrieben.

Inkrementelle Migration zu Navigation Compose

Derzeit können Sie Navigation Compose nicht verwenden, wenn Sie weiterhin Fragmente als Ziele in Ihrem Code verwenden. Wenn Sie Navigation Compose verwenden möchten, müssen alle Ihre Ziele Composables sein. Sie können diese Funktionsanfrage in der Problemverfolgung verfolgen.

Übergangsanimationen

Ab Navigation 2.7.0-alpha01 wird das Festlegen benutzerdefinierter Übergänge, das bisher über AnimatedNavHost erfolgte, jetzt direkt in NavHost unterstützt. Weitere Informationen finden Sie in den Versionshinweisen.

Weitere Informationen

Weitere Informationen zur Migration zu Navigation Compose finden Sie in den folgenden Ressourcen:

  • Codelab zu Navigation Compose: In diesem praktischen Codelab lernen Sie die Grundlagen von Navigation Compose kennen.
  • Now in Android-Repository: Eine voll funktionsfähige Android-App, die vollständig mit Kotlin und Jetpack Compose entwickelt wurde und den Best Practices für Android-Design und ‑Entwicklung entspricht. Sie enthält Navigation Compose.
  • Sunflower zu Jetpack Compose migrieren: In diesem Blogpost wird die Migration der Sunflower-Beispiel-App von Views zu Compose dokumentiert. Dazu gehört auch die Migration zu Navigation Compose.
  • Jetnews für jeden Bildschirm: In diesem Blogpost wird die Umgestaltung und Migration des Jetnews-Beispiels dokumentiert, um alle Bildschirme mit Jetpack Compose und Navigation Compose zu unterstützen.