Navigationsdiagramm entwerfen

Die Navigationskomponente verwendet ein Navigationsdiagramm, um die Navigation Ihrer App zu verwalten. Das Navigationsdiagramm ist eine Datenstruktur, die alle Ziele in Ihrer App und die Verbindungen zwischen ihnen enthält.

Hinweis: Die Navigationsgrafik unterscheidet sich vom Back-Stack, einem Stapel innerhalb von NavController, der die Ziele enthält, die der Nutzer kürzlich besucht hat.

Zieltypen

Es gibt drei allgemeine Arten von Zielen: „Gehostet“, „Dialogfeld“ und „Aktivität“. In der folgenden Tabelle werden diese drei Zieltypen und ihre Zwecke beschrieben.

Typ	Beschreibung	Anwendungsfälle
Gehostet	Füllt den gesamten Navigationshost aus. Das heißt, die Größe eines gehosteten Ziels entspricht der Größe des Navigationshosts. Vorherige Ziele sind nicht sichtbar.	Haupt- und Detailbildschirme.
Dialogfeld	Stellt Overlay-UI-Komponenten dar. Diese Benutzeroberfläche ist nicht an den Standort des Navigationshosts oder seine Größe gebunden. Vorherige Reiseziele werden unter dem Reiseziel angezeigt.	Benachrichtigungen, Auswahl, Formulare
Aktivitäten	Einmalige Bildschirme oder Funktionen innerhalb der App	Als Ausstiegspunkt für das Navigationsdiagramm dienen, das eine neue Android-Aktivität startet, die getrennt von der Navigationskomponente verwaltet wird In der modernen Android-Entwicklung besteht eine App aus einer einzelnen Aktivität. Aktivitätsziele sollten daher am besten bei der Interaktion mit Aktivitäten von Drittanbietern oder im Rahmen des Migrationsprozesses verwendet werden.

Dieses Dokument enthält Beispiele für gehostete Ziele, bei denen es sich um die gängigsten und grundlegenden Ziele handelt. Informationen zu den anderen Zielen finden Sie in den folgenden Leitfäden:

• Dialogziele
• Ziele der Aktivität

Rahmenbedingungen

Obwohl in jedem Fall derselbe allgemeine Workflow gilt, hängt es vom verwendeten UI-Framework ab, wie genau Sie einen Navigationshost und eine Grafik erstellen.

• Schreiben:Verwenden Sie die zusammensetzbare Funktion NavHost. Fügen Sie ihm mit Kotlin DSL ein NavGraph hinzu. Sie haben zwei Möglichkeiten, das Diagramm zu erstellen:
  • Als Teil von NavHost:Die Navigationsgrafik wird direkt beim Hinzufügen von NavHost erstellt.
  • Programmatisch:Verwenden Sie die Methode NavController.createGraph(), um einen NavGraph zu erstellen und direkt an NavHost zu übergeben.
• Fragmente:Wenn Sie Fragmente mit dem UI-Framework für Ansichten verwenden, verwenden Sie NavHostFragment als Host. Es gibt mehrere Möglichkeiten, ein Navigationsdiagramm zu erstellen:
  • Programmatisch:Verwenden Sie die Kotlin DSL, um eine NavGraph zu erstellen und direkt auf die NavHostFragment anzuwenden.
    • Die Funktion createGraph(), die in Kotlin-DSL sowohl für Fragmente als auch für Compose verwendet wird, ist die gleiche.
  • XML:Sie schreiben den Navigationshost und die Grafik direkt in XML.
  • Android Studio-Editor:Verwenden Sie den GUI-Editor in Android Studio, um die Grafik als XML-Ressourcendatei zu erstellen und anzupassen.

Hinweis: Die Interaktion mit dem Diagramm über NavController ist bei den Frameworks ähnlich. Weitere Informationen finden Sie im Leitfaden Zu einem Ziel navigieren.

Textvorschläge

Verwenden Sie in Compose ein serialisierbares Objekt oder eine serialisierbare Klasse, um eine route zu definieren. Eine Route beschreibt, wie Sie zu einem Ziel gelangen, und enthält alle für das Ziel erforderlichen Informationen. Nachdem Sie Ihre Routen definiert haben, verwenden Sie die zusammensetzbare Funktion NavHost, um Ihr Navigationsdiagramm zu erstellen. Betrachten Sie das folgende Beispiel:

@Serializable
object Profile
@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
    // Add more destinations similarly.
}

