TopAppBar: ano ito, pagsasaayos at paggamit sa Jetpack Compose

Ano ang TopAppBar sa Jetpack Compose?

TopAppBar ay isang composable function mula sa Material Design library para sa Jetpack Compose na nagpapatupad ng itaas na panel ng app (App Bar). Ang component ay nagpapakita ng pamagat ng kasalukuyang screen, navigation button sa kaliwa, at karagdagang mga aksyon sa kanan.

Hindi tulad ng klasikong View system, ang Compose version ng TopAppBar ay ganap na declarative: ang panel ay iginuhit muli kapag nagbago ang estado, hindi pinamamahalaan sa pamamagitan ng findViewById. Gumagamit ang TopAppBar ng konsepto ng slot API, kung saan ang title, navigationIcon at actions ay ipinapasa bilang composable lambdas. Ito ay nagpapahintulot ng pag-customize ng anumang elemento ng panel nang walang inheritance.

Ayon sa Google Material Design (2025), ang TopAppBar sa Compose ay may tatlong uri: CenterAlignedTopAppBar (naka-center na pamagat), SmallTopAppBar (standard), at MediumTopAppBar (pinalawak). Ang bawat uri ay tumutukoy sa taas ng panel, laki ng font ng pamagat, at pag-uugali habang nag-scroll. Ang naka-center na variant ay mas madalas ginagamit sa mga pangunahing screen, at ang MediumTopAppBar para sa mga pahina na may content kung saan ang pamagat ay unti-unting lumiliit habang nag-scroll.

Para sa tamang pagpapatakbo ng TopAppBar, dapat isaalang-alang ang system margins: Insets mula sa WindowInsetsCompat. Ayon sa rekomendasyon ng Android Developers (2025), ang pagtawag sa Modifier.statusBarsPadding() o windowInsetsPadding(WindowInsets.systemBars) ay pumipigil sa panel na matabunan ang status bar.

Mga Parameter ng TopAppBar: pagsasaayos ng pamagat at mga modifier

Ang component na TopAppBar ay tumatanggap ng ilang mandatory at opsyonal na parameter. Ang pangunahin ay ang title, kung saan ipinapasa ang isang composable block na may text ng pamagat. Dahil ang title ay isang @Composable lambda, hindi lamang text kundi pati icon na may text, search bar, o progress bar ay maaaring ilagay.

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

Ang parameter na Modifier ay nagpapahintulot ng pagtatakda ng mga margin, laki, at alignment ng buong panel. Sa pamamagitan ng Modifier.heightIn, maaaring limitahan ang minimum at maximum na taas. Ang parameter na colors ay tumatanggap ng TopAppBarColors object para sa pag-override ng mga kulay ng background, pamagat, at mga icon.

Bilang default, ang TopAppBar ay gumagamit ng color scheme mula sa kasalukuyang MaterialTheme. Kung kailangan ng custom na palette, gamitin ang TopAppBarDefaults.smallTopAppBarColors(). Sa Material3, ang kulay ng background ay awtomatikong umaangkop sa surfaceColor sa light at dark na tema, na nag-aalis ng pangangailangan para sa manual na pagsasaayos.

Navigation button sa TopAppBar

NavigationIcon ay isang composable block sa kaliwang bahagi ng TopAppBar kung saan ipinapatupad ang navigation. Mga tipikal na scenario: pagbukas ng Navigation Drawer (icon ng Menu), pagbalik sa nakaraang screen (icon ng ArrowBack), o pagsara ng kasalukuyang screen (icon ng Close).

Ang pagpili ng icon ay depende sa posisyon ng screen sa navigation stack. Kung ang screen ay root — ang icon na Menu ay ipinapakita para buksan ang Drawer. Kung ang screen ay naka-nest — ang icon na ArrowBack para bumalik. Sa Compose, ang lohika na ito ay ipinapatupad sa pamamagitan ng NavController: ang kasalukuyang back stack entry ay tumutukoy kung aling icon ang ipapakita.

Ayon sa rekomendasyon ng Material Design (2025), ang lapad ng navigation area ay 48 dp — ang standard na target para sa touch interaction. Ang icon ay dapat na clickable na may visual feedback (ripple). Sa Compose, ito ay sinisiguro sa pamamagitan ng pagbalot sa IconButton na may onClick callback na nag-uumpisa ng navigation.

Kapag gumagamit ng Scaffold, ang navigation button ay maaaring mag-duplicate ng DrawerState na ipinapasa sa Scaffold, hindi direkta sa TopAppBar. Sa kasong ito, ang navigationIcon ay tumutukoy sa estado ng Drawer sa pamamagitan ng rememberDrawerState.

Pagdagdag ng mga aksyon at dropdown menu

Ang parameter na actions sa TopAppBar ay tumatanggap ng composable block na may konteksto ng RowScope, na nagpapahintulot ng paglalagay ng maraming icon o button sa kanan ng pamagat. Bawat aksyon ay dapat na clickable iconographic element: paghahanap, mga notification, mga setting, mga paborito.

