TopAppBar: Was es ist, Einrichtung und Verwendung in Jetpack Compose

Was ist TopAppBar in Jetpack Compose?

TopAppBar ist eine composable-Funktion aus der Material Design-Bibliothek für Jetpack Compose, die die obere App-Leiste implementiert. Die Komponente zeigt den Titel des aktuellen Bildschirms, einen Navigationsbutton links und zusätzliche Aktionen rechts an.

Anders als das klassische View-System ist die Compose-Version von TopAppBar vollständig deklarativ: Die Leiste wird bei Zustandsänderungen neu gezeichnet, anstatt über findViewById verwaltet zu werden. TopAppBar verwendet das Slot-API-Konzept, bei dem title, navigationIcon und actions als composable-Lambdas übergeben werden. Dies ermöglicht die Anpassung jedes Elements der Leiste ohne Vererbung.

Laut Google Material Design (2025) gibt es TopAppBar in Compose in drei Typen: CenterAlignedTopAppBar (zentrierter Titel), SmallTopAppBar (Standard) und MediumTopAppBar (erweitert). Jeder Typ definiert die Höhe der Leiste, die Schriftgröße des Titels und das Scrollverhalten. Die zentrierte Variante wird häufiger auf Hauptbildschirmen verwendet, während MediumTopAppBar für Inhaltsseiten verwendet wird, bei denen der Titel beim Scrollen sanft verkleinert wird.

Für den korrekten Betrieb von TopAppBar müssen die Systemabstände berücksichtigt werden: Insets aus WindowInsetsCompat. Laut der Empfehlung von Android Developers (2025) verhindert der Aufruf von Modifier.statusBarsPadding() oder windowInsetsPadding(WindowInsets.systemBars) die Überlappung der Leiste mit der Statusleiste.

TopAppBar-Parameter: Titel und Modifikatoren konfigurieren

Die TopAppBar-Komponente akzeptiert mehrere erforderliche und optionale Parameter. Der wichtigste ist title, an den ein composable-Block mit dem Titeltext übergeben wird. Da title eine @Composable-Lambda ist, kann nicht nur Text, sondern auch ein Symbol mit Text, ein Suchfeld oder ein Fortschrittsbalken eingefügt werden.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppTopBar() {
    TopAppBar(
        title = { Text("Main") },
        navigationIcon = {
            IconButton(onClick = { /* open drawer */ }) {
                Icon(
                    Icons.Filled.Menu,
                    contentDescription = "Menu"
                )
            }
        },
        actions = {
            IconButton(onClick = { /* search */ }) {
                Icon(Icons.Filled.Search, contentDescription = "Search")
            }
        }
    )
}

Der Modifier-Parameter ermöglicht das Festlegen von Abständen, Größe und Ausrichtung für die gesamte Leiste. Mit Modifier.heightIn können die minimale und maximale Höhe begrenzt werden. Der Parameter colors akzeptiert ein TopAppBarColors-Objekt zum Überschreiben der Hintergrund-, Titel- und Symbolfarben.

Standardmäßig verwendet TopAppBar das Farbschema des aktuellen MaterialTheme. Wenn eine benutzerdefinierte Palette benötigt wird, verwenden Sie TopAppBarDefaults.smallTopAppBarColors(). In Material3 passt sich die Hintergrundfarbe automatisch an surfaceColor in hellen und dunklen Themen an, sodass keine manuelle Konfiguration erforderlich ist.

Navigationsbutton in TopAppBar

NavigationIcon ist ein composable-Block im linken Teil von TopAppBar, über den die Navigation implementiert wird. Typische Szenarien: Öffnen eines Navigation Drawers (Menüsymbol), Zurückkehren zum vorherigen Bildschirm (Zurück-Pfeil-Symbol) oder Schließen des aktuellen Bildschirms (Schließen-Symbol).

Die Wahl des Symbols hängt von der Position des Bildschirms im Navigationsstapel ab. Wenn der Bildschirm root ist, wird das Menü-Symbol zum Öffnen des Drawers angezeigt. Wenn der Bildschirm verschachtelt ist, wird das Zurück-Pfeil-Symbol zum Zurückkehren angezeigt. In Compose wird diese Logik über NavController implementiert: Der aktuelle Back-Stack-Eintrag bestimmt, welches Symbol angezeigt wird.

Laut Material Design-Empfehlungen (2025) beträgt die Breite des Navigationsbereichs 48 dp — das Standardziel für Touch-Interaktion. Das Symbol sollte mit visuellem Feedback (Ripple) klickbar sein. In Compose wird dies durch Umwickeln mit IconButton mit einem onClick-Callback, der die Navigation auslöst, sichergestellt.

Bei Verwendung von Scaffold kann der Navigationsbutton den DrawerState duplizieren, der an Scaffold und nicht direkt an TopAppBar übergeben wird. In diesem Fall verweist navigationIcon über rememberDrawerState auf den Drawer-Zustand.

Aktionen und Dropdown-Menü hinzufügen

Der actions-Parameter in TopAppBar akzeptiert einen composable-Block mit RowScope-Kontext, der das Platzieren mehrerer Symbole oder Buttons rechts vom Titel ermöglicht. Jede Aktion sollte ein klickbares ikonografisches Element sein: Suche, Benachrichtigungen, Einstellungen, Favoriten.

Überlaufaktionen werden über ein Dropdown-Menü mit DropdownMenu realisiert. Wenn die Anzahl der Aktionen drei übersteigt, werden die zusätzlichen Aktionen in einem OverflowMenu mit dem MoreVert-Symbol platziert. Beim Klicken öffnet sich eine Liste ausgeblendeter Aktionen. DropdownMenu wird automatisch relativ zum Symbol positioniert.

