Navigation mit der Funktion „Schreiben“

Die Navigationskomponente unterstützt Jetpack Compose-Anwendungen. Sie können zwischen den Komponenten wechseln und dabei die Infrastruktur und Funktionen der Navigationskomponente nutzen.

Einrichten

Wenn Sie Compose unterstützen möchten, verwenden Sie die folgende Abhängigkeit in der build.gradle-Datei Ihres App-Moduls:

Groovy

dependencies {
    def nav_version = "2.8.4"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.8.4"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

Erste Schritte

Implementieren Sie bei der Navigation in einer App einen Navigationshost, ein Navigationsdiagramm und einen Navigationscontroller. Weitere Informationen finden Sie in der Übersicht Navigation.

Informationen zum Erstellen eines NavController in Compose finden Sie im Abschnitt „Compose“ des Artikels Navigationscontroller erstellen.

NavHost erstellen

Informationen zum Erstellen einer NavHost in Compose finden Sie im Abschnitt „Compose“ des Artikels Navigationsgraph entwerfen.

Informationen zum Aufrufen eines Composeable finden Sie in der Architekturdokumentation unter Ziel aufrufen.

Informationen zum Übergeben von Argumenten zwischen zusammensetzbaren Zielen finden Sie im Abschnitt „Zusammenstellen“ des Artikels Navigationsgraph entwerfen.

Komplexe Daten bei der Navigation abrufen

Wir empfehlen dringend, bei der Navigation keine komplexen Datenobjekte zu übergeben, sondern stattdessen die minimal erforderlichen Informationen wie eine eindeutige Kennung oder eine andere Form der ID als Argumente für Navigationsaktionen zu übergeben:

// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))

Komplexe Objekte sollten als Daten in einer einzigen Datenquelle gespeichert werden, z. B. in der Datenebene. Sobald Sie das Ziel erreicht haben, können Sie die erforderlichen Informationen mithilfe der übergebenen ID aus der einzigen „Source of Truth“ laden. Wenn Sie die Argumente in Ihrer ViewModel abrufen möchten, die für den Zugriff auf die Datenebene verantwortlich sind, verwenden Sie die SavedStateHandle der ViewModel:

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val profile = savedStateHandle.toRoute<Profile>()

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)

// …

}

So lassen sich Datenverluste bei Konfigurationsänderungen und Inkonsistenzen beim Aktualisieren oder Ändern des betreffenden Objekts vermeiden.

Eine ausführlichere Erklärung dazu, warum Sie komplexe Daten nicht als Argumente übergeben sollten, sowie eine Liste der unterstützten Argumenttypen finden Sie unter Daten zwischen Zielen übergeben.

Navigation Compose unterstützt Deeplinks, die auch als Teil der composable()-Funktion definiert werden können. Der Parameter deepLinks akzeptiert eine Liste von NavDeepLink-Objekten, die mit der Methode navDeepLink() schnell erstellt werden können:

@Serializable data class Profile(val id: String)
val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  ProfileScreen(id = backStackEntry.toRoute<Profile>().id)
}

Mit diesen Deeplinks kannst du eine bestimmte URL, Aktion oder einen bestimmten MIME-Typ mit einem Composeable verknüpfen. Standardmäßig sind diese Deeplinks für externe Apps nicht sichtbar. Wenn Sie diese Deeplinks extern verfügbar machen möchten, müssen Sie der Datei manifest.xml Ihrer App die entsprechenden <intent-filter>-Elemente hinzufügen. Wenn Sie den Deeplink im vorherigen Beispiel aktivieren möchten, fügen Sie Folgendes in das <activity>-Element des Manifests ein:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

Bei der Navigation wird automatisch ein Deeplink zu diesem Composeable erstellt, wenn der Deeplink von einer anderen App ausgelöst wird.

Mit diesen Deeplinks können Sie auch eine PendingIntent mit dem entsprechenden Deeplink aus einem Composeable erstellen:

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

Sie können diese deepLinkPendingIntent dann wie jede andere deepLinkPendingIntent verwenden, um Ihre App am Deeplink-Ziel zu öffnen.PendingIntent

Verschachtelte Navigation

Informationen zum Erstellen verschachtelter Navigationsgraphen finden Sie unter Verschachtelte Diagramme.

Einbindung in die untere Navigationsleiste

Wenn Sie die NavController auf einer höheren Ebene in Ihrer hierarchischen Zusammenstellung definieren, können Sie die Navigation mit anderen Komponenten wie der Navigationsleiste unten verknüpfen. So können Sie durch Auswahl der Symbole in der unteren Leiste navigieren.