Para sa mga sobrang aksyon, ginagamit ang dropdown menu sa pamamagitan ng DropdownMenu. Kung ang bilang ng mga aksyon ay lumampas sa tatlo, ang mga sobrang aksyon ay inilalagay sa OverflowMenu na may icon na MoreVert. Kapag pinindot, ang listahan ng mga nakatagong aksyon ay bubukas. Ang DropdownMenu ay awtomatikong pumuwesto kaugnay ng icon.

@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("Mga Setting") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("Tungkol") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Mahalagang itakda ang contentDescription para sa bawat icon — ito ay isang pangangailangan ng accessibility. Kung walang paglalarawan, hindi iaanunsyo ng TalkBack ang button. Para sa purong dekoratibong elemento, gamitin ang contentDescription = null.

TopAppBar sa Material3: Dynamic Color at adaptasyon

Ang Material3 (M3) ay ang kasalukuyang bersyon ng Material Design, na inirerekomenda ng Google para sa mga bagong proyekto. Ang TopAppBar sa M3 ay ipinapatupad sa pamamagitan ng TopAppBar, CenterAlignedTopAppBar, at MediumTopAppBar. Ang pangunahing pagkakaiba mula sa Material2 — ang built-in na suporta para sa dynamic color, adaptive na taas, at scroll behavior.

Ang Dynamic Color ay awtomatikong pumipili ng mga kulay ng panel batay sa wallpaper ng device (Android 12+). Ang TopAppBar sa M3 ay gumagamit ng surfaceColor para sa background at primary para sa pamagat. Kung ang dynamic color ay hindi available, ang fallback palette mula sa MaterialTheme ay inilalapat. Ayon sa Google Material Design (2025), 63% ng mga user ng Android 12+ ay gumagamit ng dynamic color sa mga app.

Ang MediumTopAppBar ay isang pinalawak na variant na may malaking pamagat (32 sp), na habang nag-scroll ay unti-unting lumiliit sa 20 sp at nagiging SmallTopAppBar. Ang epektong ito ay natatamo sa pamamagitan ng TopAppBarDefaults.mediumTopAppBarColors() at parameter na scrollBehavior. Ang transition animation ay kinokontrol ng TopAppBarState na sumusubaybay sa pagliit ng pamagat.

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

Para sa Material3 TopAppBar, dapat gamitin ang @OptIn(ExperimentalMaterial3Api::class) — ang anotasyon ay nagpapahiwatig na ang API ay maaaring magbago sa mga susunod na bersyon. Sa taong 2025, ang TopAppBar sa M3 ay nananatiling experimental, ngunit inirerekomenda ito ng Google para sa produksyon na may angkop na pag-verify.

ScrollBehavior: pagtatago ng panel habang nag-scroll

ScrollBehavior ay ang mekanismo na namamahala sa visibility ng TopAppBar habang nag-vevertical scroll ng content. Sa Jetpack Compose, ang scrollBehavior ay nagpapahintulot na itago o liitin ang panel para magbakante ng espasyo, na lalong kapaki-pakinabang sa mga screen na may malaking listahan ng content.

Ang Material3 ay nag-aalok ng tatlong estratehiya: enterAlways (ang panel ay lilitaw kapag nag-scroll pataas at nagtatago kapag nag-scroll pababa), exitUntilCollapsed (ang panel ay nagtatago lamang pagkatapos ng kumpletong pagliit ng pamagat), at custom sa pamamagitan ng implementasyon ng TopAppBarScrollBehavior interface. Ang unang variant ay angkop para sa content feeds, ang pangalawa — para sa mga screen na may MediumTopAppBar.

Ang ScrollBehavior ay nangangailangan ng koordinasyon sa LazyColumn o LazyRow sa pamamagitan ng rememberLazyListState(). Ang estado ng scroll ay ipinapasa sa TopAppBar sa pamamagitan ng parameter na scrollBehavior. Ang component ay awtomatikong nag-subscribe sa mga scroll event at nag-a-animate ng visibility ng panel. Ayon sa Android Developers (2025), ang enterAlwaysScrollBehavior ay ang pinakasikat na estratehiya, ginagamit sa 75% ng mga app na may scrollable na TopAppBar.

Pagsasaayos ng Custom na ScrollBehavior

Para gumawa ng custom na pag-uugali, magmana mula sa TopAppBarScrollBehavior at i-override ang mga method na onScroll at onDrag. Ang custom na pag-uugali ay kapaki-pakinabang kapag ang standard na mga scenario ay hindi sumasaklaw sa mga kinakailangan ng disenyo — halimbawa, ang panel ay dapat magtago lamang pagkatapos lumampas sa isang tiyak na threshold ng scroll.

Bilang default, ang scrollBehavior ay hindi nagdaragdag ng margin para sa content — ang paddingTop ay dapat manu-manong itakda sa pamamagitan ng contentPadding sa Scaffold o sa pamamagitan ng Modifier.padding sa LazyColumn. Sa MediumTopAppBar, ang mga margin ay awtomatikong kinakalkula sa pamamagitan ng TopAppBarState.collapsedFraction.

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

Ang ScrollBehavior ay available lamang sa Material3. Sa Material2, ang TopAppBar ay walang built-in na suporta para sa pagtatago habang nag-scroll — para sa katulad na pag-uugali, kinakailangan ang manual na implementasyon sa pamamagitan ng NestedScrollConnection.