Die Navigationskomponente verwendet ein Navigationsdiagramm, um die Navigation Ihrer App zu verwalten. Das Navigationsdiagramm ist eine Datenstruktur, die alle Ziele innerhalb Ihrer Anwendung und die Verbindungen zwischen ihnen enthält.
Zieltypen
Es gibt drei allgemeine Arten von Zielen: gehostet, Dialog 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 und vorherige Ziele sind nicht sichtbar. |
Haupt- und Detailbildschirme |
Dialogfeld |
Zeigt Overlay-UI-Komponenten an. Diese UI ist nicht an den Standort oder die Größe des Navigationshosts gebunden. Vorherige Reiseziele werden unter dem Ziel angezeigt. |
Benachrichtigungen, Auswahlmöglichkeiten, Formulare |
Aktivitäten |
Einzelne Bildschirme oder Funktionen innerhalb der App. |
Sie dienen als Ausstiegspunkt für die Navigationsgrafik, die eine neue Android-Aktivität startet, die getrennt von der Navigationskomponente verwaltet wird. In der modernen Android-Entwicklung besteht eine App aus einer einzigen Aktivität. Aktivitätsziele eignen sich daher am besten für die Interaktion mit Aktivitäten von Drittanbietern oder im Rahmen des Migrationsprozesses. |
Dieses Dokument enthält Beispiele für gehostete Ziele. Dies sind die gängigsten und grundlegenden Ziele. Informationen zu den anderen Zielen finden Sie in den folgenden Leitfäden:
Rahmen
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.
- Compose (Erstellen): Verwenden Sie die zusammensetzbare Funktion
NavHost
. Fügen Sie ihm mit Kotlin-DSL einNavGraph
hinzu. Sie haben zwei Möglichkeiten, das Diagramm zu erstellen:- Als Teil von NavHost:Erstellen Sie das Navigationsdiagramm direkt, wenn Sie
NavHost
hinzufügen. - Programmatisch:Verwende die Methode
NavController.createGraph()
, um einenNavGraph
zu erstellen und ihn direkt an dieNavHost
zu übergeben.
- Als Teil von NavHost:Erstellen Sie das Navigationsdiagramm direkt, wenn Sie
- Fragmente:Wenn Sie Fragmente mit dem UI-Framework für Ansichten verwenden, verwenden Sie ein
NavHostFragment
als Host. Es gibt mehrere Möglichkeiten, ein Navigationsdiagramm zu erstellen:- Programmatisch:Erstellen Sie mit der Kotlin-DSL eine
NavGraph
und wenden Sie sie direkt auf dieNavHostFragment
an.- Die
createGraph()
-Funktion, die mit Kotlin-DSL sowohl für Fragmente als auch für Compose verwendet wird, ist identisch.
- Die
- XML:Schreiben Sie Ihren Navigationshost und Ihre Grafik direkt in XML.
- Android Studio-Editor: Verwenden Sie den GUI-Editor in Android Studio, um Ihr Diagramm als XML-Ressourcendatei zu erstellen und anzupassen.
- Programmatisch:Erstellen Sie mit der Kotlin-DSL eine
Textvorschläge
Verwenden Sie in Compose ein serielles Objekt oder eine serielle Klasse, um eine route zu definieren. Eine Route beschreibt, wie man zu einem Ziel gelangt. Sie enthält alle Informationen, die das Ziel benötigt. Nachdem Sie die Routen definiert haben, erstellen Sie mit der zusammensetzbaren Funktion NavHost
die Navigationsgrafik. Hier ein 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.
}
- Ein serielles Objekt stellt jede der beiden Routen,
Profile
undFriendsList
, dar. - Der Aufruf der zusammensetzbaren Funktion
NavHost
übergibt einNavController
und eine Route für das Startziel. - Die an
NavHost
übergebene Lambda-Funktion ruft letztendlichNavController.createGraph()
auf und gibt einNavGraph
-Objekt zurück. - Jede Route wird als Typargument an
NavGraphBuilder.composable<T>()
übergeben, wodurch das Ziel dem resultierendenNavGraph
hinzugefügt wird. - Die an
composable
übergebene Lambda-Funktion ist das, was dieNavHost
für dieses Ziel anzeigt.
Das Lambda verstehen
Zum besseren Verständnis der Lambda-Funktion, mit der die NavGraph
erstellt wird, können Sie zum Erstellen des Diagramms wie im vorherigen Snippet die NavGraph
separat mit NavController.createGraph()
erstellen und direkt an die NavHost
übergeben:
val navGraph by remember(navController) {
navController.createGraph(startDestination = Profile)) {
composable<Profile> { ProfileScreen( /* ... */ ) }
composable<FriendsList> { FriendsListScreen( /* ... */ ) }
}
}
NavHost(navController, navGraph)
Argumente übergeben
Wenn Sie Daten an ein Ziel übergeben müssen, definieren Sie die Route mit einer Klasse mit Parametern. Die Route Profile
ist beispielsweise eine Datenklasse mit einem name
-Parameter.
@Serializable
data class Profile(val name: String)
Immer wenn Sie Argumente an dieses Ziel übergeben müssen, erstellen Sie eine Instanz der Routenklasse und übergeben die Argumente an den Klassenkonstruktor.
Routeninstanz abrufen
Sie können die Routeninstanz mit NavBackStackEntry.toRoute()
oder SavedStateHandle.toRoute()
abrufen. Wenn Sie mit composable()
ein Ziel 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, wobei"John Smith"
das Argument fürname
ist. - Das Ziel selbst ist der Block
composable<Profile>{}
. - Die zusammensetzbare Funktion
ProfileScreen
verwendet den Wert vonprofile.name
für ihr eigenes Argumentname
. - Daher wird der Wert
"John Smith"
anProfileScreen
weitergegeben.
Minimales Beispiel
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 das Snippet zeigt, stellen Sie ein Ereignis für die NavHost
bereit, anstatt NavController
an Ihre zusammensetzbaren Funktionen zu übergeben. Das heißt, die zusammensetzbaren Funktionen sollten einen Parameter vom Typ () -> Unit
haben, für den NavHost
eine Lambda-Funktion übergibt, die NavController.navigate()
aufruft.
Fragmente
Wie in den vorherigen Abschnitten beschrieben, können Sie bei Verwendung von Fragmenten Navigationsdiagramme programmatisch mit Kotlin-DSL, XML oder dem Android Studio-Editor erstellen.
In den folgenden Abschnitten werden diese verschiedenen Ansätze ausführlich beschrieben.
Programmatisch
Kotlin-DSL bietet eine programmatische Möglichkeit zum Erstellen eines Navigationsdiagramms mit Fragmenten. In vielerlei Hinsicht ist dies übersichtlicher und moderner als die Verwendung einer XML-Ressourcendatei.
Im folgenden Beispiel wird eine Navigationsgrafik mit zwei Bildschirmen implementiert.
Zuerst müssen Sie das NavHostFragment
erstellen, das kein Element app:navGraph
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 NavHostFragment
verknüpft.
Anschließend verknüpft der Aufruf von NavController.createGraph()
die Grafik mit der NavController
und folglich auch mit der 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 dem Workflow, der im vorherigen Abschnitt zum Thema Schreiben beschrieben wurde. Die Funktion NavController.createGraph()
generiert beispielsweise sowohl dort als auch hier das NavGraph
. Während NavGraphBuilder.composable()
dem Diagramm zusammensetzbare Ziele hinzufügt, fügt NavGraphBuilder.fragment()
hier ein Fragmentziel hinzu.
Weitere Informationen zur Verwendung der Kotlin-DSL finden Sie unter Diagramm mit der NavGraphBuilder-DSL erstellen.
XML
Sie können den XML-Code selbst direkt schreiben. Das folgende Beispiel spiegelt das Beispiel mit zwei Bildschirmen aus dem vorherigen Abschnitt wider und entspricht diesem Beispiel.
Erstellen Sie zuerst eine NavHostFragment
. Sie dient als Navigationshost,
der das eigentliche Navigationsdiagramm enthält.
Eine minimale Implementierung von 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. Im Folgenden finden Sie ein Beispiel dafür, wie Sie die Grafik implementieren können:
<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>
Mithilfe von Aktionen definieren Sie die Verbindungen zwischen verschiedenen Zielen. In diesem Beispiel enthält das Fragment profile
eine Aktion, mit der zu friendslist
navigiert wird. Weitere Informationen finden Sie unter Navigationsaktionen und -fragmente verwenden.
Bearbeiter
Sie können die Navigationsgrafik Ihrer App mit dem Navigationseditor in Android Studio verwalten. Dies ist im Wesentlichen eine GUI, die Sie zum Erstellen und Bearbeiten Ihrer NavigationFragment
-XML-Datei verwenden können, wie im vorherigen Abschnitt gezeigt.
Weitere Informationen finden Sie unter Navigationseditor.
Verschachtelte Grafiken
Sie können auch verschachtelte Grafiken verwenden. Dabei 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 sich die allgemeine Übersicht über die Navigationskomponente durch.
- Aktivitätsziele:Beispiele für die Implementierung von Zielen, die Nutzer zu Aktivitäten weiterleiten.
- Dialogziele:Beispiele für das Erstellen von Zielen, über die der Nutzer zu einem Dialogfeld weitergeleitet wird.
- Zu einem Ziel navigieren:Eine ausführliche Anleitung zur Navigation von einem Ziel zu einem anderen.
- Verschachtelte Grafiken:Ein ausführlicher Leitfaden zum Verschachteln von Navigationsdiagrammen in anderen Diagrammen.