Wenn Sie die Komponenten BottomNavigation und BottomNavigationItem verwenden möchten, fügen Sie Ihrer Android-Anwendung die Abhängigkeit androidx.compose.material hinzu.

Groovy

dependencies {
    implementation "androidx.compose.material:material:1.7.5"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material:material:1.7.5")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Wenn Sie die Elemente in einer unteren Navigationsleiste mit Routen in Ihrem Navigationsgraphen verknüpfen möchten, sollten Sie eine Klasse wie TopLevelRoute hier definieren, die eine Routenklasse und ein Symbol hat.

data class TopLevelRoute<T : Any>(val name: String, val route: T, val icon: ImageVector)

Fügen Sie diese Routen dann in eine Liste ein, die von BottomNavigationItem verwendet werden kann:

val topLevelRoutes = listOf(
   TopLevelRoute("Profile", Profile, Icons.Profile),
   TopLevelRoute("Friends", Friends, Icons.Friends)
)

Rufe in deinem BottomNavigation-Composeable mit der Funktion currentBackStackEntryAsState() den aktuellen NavBackStackEntry ab. Über diesen Eintrag erhalten Sie Zugriff auf den aktuellen NavDestination. Der ausgewählte Status jedes BottomNavigationItem kann dann ermittelt werden, indem die Route des Artikels mit der Route des aktuellen Ziels und seiner übergeordneten Ziele verglichen wird, um Fälle zu bearbeiten, bei denen die verschachtelte Navigation mit der NavDestination-Hierarchie verwendet wird.

Über den Pfad des Artikels wird auch die onClick-Lambda-Funktion mit einem Aufruf von navigate verbunden, damit durch Tippen auf das Element zu diesem Element gewechselt wird. Mit den Flags saveState und restoreState werden der Status und der Backstack dieses Elements korrekt gespeichert und wiederhergestellt, wenn Sie zwischen den Navigationselementen unten wechseln.

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      topLevelRoutes.forEach { topLevelRoute ->
        BottomNavigationItem(
          icon = { Icon(topLevelRoute.icon, contentDescription = topLevelRoute.name) },
          label = { Text(topLevelRoute.name) },
          selected = currentDestination?.hierarchy?.any { it.hasRoute(topLevelRoute.route::class) } == true,
          onClick = {
            navController.navigate(topLevelRoute.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Profile, Modifier.padding(innerPadding)) {
    composable<Profile> { ProfileScreen(...) }
    composable<Friends> { FriendsScreen(...) }
  }
}

Hier nutzen Sie die NavController.currentBackStackEntryAsState()-Methode, um den navController-Status aus der NavHost-Funktion zu extrahieren und für die BottomNavigation-Komponente freizugeben. Das bedeutet, dass BottomNavigation automatisch den aktuellsten Status hat.

Interoperabilität

Wenn Sie die Navigationskomponente mit Compose verwenden möchten, haben Sie zwei Möglichkeiten:

  • Definieren Sie mit der Navigationskomponente ein Navigationsdiagramm für Fragmente.
  • Definieren Sie einen Navigationsgraphen mit einem NavHost in Compose mithilfe von Compose-Zielen. Das ist nur möglich, wenn alle Bildschirme im Navigationsgraphen Composables sind.

Daher wird für Apps mit einer Mischung aus Compose- und Ansichten-Komponenten die fragmentbasierte Navigationskomponente empfohlen. Fragmente enthalten dann ansichtenbasierte Bildschirme, Compose-Bildschirme und Bildschirme, auf denen sowohl Ansichten als auch Compose verwendet werden. Sobald sich der Inhalt jedes Fragments in Compose befindet, besteht der nächste Schritt darin, alle diese Bildschirme mit Navigation Compose zu verknüpfen und alle Fragmente zu entfernen.

Wenn Sie Ziele im Compose-Code ändern möchten, müssen Sie Ereignisse freigeben, die an alle Kompositionen in der Hierarchie übergeben und von ihnen ausgelöst werden können:

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

In Ihrem Fragment stellen Sie eine Verbindung zwischen Compose und der fragmentbasierten Navigationskomponente her, indem Sie die NavController suchen und zum Ziel navigieren:

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

Alternativ können Sie NavController an die Compose-Hierarchie weitergeben. Einfache Funktionen sind jedoch viel wiederverwendbarer und testbarer.

Testen

Entkoppeln Sie den Navigationscode von Ihren Composeable-Zielen, damit jedes Composeable unabhängig vom NavHost-Composeable getestet werden kann.

Das bedeutet, dass du die navController nicht direkt an ein composable übergeben, sondern Navigations-Callbacks als Parameter übergeben solltest. So können alle Ihre Composeables einzeln getestet werden, da in Tests keine Instanz von navController erforderlich ist.

Durch die Indirektion, die das composable-Lambda bietet, können Sie Ihren Navigationscode vom eigentlichen Composeable trennen. Das funktioniert in zwei Richtungen:

  • Übergeben Sie nur geparste Argumente an Ihre Composeable-Funktion.
  • Übergeben Sie Lambdas, die vom Composeable ausgelöst werden sollen, um zur Navigation zu gelangen, und nicht vom NavController selbst.

Ein ProfileScreen-Komposit, das eine userId als Eingabe nimmt und Nutzern ermöglicht, zur Profilseite eines Freundes zu wechseln, könnte beispielsweise die Signatur haben:

@Composable
fun ProfileScreen(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

So funktioniert das ProfileScreen-Element unabhängig von der Navigation und kann unabhängig getestet werden. Das composable-Lambda würde die minimale Logik umfassen, die erforderlich ist, um die Lücke zwischen den Navigations-APIs und Ihrem Composeable zu schließen:

@Serializable data class Profile(id: String)

composable<Profile> { backStackEntry ->
    val profile = backStackEntry.toRoute<Profile>()
    ProfileScreen(userId = profile.id) { friendUserId ->
        navController.navigate(route = Profile(id = friendUserId))
    }
}

Wir empfehlen, Tests zu schreiben, die die Anforderungen an die Navigation in Ihrer App abdecken. Dazu sollten Sie die NavHost, die Navigationsaktionen, die an Ihre Composeables übergeben werden, sowie die einzelnen Bildschirm-Composeables testen.

NavHost testen

Wenn Sie mit dem Testen Ihrer NavHost beginnen möchten , fügen Sie die folgende Abhängigkeit für Navigationstests hinzu:

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

Hülle die NavHost deiner App in ein Composeable ein, das einen NavHostController als Parameter akzeptiert.

@Composable
fun AppNavHost(navController: NavHostController){
  NavHost(navController = navController){ ... }
}

Jetzt können Sie AppNavHost und die gesamte in NavHost definierte Navigationslogik testen, indem Sie eine Instanz des Navigationstest-Artefakts TestNavHostController übergeben. Ein UI-Test, mit dem das Startziel Ihrer App und NavHost überprüft wird, würde so aussehen:

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

Navigationsaktionen testen

Sie können die Navigationsimplementierung auf verschiedene Arten testen. Klicken Sie dazu auf die UI-Elemente und prüfen Sie dann entweder das angezeigte Ziel oder vergleichen Sie die voraussichtliche Route mit der aktuellen Route.

Da Sie die Implementierung Ihrer App testen möchten, sind Klicks auf die Benutzeroberfläche vorzuziehen. Informationen dazu, wie Sie dies zusammen mit einzelnen kombinierbaren Funktionen separat testen, finden Sie im Codelab Testing in Jetpack Compose.

Sie können navController auch verwenden, um Ihre Behauptungen zu überprüfen, indem Sie den aktuellen Pfad mit dem erwarteten Pfad vergleichen. Verwenden Sie dazu navControllers currentBackStackEntry:

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    assertTrue(navController.currentBackStackEntry?.destination?.hasRoute<Profile>() ?: false)
}

Weitere Informationen zu den Grundlagen von Compose-Tests finden Sie unter Compose-Layout testen und im Codelab Testing in Jetpack Compose. Weitere Informationen zu erweiterten Tests von Navigationscode finden Sie im Leitfaden Navigation testen.

Weitere Informationen

Weitere Informationen zu Jetpack Navigation finden Sie unter Erste Schritte mit der Navigationskomponente oder im Codelab „Jetpack Compose Navigation“.

Informationen dazu, wie Sie die Navigation Ihrer App so gestalten, dass sie sich an unterschiedliche Bildschirmgrößen, -ausrichtungen und Formfaktoren anpasst, finden Sie unter Navigation für responsive Benutzeroberflächen.

Eine erweiterte Implementierung der Compose-Navigation in einer modularen App, einschließlich Konzepten wie verschachtelten Diagrammen und der Integration der unteren Navigationsleiste, finden Sie in der Now in Android App auf GitHub.

Produktproben