1. Ein serialisierbares Objekt stellt jede der beiden Routen Profile und FriendsList dar.
2. Beim Aufruf der zusammensetzbaren Funktion NavHost werden ein NavController und eine Route für das Startziel übergeben.
3. Die an das NavHost übergebene Lambda-Funktion ruft letztendlich NavController.createGraph() auf und gibt ein NavGraph zurück.
4. Jede Route wird als Typargument für NavGraphBuilder.composable<T>() angegeben, wodurch das Ziel dem resultierenden NavGraph hinzugefügt wird.
5. Die an composable übergebene Lambda-Funktion wird in NavHost für dieses Ziel angezeigt.

Achtung :Anstatt einen Typ an composable() zu übergeben, können Sie einen route-String oder eine Ganzzahl id übergeben. Dies erschwert jedoch die Verwaltung zusätzlicher Argumente an das Ziel.

Lambda verstehen

Zum besseren Verständnis der Lambda-Funktion, mit der das NavGraph erstellt wird, könnten Sie zum Erstellen desselben Graphen wie im vorherigen Snippet die NavGraph separat mit NavController.createGraph() erstellen und direkt an das NavHost übergeben:

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile)) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
  }
}
NavHost(navController, navGraph)

Wichtig :Ein NavController ist einer einzelnen NavHost-zusammensetzbaren Funktion zugeordnet. NavHost bietet dem NavController-Zugriff auf den zugehörigen Navigationsdiagramm. Wenn Sie NavController zum Aufrufen eines Ziels verwenden, interagiert NavController mit dem zugehörigen NavHost.

Argumente übergeben

Wenn Sie Daten an ein Ziel übergeben müssen, definieren Sie die Route mit einer Klasse, die Parameter enthält. Die Route Profile ist beispielsweise eine Datenklasse mit einem name-Parameter.

@Serializable
data class Profile(val name: String)

Immer wenn Argumente an dieses Ziel übergeben werden müssen, erstellen Sie eine Instanz Ihrer Routenklasse und übergeben die Argumente an den Klassenkonstruktor.

Hinweis: Verwenden Sie data class für eine Route mit Argumenten und object oder data object für eine Route ohne Argumente.

Routeninstanz abrufen

Sie können die Routeninstanz mit NavBackStackEntry.toRoute() oder SavedStateHandle.toRoute() abrufen. Wenn Sie ein Ziel mit composable() erstellen, ist NavBackStackEntry als Parameter verfügbar.

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name) }
}

Beachten Sie in diesem Snippet Folgendes:

• Die Route Profile gibt das Startziel im Navigationsdiagramm an, mit "John Smith" als Argument für name.
• Das Ziel selbst ist der composable<Profile>{}-Block.
• Die zusammensetzbare Funktion ProfileScreen verwendet den Wert von profile.name als eigenes name-Argument.
• Daher wird der Wert "John Smith" an ProfileScreen weitergegeben.

Mindestbeispiel

Hier ein vollständiges Beispiel für die Zusammenarbeit von NavController und NavHost:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
    profile: Profile
    onNavigateToFriendsList: () -> Unit,
  ) {
  Text("Profile for ${profile.name}")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = Profile(name = "John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(
            profile = profile,
            onNavigateToFriendsList = {
                navController.navigate(route = FriendsList)
            }
        )
    }
    composable<FriendsList> {
      FriendsListScreen(
        onNavigateToProfile = {
          navController.navigate(
            route = Profile(name = "Aisha Devi")
          )
        }
      )
    }
  }
}

Wie im Snippet gezeigt, machen Sie ein Ereignis für die NavHost verfügbar, anstatt das NavController an die zusammensetzbaren Funktionen zu übergeben. Ihre zusammensetzbaren Funktionen sollten also einen Parameter vom Typ () -> Unit haben, für den NavHost eine Lambda-Funktion übergibt, die NavController.navigate() aufruft.

Hinweis: Wenn Sie die Parameter der Routenklasse verwenden, können Sie Daten mit vollständiger Typsicherheit an das angegebene Ziel übergeben. Im vorherigen Code sorgt Profile.name beispielsweise dafür, dass name immer ein String ist.

Fragmente

Wie in den vorherigen Abschnitten beschrieben, können Sie bei der Verwendung von Fragmenten eine Navigationsgrafik programmatisch mit dem Kotlin DSL, XML oder dem Android Studio-Editor erstellen.

In den folgenden Abschnitten werden diese unterschiedlichen Ansätze erläutert.

