TopAppBar: co to je, nastavení a použití v Jetpack Compose

Co je TopAppBar v Jetpack Compose?

TopAppBar je composable funkce z knihovny Material Design pro Jetpack Compose, která implementuje horní panel aplikace (App Bar). Komponenta zobrazuje titulek aktuální obrazovky, navigační tlačítko vlevo a další akce vpravo.

Na rozdíl od klasického systému View je verze TopAppBar v Compose plně deklarativní: panel se překresluje při změně stavu a není spravován pomocí findViewById. TopAppBar používá koncept slot API, kde jsou title, navigationIcon a actions předávány jako composable lambdy. To umožňuje přizpůsobit libovolný prvek panelu bez dědičnosti.

Podle Google Material Design (2025) existuje TopAppBar v Compose ve třech typech: CenterAlignedTopAppBar (centrovaný titulek), SmallTopAppBar (standardní) a MediumTopAppBar (rozšířený). Každý typ určuje výšku panelu, velikost písma titulku a chování při posouvání. Centrovaná varianta se častěji používá na hlavních obrazovkách a MediumTopAppBar pro stránky s obsahem, kde se titulek při posouvání postupně zmenšuje.

Pro správnou funkci TopAppBar je třeba zohlednit systémové okraje: Insets z WindowInsetsCompat. Podle doporučení Android Developers (2025) volání Modifier.statusBarsPadding() nebo windowInsetsPadding(WindowInsets.systemBars) zabraňuje překrývání panelu se stavovým řádkem.

Parametry TopAppBar: nastavení titulku a modifikátorů

Komponenta TopAppBar přijímá řadu povinných a volitelných parametrů. Hlavním je title, do kterého se předává composable blok s textem titulku. Protože title je @Composable lambda, lze vložit nejen text, ale také ikonu s textem, vyhledávací pole nebo indikátor průběhu.

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

Parametr Modifier umožňuje nastavit okraje, velikost a zarovnání celého panelu. Pomocí Modifier.heightIn lze omezit minimální a maximální výšku. Parametr colors přijímá objekt TopAppBarColors pro přepsání barev pozadí, titulku a ikon.

Ve výchozím nastavení TopAppBar používá barevné schéma z aktuálního MaterialTheme. Pokud je potřeba vlastní paleta, použijte TopAppBarDefaults.smallTopAppBarColors(). V Material3 se barva pozadí automaticky přizpůsobuje surfaceColor ve světlém a tmavém režimu, což eliminuje potřebu ručního nastavení.

Navigační tlačítko v TopAppBar

NavigationIcon je composable blok v levé části TopAppBar, přes který se implementuje navigace. Typické scénáře: otevření Navigation Drawer (ikona Menu), návrat na předchozí obrazovku (ikona ArrowBack) nebo zavření aktuální obrazovky (ikona Close).

Výběr ikony závisí na pozici obrazovky v navigačním zásobníku. Pokud je obrazovka kořenová — zobrazí se ikona Menu pro otevření Drawer. Pokud je obrazovka vnořená — ikona ArrowBack pro návrat. V Compose je tato logika implementována pomocí NavController: aktuální záznam back stack určuje, která ikona se zobrazí.

Podle doporučení Material Design (2025) je šířka navigační oblasti 48 dp — standardní cíl pro dotykovou interakci. Ikona musí být klikatelná s vizuální zpětnou vazbou (ripple). V Compose je to zajištěno zabalením do IconButton s callbackem onClick, který spouští navigaci.

Při použití Scaffold může navigační tlačítko duplikovat DrawerState, který je předáván Scaffoldu, nikoli přímo TopAppBar. V tomto případě navigationIcon odkazuje na stav Drawer přes rememberDrawerState.

Přidání akcí a rozbalovacího menu

Parametr actions v TopAppBar přijímá composable blok s kontextem RowScope, což umožňuje umístit několik ikon nebo tlačítek vpravo od titulku. Každá akce by měla být klikatelný ikonografický prvek: vyhledávání, oznámení, nastavení, oblíbené.

