Zu einem Ziel navigieren

Die Komponente „Navigation“ bietet eine einfache und allgemeine Möglichkeit, zu einem Ziel zu navigieren. Diese Schnittstelle unterstützt eine Reihe von Kontexten und UI-Frameworks. Sie können die Navigationskomponente beispielsweise mit der Funktion „Compose“, Ansichten, Fragmenten, Aktivitäten und sogar benutzerdefinierten UI-Frameworks verwenden.

In diesem Leitfaden wird beschrieben, wie Sie mit der Navigationskomponente in verschiedenen Kontexten zu einem Ziel navigieren können.

NavController verwenden

Der Schlüsseltyp, mit dem Sie zwischen Zielen wechseln, ist NavController. Weitere Informationen zur Klasse selbst und zum Erstellen einer Instanz dieser Klasse finden Sie unter Navigationscontroller erstellen. In diesem Leitfaden wird die Verwendung beschrieben.

Navigieren

Unabhängig davon, welches UI-Framework Sie verwenden, gibt es eine einzelne Funktion, mit der Sie zu einem Ziel wechseln können: NavController.navigate().

Für navigate() sind viele Überlastungen verfügbar. Die Überlastung, die Sie wählen sollten, entspricht genau Ihrem Kontext. Sie sollten beispielsweise eine Überlastung verwenden, wenn Sie zu einer zusammensetzbaren Funktion navigieren, und eine andere, wenn Sie zu einer Ansicht wechseln.

In den folgenden Abschnitten werden einige der navigate()-Schlüsselüberlastungen beschrieben, die Sie verwenden können.

Zu einer zusammensetzbaren Funktion wechseln

Um eine zusammensetzbare Funktion aufzurufen, sollten Sie NavController.navigate<T> verwenden. Bei dieser Überlastung verwendet navigate() ein einzelnes route-Argument, für das Sie einen Typ übergeben. Er dient als Schlüssel zu einem Ziel.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Wenn Sie eine zusammensetzbare Funktion in der Navigationsgrafik aufrufen möchten, definieren Sie zuerst die NavGraph so, dass jedes Ziel einem Typ entspricht. Bei zusammensetzbaren Funktionen verwenden Sie dazu die Funktion composable().

Ereignisse aus zusammensetzbaren Funktionen freigeben

Wenn eine zusammensetzbare Funktion zu einem neuen Bildschirm wechseln muss, sollten Sie keinen Verweis auf die NavController übergeben, damit sie navigate() direkt aufrufen kann. Gemäß den Prinzipien des Unidirektionalen Datenflusses (UDF) sollte die zusammensetzbare Funktion stattdessen ein Ereignis verfügbar machen, das von NavController verarbeitet wird.

Genauer gesagt sollte Ihre zusammensetzbare Funktion einen Parameter vom Typ () -> Unit haben. Wenn Sie Ihrem NavHost mit der Funktion composable() Ziele hinzufügen, übergeben Sie der zusammensetzbaren Funktion einen Aufruf an NavController.navigate().

Im folgenden Unterabschnitt finden Sie ein Beispiel dafür.

Warnung :Übergeben Sie NavController nicht an zusammensetzbare Funktionen. Geben Sie ein Ereignis wie hier beschrieben frei.

Beispiel

Betrachten Sie zur Veranschaulichung der vorherigen Abschnitte diese Punkte im folgenden Snippet:

