TopAppBar: mi ez, beállítás és használat a Jetpack Compose-ban

Mi az a TopAppBar a Jetpack Compose-ban?

TopAppBar egy composable függvény a Material Design könyvtárból Jetpack Compose-hoz, amely az alkalmazás felső paneljét (App Bar) valósítja meg. A komponens megjeleníti az aktuális képernyő címét, a navigációs gombot bal oldalon és a kiegészítő műveleteket jobb oldalon.

Ellentétben a klasszikus View rendszerrel, a TopAppBar Compose verziója teljesen deklaratív: a panel átrajzolódik állapotváltozáskor, és nem findViewById-n keresztül kezelik. A TopAppBar a slot API koncepciót használja, ahol a title, navigationIcon és actions composable lambdákként kerülnek átadásra. Ez lehetővé teszi a panel bármely eleme testreszabását öröklődés nélkül.

A Google Material Design (2025) szerint a TopAppBar a Compose-ban három típusban létezik: CenterAlignedTopAppBar (középre igazított cím), SmallTopAppBar (szabvány) és MediumTopAppBar (kibővített). Minden típus meghatározza a panel magasságát, a cím betűméretét és a görgetéskor tanúsított viselkedést. A középre igazított változatot gyakrabban használják főképernyőkön, a MediumTopAppBar-t pedig tartalmas oldalakon, ahol a cím görgetéskor fokozatosan kicsinyül.

A TopAppBar helyes működéséhez figyelembe kell venni a rendszermargókat: Insets a WindowInsetsCompat-ból. Az Android Developers (2025) ajánlása szerint a Modifier.statusBarsPadding() vagy windowInsetsPadding(WindowInsets.systemBars) meghívása megakadályozza, hogy a panel rákerüljön az állapotsávra.

TopAppBar paraméterek: cím és modifikátorok beállítása

A TopAppBar komponens számos kötelező és opcionális paramétert fogad el. A fő paraméter a title, amelybe egy composable blokk kerül a címszöveggel. Mivel a title egy @Composable lambda, nem csak szöveg, hanem ikon szöveggel, keresősáv vagy folyamatjelző is beilleszthető.

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

A Modifier paraméter lehetővé teszi a margók, méret és igazítás beállítását a teljes panel számára. A Modifier.heightIn segítségével korlátozható a minimális és maximális magasság. A colors paraméter egy TopAppBarColors objektumot fogad el a háttér, cím és ikonok színeinek felülírásához.

Alapértelmezésben a TopAppBar az aktuális MaterialTheme színsémáját használja. Ha egyedi palettára van szükség, használja a TopAppBarDefaults.smallTopAppBarColors() függvényt. A Material3-ban a háttérszín automatikusan igazodik a surfaceColor értékhez világos és sötét témában, kiküszöbölve a kézi beállítás szükségességét.

Navigációs gomb a TopAppBar-ban

NavigationIcon egy composable blokk a TopAppBar bal részében, amelyen keresztül a navigáció megvalósul. Tipikus forgatókönyvek: Navigation Drawer megnyitása (Menu ikon), visszatérés az előző képernyőre (ArrowBack ikon) vagy az aktuális képernyő bezárása (Close ikon).

Az ikon választása függ a képernyő navigációs veremben elfoglalt helyétől. Ha a képernyő gyökér — a Menu ikon jelenik meg a Drawer megnyitásához. Ha a képernyő beágyazott — az ArrowBack ikon a visszatéréshez. Compose-ban ezt a logikát a NavController valósítja meg: az aktuális back stack bejegyzés határozza meg, melyik ikon jelenjen meg.

A Material Design (2025) ajánlása szerint a navigációs terület szélessége 48 dp — a szabvány célpont érintőinterakcióhoz. Az ikonnak kattinthatónak kell lennie vizuális visszajelzéssel (ripple). Compose-ban ezt az IconButton-ba csomagolás biztosítja egy onClick callback-kel, amely elindítja a navigációt.

A Scaffold használatakor a navigációs gomb megkettőzheti a Scaffold-nak átadott DrawerState állapotot, nem közvetlenül a TopAppBar-nak. Ebben az esetben a navigationIcon a rememberDrawerState-n keresztül hivatkozik a Drawer állapotára.

Műveletek és legördülő menü hozzáadása

A TopAppBar actions paramétere egy composable blokkot fogad el RowScope kontextussal, lehetővé téve több ikon vagy gomb elhelyezését a címtől jobbra. Minden műveletnek kattintható ikonográfiai elemnek kell lennie: keresés, értesítések, beállítások, kedvencek.