@Composable
fun TopBarWithOverflow() {
    var menuExpanded by remember { mutableStateOf(false) }
    TopAppBar(
        title = { Text("Profile") },
        actions = {
            IconButton(onClick = { /* share */ }) {
                Icon(Icons.Filled.Share, contentDescription = "Share")
            }
            Box {
                IconButton(onClick = { menuExpanded = true }) {
                    Icon(Icons.Filled.MoreVert, contentDescription = "More")
                }
                DropdownMenu(
                    expanded = menuExpanded,
                    onDismissRequest = { menuExpanded = false }
                ) {
                    DropdownMenuItem(text = { Text("Settings") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("About") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Es ist wichtig, für jedes Symbol contentDescription zu setzen — dies ist eine Barrierefreiheitsanforderung. Ohne Beschreibung wird TalkBack den Button nicht ankündigen. Für rein dekorative Elemente verwenden Sie contentDescription = null.

TopAppBar in Material3: Dynamische Farbe und Anpassung

Material3 (M3) ist die aktuelle Version von Material Design, die von Google für neue Projekte empfohlen wird. TopAppBar in M3 wird über TopAppBar, CenterAlignedTopAppBar und MediumTopAppBar implementiert. Der Hauptunterschied zu Material2 ist die integrierte Unterstützung für dynamische Farbe, adaptive Höhe und Scrollverhalten.

Dynamische Farbe wählt die Leistenfarben automatisch basierend auf dem Gerätehintergrundbild (Android 12+) aus. TopAppBar in M3 verwendet surfaceColor für den Hintergrund und primary für den Titel. Wenn dynamische Farbe nicht verfügbar ist, wird eine Fallback-Palette aus MaterialTheme angewendet. Laut Google Material Design (2025) verwenden 63% der Android 12+-Nutzer dynamische Farben in Anwendungen.

MediumTopAppBar ist eine erweiterte Variante mit einem großen Titel (32 sp), der beim Scrollen sanft auf 20 sp schrumpft und sich in SmallTopAppBar verwandelt. Dieser Effekt wird über TopAppBarDefaults.mediumTopAppBarColors() und den Parameter scrollBehavior implementiert. Die Übergangsanimation wird über TopAppBarState gesteuert, das die Titel-Kollaps verfolgt.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MediumTopBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        topBar = {
            MediumTopAppBar(
                title = { Text("Library") },
                navigationIcon = {
                    IconButton(onClick = { }) {
                        Icon(Icons.Filled.Menu, contentDescription = "Menu")
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { padding ->
        LazyColumn(contentPadding = padding) { /* content */ }
    }
}

Für Material3 TopAppBar muss @OptIn(ExperimentalMaterial3Api::class) verwendet werden — die Annotation zeigt an, dass sich die API in zukünftigen Versionen ändern kann. Stand 2025 bleibt TopAppBar in M3 experimentell, aber Google empfiehlt es mit entsprechenden Tests für die Produktion.

ScrollBehavior: Ausblenden der Leiste beim Scrollen

ScrollBehavior ist ein Mechanismus, der die Sichtbarkeit von TopAppBar beim vertikalen Scrollen von Inhalten steuert. In Jetpack Compose ermöglicht scrollBehavior das Ausblenden oder Zusammenklappen der Leiste, um Platz zu schaffen, was besonders auf Bildschirmen mit großen Inhaltslisten nützlich ist.

Material3 bietet drei Strategien: enterAlways (die Leiste erscheint beim Hochscrollen und verschwindet beim Runterrollen), exitUntilCollapsed (die Leiste wird erst ausgeblendet, nachdem der Titel vollständig kollabiert ist) und benutzerdefiniert durch Implementierung des TopAppBarScrollBehavior-Interfaces. Die erste Option eignet sich für Inhaltsfeeds, die zweite für Bildschirme mit MediumTopAppBar.

ScrollBehavior erfordert Koordination mit LazyColumn oder LazyRow über rememberLazyListState(). Der Scroll-Zustand wird über den Parameter scrollBehavior an TopAppBar übergeben. Die Komponente abonniert automatisch Scroll-Ereignisse und animiert die Sichtbarkeit der Leiste. Laut Android Developers (2025) ist enterAlwaysScrollBehavior die beliebteste Strategie, die in 75% der Anwendungen mit scrollbarer TopAppBar verwendet wird.

Benutzerdefiniertes ScrollBehavior konfigurieren

Um ein benutzerdefiniertes Verhalten zu erstellen, erweitern Sie TopAppBarScrollBehavior und überschreiben die Methoden onScroll und onDrag. Ein benutzerdefiniertes Verhalten ist nützlich, wenn Standardszenarien die Designanforderungen nicht abdecken — zum Beispiel, wenn die Leiste erst nach Überschreiten einer bestimmten Scroll-Schwelle ausgeblendet werden soll.

Standardmäßig fügt scrollBehavior keinen Abstand zum Inhalt hinzu — paddingTop muss manuell über contentPadding in Scaffold oder über Modifier.padding in LazyColumn gesetzt werden. In MediumTopAppBar werden die Abstände automatisch über TopAppBarState.collapsedFraction berechnet.

val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
Scaffold(
    topBar = {
        MediumTopAppBar(
            title = { Text("Content") },
            scrollBehavior = scrollBehavior
        )
    }
) { padding ->
    LazyColumn(contentPadding = padding) { /* items */ }
}

ScrollBehavior ist nur in Material3 verfügbar. Material2 TopAppBar hat keine integrierte Unterstützung zum Ausblenden beim Scrollen — für ein ähnliches Verhalten ist eine manuelle Implementierung über NestedScrollConnection erforderlich.