Pro přetékající akce se používá rozbalovací menu přes DropdownMenu. Pokud počet akcí přesáhne tři, přebytečné jsou umístěny do OverflowMenu s ikonou MoreVert. Po stisknutí se otevře seznam skrytých akcí. DropdownMenu se automaticky pozicionuje vzhledem k ikoně.

@Composable
fun TopBarWithOverflow() {
    var menuExpanded by remember { mutableStateOf(false) }
    TopAppBar(
        title = { Text("Profil") },
        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("Nastavení") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("O aplikaci") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Je důležité nastavit contentDescription pro každou ikonu — to je požadavek přístupnosti. Bez popisu TalkBack tlačítko neohlásí. U čistě dekorativních prvků použijte contentDescription = null.

TopAppBar v Material3: Dynamic Color a adaptace

Material3 (M3) je aktuální verze Material Designu doporučená Googlem pro nové projekty. TopAppBar v M3 je implementován přes TopAppBar, CenterAlignedTopAppBar a MediumTopAppBar. Klíčový rozdíl oproti Material2 — vestavěná podpora dynamic color, adaptivní výšky a scroll behavior.

Dynamic Color automaticky vybírá barvy panelu na základě tapety zařízení (Android 12+). TopAppBar v M3 používá surfaceColor pro pozadí a primary pro titulek. Pokud dynamic color není k dispozici, použije se záložní paleta z MaterialTheme. Podle Google Material Design (2025) používá dynamic color v aplikacích 63 % uživatelů Android 12+.

MediumTopAppBar je rozšířená varianta s velkým titulkem (32 sp), který se při posouvání postupně zmenšuje na 20 sp a přeměňuje se na SmallTopAppBar. Tohoto efektu je dosaženo pomocí TopAppBarDefaults.mediumTopAppBarColors() a parametru scrollBehavior. Animace přechodu je řízena TopAppBarState, který sleduje sbalování titulku.

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

Pro Material3 TopAppBar je nutné použít @OptIn(ExperimentalMaterial3Api::class) — anotace označuje, že se API může v budoucích verzích změnit. K roku 2025 zůstává TopAppBar v M3 experimental, ale Google jej doporučuje pro produkci s odpovídajícím ověřením.

ScrollBehavior: skrytí panelu při posouvání

ScrollBehavior je mechanismus, který řídí viditelnost TopAppBar při vertikálním posouvání obsahu. V Jetpack Compose scrollBehavior umožňuje skrýt nebo zmenšit panel pro uvolnění místa, což je užitečné zejména na obrazovkách s velkým seznamem obsahu.

Material3 nabízí tři strategie: enterAlways (panel se objeví při posouvání nahoru a schová se při posouvání dolů), exitUntilCollapsed (panel se schová až po úplném sbalení titulku) a vlastní pomocí implementace rozhraní TopAppBarScrollBehavior. První varianta je vhodná pro obsahové feedy, druhá — pro obrazovky s MediumTopAppBar.

ScrollBehavior vyžaduje koordinaci s LazyColumn nebo LazyRow přes rememberLazyListState(). Stav posouvání je předáván TopAppBar přes parametr scrollBehavior. Komponenta se automaticky přihlásí k událostem posouvání a animuje viditelnost panelu. Podle Android Developers (2025) je enterAlwaysScrollBehavior nejoblíbenější strategií, používanou v 75 % aplikací s posouvatelným TopAppBar.

Nastavení vlastního ScrollBehavior

Pro vytvoření vlastního chování zděďte z TopAppBarScrollBehavior a přepište metody onScroll a onDrag. Vlastní chování je užitečné, když standardní scénáře nepokrývají požadavky návrhu — například panel by se měl skrýt až po překročení určitého prahu posouvání.

Ve výchozím nastavení scrollBehavior nepřidává okraje pro obsah — paddingTop je třeba nastavit ručně pomocí contentPadding v Scaffold nebo pomocí Modifier.padding v LazyColumn. V MediumTopAppBar se okraje automaticky vypočítávají přes TopAppBarState.collapsedFraction.

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

ScrollBehavior je k dispozici pouze v Material3. V Material2 TopAppBar nemá vestavěnou podporu pro skrytí při posouvání — pro podobné chování je vyžadována ruční implementace přes NestedScrollConnection.