1. Jedes Ziel im Diagramm wird mithilfe einer Route erstellt. Dabei handelt es sich um ein serielles Objekt oder eine Klasse, die die von diesem Ziel benötigten Daten beschreibt.
2. Die zusammensetzbare Funktion MyAppNavHost enthält die Instanz NavController.
3. Dementsprechend sollten navigate()-Aufrufe dort erfolgen und nicht in einer niedrigeren zusammensetzbaren Funktion wie ProfileScreen.
4. ProfileScreen enthält eine Schaltfläche, über die der Nutzer zu FriendsList weitergeleitet wird, wenn er darauf klickt. Es wird jedoch nicht navigate() selbst aufgerufen.
5. Stattdessen ruft die Schaltfläche eine Funktion auf, die als Parameter onNavigateToFriends verfügbar gemacht wird.
6. Wenn MyAppNavHost dem Navigationsdiagramm ProfileScreen hinzufügt, übergibt es für onNavigateToFriends eine Lambda-Funktion, die navigate(route = FriendsList aufruft.
7. Dadurch wird sichergestellt, dass der Nutzer korrekt zu FriendsListScreen navigiert, wenn er auf die Schaltfläche ProfileScreen drückt.

@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),

) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = FriendsList) },
                /*...*/
            )
        }
        composable<FriendsList> { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

Warnung: Rufen Sie navigate() nur im Rahmen eines Callbacks und nicht als Teil der zusammensetzbaren Funktion selbst auf. So wird verhindert, dass navigate() bei jeder Neuzusammensetzung aufgerufen wird.

Mit Ganzzahl-ID navigieren

Rufen Sie die navigate(int)-Überlast auf, um mit einer Ganzzahl-ID zu einem Ziel zu gelangen. Er verwendet die Ressourcen-ID einer Aktion oder eines Ziels. Das folgende Code-Snippet zeigt, wie Sie mit dieser Überlastung zum ViewTransactionsFragment wechseln können:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

Wenn Sie IDs verwenden, sollten Sie nach Möglichkeit Aktionen verwenden. Aktionen liefern zusätzliche Informationen in Ihrem Navigationsdiagramm und zeigen visuell, wie Ihre Ziele miteinander verbunden sind.

Hinweis :Es gibt drei Varianten von Navigation.createNavigateOnClickListener() für Schaltflächen. Diese Varianten sind nützlich, wenn Sie die Programmiersprache Java verwenden. Wenn Sie Kotlin verwenden, ist OnClickListener eine SAM-Schnittstelle, sodass Sie ein nachgestelltes Lambda verwenden können. Dieser Ansatz kann kürzer und einfacher zu lesen sein, als createNavigateOnClickListener() direkt aufzurufen.

Hinweis: Informationen zur Handhabung anderer gängiger UI-Komponenten wie der oberen App-Leiste und der unteren Navigation finden Sie unter UI-Komponenten mit NavigationUI aktualisieren.

Mit NavDeepLinkRequest navigieren

Verwenden Sie die navigate(NavDeepLinkRequest)-Überlastung, um ein implizites Deeplink-Ziel aufzurufen. Das folgende Snippet stellt eine Implementierung dieser Methode bereit:

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

Im Gegensatz zur Navigation mit Aktions- oder Ziel-IDs können Sie jeden Deeplink in der Grafik aufrufen, unabhängig davon, ob das Ziel sichtbar ist. Sie können ein Ziel in der aktuellen Grafik oder ein Ziel auf einer ganz anderen Grafik aufrufen.

Achtung :Beim Navigieren mit NavDeepLinkRequest wird der Back Stack nicht zurückgesetzt. Dieses Verhalten unterscheidet sich von anderen Formen der Deeplink-Navigation. popUpTo() und popUpToInclusive() entfernen jedoch weiterhin Ziele aus dem Back-Stack, so als ob Sie eine ID verwenden würden.

Hinweis: Der Einfachheit halber können Sie auch navigate(Uri) verwenden, bei der Uri in DeepLinkRequest eingeschlossen ist.

Aktionen und MIME-Typen

Zusätzlich zu Uri unterstützt NavDeepLinkRequest auch Deeplinks mit Aktionen und MIME-Typen. Verwenden Sie fromAction() oder setAction(), um der Anfrage eine Aktion hinzuzufügen. Verwenden Sie fromMimeType() oder setMimeType(), um einer Anfrage einen MIME-Typ hinzuzufügen.

Damit ein NavDeepLinkRequest mit einem impliziten Deeplink-Ziel korrekt übereinstimmt, müssen URI, Aktion und MIME-Typ mit dem NavDeepLink im Ziel übereinstimmen. URIs müssen dem Muster entsprechen, die Aktionen müssen genau übereinstimmen und die MIME-Typen müssen verwandt sein. Beispiel: image/jpg stimmt mit image/\* überein.

Weitere Kontexte

In diesem Dokument wird die Verwendung von NavController.navigate() in den gängigsten Anwendungsfällen beschrieben. Die Funktion hat jedoch eine Reihe von Überlasten, die Sie in verschiedenen Kontexten und in Verbindung mit jedem Ui-Framework verwenden können. Weitere Informationen zu diesen Überlastungen finden Sie in der Referenzdokumentation.

Weitere Informationen

Weitere Informationen finden Sie auf den folgenden Seiten:

• Navigations-Controller erstellen
• Navigation und Back Stack
• Optionen aufrufen
• Eingabesicherheit in Kotlin DSL und Navigation Compose