A túlcsorduló műveletekhez legördülő menü használatos a DropdownMenu-n keresztül. Ha a műveletek száma meghaladja a hármat, a többlet a MoreVert ikonnal ellátott OverflowMenu-ba kerül. Megnyomáskor a rejtett műveletek listája megnyílik. A DropdownMenu automatikusan pozicionálódik az ikonhoz képest.

@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("Beállítások") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("Névjegy") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Fontos beállítani a contentDescription értéket minden ikonhoz — ez akadálymentesítési követelmény. Leírás nélkül a TalkBack nem olvassa fel a gombot. Tisztán dekoratív elemekhez használja a contentDescription = null értéket.

TopAppBar a Material3-ban: Dynamic Color és adaptáció

A Material3 (M3) a Material Design jelenlegi verziója, amelyet a Google ajánl új projektekhez. A TopAppBar az M3-ban TopAppBar, CenterAlignedTopAppBar és MediumTopAppBar segítségével valósul meg. A fő különbség a Material2-höz képest a beépített dynamic color, adaptív magasság és scroll behavior támogatása.

A Dynamic Color automatikusan kiválasztja a panel színeit a készülék háttérképe alapján (Android 12+). A TopAppBar az M3-ban surfaceColor-t használ a háttérhez és primary-t a címhez. Ha a dynamic color nem érhető el, a MaterialTheme tartalék palettája kerül alkalmazásra. A Google Material Design (2025) szerint az Android 12+ felhasználók 63%-a használ dynamic color-t alkalmazásokban.

A MediumTopAppBar egy kibővített változat nagy címmel (32 sp), amely görgetéskor fokozatosan 20 sp-re csökken, átalakulva SmallTopAppBar-rá. Ezt a hatást a TopAppBarDefaults.mediumTopAppBarColors() és a scrollBehavior paraméter valósítja meg. Az átmeneti animációt a TopAppBarState vezérli, amely a cím összecsukását követi.

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

A Material3 TopAppBar-hoz használni kell a @OptIn(ExperimentalMaterial3Api::class) annotációt — ez jelzi, hogy az API a jövőben változhat. 2025-ben a TopAppBar az M3-ban experimental marad, de a Google ajánlja éles használatra megfelelő ellenőrzés mellett.

ScrollBehavior: panel elrejtése görgetéskor

ScrollBehavior az a mechanizmus, amely a TopAppBar láthatóságát kezeli tartalom függőleges görgetésekor. A Jetpack Compose-ban a scrollBehavior lehetővé teszi a panel elrejtését vagy kicsinyítését a hely felszabadítása érdekében, ami különösen hasznos nagy tartalomlistával rendelkező képernyőkön.

A Material3 három stratégiát kínál: enterAlways (a panel felgörgetéskor megjelenik, legörgetéskor elrejtődik), exitUntilCollapsed (a panel csak a cím teljes összecsukása után rejtődik el) és egyedi a TopAppBarScrollBehavior interfész implementálásával. Az első változat tartalomcsatornákhoz, a második a MediumTopAppBar-t használó képernyőkhöz alkalmas.

A ScrollBehavior koordinációt igényel a LazyColumn vagy LazyRow osztályokkal a rememberLazyListState()-n keresztül. A görgetés állapota a scrollBehavior paraméteren keresztül kerül átadásra a TopAppBar-nak. A komponens automatikusan feliratkozik a görgetési eseményekre és animálja a panel láthatóságát. Az Android Developers (2025) szerint az enterAlwaysScrollBehavior a legnépszerűbb stratégia, amelyet az alkalmazások 75%-a használ görgethető TopAppBar-ral.

Egyéni ScrollBehavior beállítása

Egyéni viselkedés létrehozásához örökítse a TopAppBarScrollBehavior osztályból és írja felül az onScroll és onDrag metódusokat. Az egyéni viselkedés akkor hasznos, ha a szabvány forgatókönyvek nem fedik le a tervezési követelményeket — például a panel csak egy bizonyos görgetési küszöb túllépése után rejtődjön el.

Alapértelmezésben a scrollBehavior nem ad margót a tartalomhoz — a paddingTop értéket kézzel kell beállítani a Scaffold contentPadding paraméterén vagy a LazyColumn Modifier.padding paraméterén keresztül. A MediumTopAppBar-ban a margók automatikusan kiszámítódnak a TopAppBarState.collapsedFraction segítségével.

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

A ScrollBehavior csak Material3-ban érhető el. A Material2-ben a TopAppBar nem rendelkezik beépített támogatással a görgetéskor történő elrejtéshez — hasonló viselkedéshez kézi implementáció szükséges a NestedScrollConnection segítségével.