Hinweis :Die Komponente „Navigation“ wurde für Apps entwickelt, die eine Hauptaktivität mit mehreren Fragmentzielen haben. Die Hauptaktivität ist einer Navigationsgrafik zugeordnet und enthält eine NavHostFragment, über die Ziele nach Bedarf gewechselt werden können. In einer App mit mehreren Aktivitätszielen hat jede Aktivität ein eigenes Navigationsdiagramm.

Programmatisch

Kotlin DSL bietet eine programmatische Möglichkeit zum Erstellen einer Navigationsgrafik mit Fragmenten. In vielerlei Hinsicht ist dies ordentlicher und moderner als die Verwendung einer XML-Ressourcendatei.

Im folgenden Beispiel wird ein Navigationsdiagramm mit zwei Bildschirmen implementiert.

Zuerst muss das NavHostFragment-Element erstellt werden, das kein app:navGraph-Element enthalten darf:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

Übergeben Sie als Nächstes den id von NavHostFragment an NavController.findNavController. Dadurch wird der NavController mit dem NavHostFragment verknüpft.

Anschließend verknüpft der Aufruf von NavController.createGraph() die Grafik mit dem NavController und folglich auch mit dem NavHostFragment:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Profile(name = "John Smith")
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment, Profile> {
        label = "Profile"
    }

    fragment<FriendsListFragment, FriendsList>() {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

Die Verwendung von DSL auf diese Weise ähnelt sehr dem Workflow, der im vorherigen Abschnitt unter Compose beschrieben wurde. Sowohl dort als auch hier generiert die Funktion NavController.createGraph() beispielsweise das NavGraph. Analog fügt NavGraphBuilder.composable() dem Diagramm zusammensetzbare Ziele hinzu, während hier NavGraphBuilder.fragment() ein Fragmentziel hinzufügt.

Weitere Informationen zur Verwendung von Kotlin DSL finden Sie unter Grafik mit NavGraphBuilder DSL erstellen.

XML

Sie können die XML-Datei direkt selbst schreiben. Das folgende Beispiel entspricht dem Beispiel mit zwei Bildschirmen aus dem vorherigen Abschnitt.

Erstellen Sie zuerst ein NavHostFragment. Sie dient als Navigationshost, der die eigentliche Navigationsgrafik enthält.

Minimale Implementierung einer NavHostFragment:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:navGraph="@navigation/nav_graph" />

</FrameLayout>

NavHostFragment enthält das Attribut app:navGraph. Verwenden Sie dieses Attribut, um die Navigationsgrafik mit dem Navigationshost zu verbinden. Das folgende Beispiel zeigt, wie Sie die Grafik implementieren könnten:

<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/profile">

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

Sie verwenden Aktionen, um die Verbindungen zwischen verschiedenen Zielen zu definieren. In diesem Beispiel enthält das Fragment profile eine Aktion, die zu friendslist führt. Weitere Informationen finden Sie unter Navigationsaktionen und -fragmente verwenden.

Hinweis: Im DSL-Beispiel werden keine Aktionen definiert, da sie in diesem Kontext nicht gelten. Bei DSL verwenden Sie NavController.navigate() direkt.

Bearbeiter

Sie können das Navigationsdiagramm Ihrer App mit dem Navigationseditor in Android Studio verwalten. Dies ist im Wesentlichen eine GUI, mit der Sie Ihre NavigationFragment-XML-Datei erstellen und bearbeiten können, wie im vorherigen Abschnitt beschrieben.

Weitere Informationen finden Sie unter Navigationseditor.

Verschachtelte Grafiken

Sie können auch verschachtelte Grafiken verwenden. Dazu wird ein Diagramm als Navigationsziel verwendet. Weitere Informationen finden Sie unter Verschachtelte Grafiken.

Weitere Informationen

Weitere grundlegende Navigationskonzepte finden Sie in den folgenden Leitfäden:

• Übersicht:Lesen Sie die allgemeine Übersicht über die Komponente „Navigation“.
• Aktivitätsziele:Beispiele für die Implementierung von Zielen, über die Nutzer zu Aktivitäten gelangen.
• Dialogziele: Beispiele für das Erstellen von Zielen, über die der Nutzer zu einem Dialogfeld weitergeleitet wird.
• Zu einem Ziel navigieren:Eine detaillierte Anleitung, wie Sie von einem Ziel zum anderen navigieren.
• Verschachtelte Grafiken:Eine ausführliche Anleitung zum Verschachteln von Navigationsdiagrammen in einem anderen.