TopAppBar: nedir, kurulumu ve Jetpack Compose'da kullanımı

Jetpack Compose'da TopAppBar Nedir?

TopAppBar, Jetpack Compose için Material Design kitaplığından üst uygulama çubuğunu uygulayan bir composable işlevidir. Bileşen, geçerli ekranın başlığını, solda bir gezinme düğmesini ve sağda ek eylemleri görüntüler.

Klasik View sisteminin aksine, TopAppBar'ın Compose sürümü tamamen bildirimseldir: findViewById aracılığıyla yönetilmek yerine, durum değiştiğinde çubuk yeniden çizilir. TopAppBar, title, navigationIcon ve actions'ın composable lambda olarak iletildiği slot API kavramını kullanır. Bu, kalıtım olmadan çubuğun herhangi bir öğesini özelleştirmeye olanak tanır.

Google Material Design'a (2025) göre Compose'da TopAppBar üç türde gelir: CenterAlignedTopAppBar (ortalanmış başlık), SmallTopAppBar (standart) ve MediumTopAppBar (genişletilmiş). Her tür, çubuk yüksekliğini, başlık yazı tipi boyutunu ve kaydırma davranışını tanımlar. Ortalanmış varyant ana ekranlarda daha sık kullanılırken, MediumTopAppBar kaydırma sırasında başlığın kademeli olarak küçüldüğü içerik sayfaları için kullanılır.

TopAppBar'ın doğru çalışması için sistem kenar boşluklarının dikkate alınması gerekir: WindowInsetsCompat'tan Insets. Android Developers (2025) tavsiyesine göre Modifier.statusBarsPadding() veya windowInsetsPadding(WindowInsets.systemBars) çağrısı yapmak, çubuğun durum çubuğuyla örtüşmesini önler.

TopAppBar Parametreleri: Başlık ve Değiştiricileri Yapılandırma

TopAppBar bileşeni birkaç zorunlu ve isteğe bağlı parametre kabul eder. Ana parametre title'dır ve başlık metnini içeren bir composable blok iletilir. title bir @Composable lambda olduğundan, yalnızca metin değil, aynı zamanda metin içeren bir simge, arama alanı oluşturma veya ilerleme görüntüleme de yapabilirsiniz.

@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")
            }
        }
    )
}

Modifier parametresi, tüm çubuk için dolgu, boyut ve hizalamayı ayarlamaya olanak tanır. Modifier.heightIn ile minimum ve maksimum yükseklik sınırlanabilir. colors parametresi, arka plan, başlık ve simge renklerini geçersiz kılmak için bir TopAppBarColors nesnesi kabul eder.

Varsayılan olarak TopAppBar, geçerli MaterialTheme'den renk şemasını kullanır. Özel bir palet gerekiyorsa TopAppBarDefaults.smallTopAppBarColors() kullanın. Material3'te arka plan rengi, açık ve koyu temalarda otomatik olarak surfaceColor'a uyum sağlayarak manuel yapılandırma ihtiyacını ortadan kaldırır.

TopAppBar'da Gezinme Düğmesi

NavigationIcon, TopAppBar'ın sol kısmında, gezinmenin uygulandığı bir composable bloktur. Tipik senaryolar: Gezinme Drawer'ını açma (Menü simgesi), önceki ekrana dönme (Geri Ok simgesi) veya geçerli ekranı kapatma (Kapat simgesi).

Simge seçimi, ekranın gezinme yığınındaki konumuna bağlıdır. Ekran kök ise Drawer'ı açmak için Menü simgesi görüntülenir. Ekran iç içeyse geri dönmek için Geri Ok simgesi görüntülenir. Compose'da bu mantık NavController aracılığıyla uygulanır: geçerli geri yığın girişi hangi simgenin gösterileceğini belirler.

Material Design (2025) tavsiyelerine göre gezinme alanının genişliği 48 dp'dir — dokunma etkileşimi için standart hedef. Simge, görsel geri bildirim (dalga efekti) ile tıklanabilir olmalıdır. Compose'da bu, gezinmeyi tetikleyen bir onClick geri çağrısına sahip IconButton içine sarılarak sağlanır.

Scaffold kullanıldığında, gezinme düğmesi doğrudan TopAppBar'a değil Scaffold'a iletilen DrawerState'i kopyalayabilir. Bu durumda navigationIcon, rememberDrawerState aracılığıyla Drawer durumuna başvurur.

Eylemler ve Açılır Menü Ekleme

TopAppBar'daki actions parametresi, RowScope bağlamına sahip bir composable blok kabul ederek başlığın sağına birden çok simge veya düğme yerleştirmeye olanak tanır. Her eylem tıklanabilir bir ikonografik öğe olmalıdır: arama, bildirimler, ayarlar, favoriler.

Taşan eylemler için DropdownMenu aracılığıyla bir açılır menü kullanılır. Eylem sayısı üçü aşarsa, fazladan eylemler MoreVert simgesiyle OverflowMenu'ye yerleştirilir. Tıklandığında gizli eylemlerin bir listesi açılır. DropdownMenu, simgeye göre otomatik olarak konumlandırılır.

@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 */ })
                }
            }
        }
    )
}

Her simge için contentDescription ayarlamak önemlidir — bu bir erişilebilirlik gereksinimidir. Açıklama olmadan TalkBack düğmeyi duyurmayacaktır. Yalnızca dekoratif öğeler için contentDescription = null kullanın.

Material3'te TopAppBar: Dinamik Renk ve Uyum

Material3 (M3), Google tarafından yeni projeler için önerilen Material Design'ın güncel sürümüdür. M3'te TopAppBar, TopAppBar, CenterAlignedTopAppBar ve MediumTopAppBar aracılığıyla uygulanır. Material2'den temel fark, dinamik renk, uyarlanabilir yükseklik ve kaydırma davranışı için yerleşik destektir.

Dinamik Renk, çubuk renklerini cihaz duvar kağıdına (Android 12+) göre otomatik olarak seçer. M3'te TopAppBar arka plan için surfaceColor ve başlık için primary kullanır. Dinamik renk mevcut değilse, MaterialTheme'den bir yedek palet uygulanır. Google Material Design'a (2025) göre Android 12+ kullanıcılarının %63'ü uygulamalarda dinamik renk kullanmaktadır.

MediumTopAppBar, kaydırma sırasında kademeli olarak 20 sp'ye küçülen ve SmallTopAppBar'a dönüşen büyük bir başlığa (32 sp) sahip genişletilmiş bir varyanttır. Bu efekt, TopAppBarDefaults.mediumTopAppBarColors() ve scrollBehavior parametresi aracılığıyla uygulanır. Geçiş animasyonu, başlık daralmasını izleyen TopAppBarState aracılığıyla kontrol edilir.

@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 */ }
    }
}

Material3 TopAppBar için @OptIn(ExperimentalMaterial3Api::class) kullanılmalıdır — ek açıklama, API'nin gelecek sürümlerde değişebileceğini belirtir. 2025 itibarıyla M3'te TopAppBar deneysel olmaya devam etmektedir, ancak Google uygun testlerle üretimde kullanılmasını önermektedir.

ScrollBehavior: Kaydırma Sırasında Çubuğu Gizleme

ScrollBehavior, dikey içerik kaydırma sırasında TopAppBar'ın görünürlüğünü kontrol eden bir mekanizmadır. Jetpack Compose'da scrollBehavior, yer açmak için çubuğu gizlemeye veya daraltmaya olanak tanır; bu, özellikle büyük içerik listelerine sahip ekranlarda kullanışlıdır.

Material3 üç strateji sağlar: enterAlways (yukarı kaydırırken çubuk görünür, aşağı kaydırırken gizlenir), exitUntilCollapsed (çubuk yalnızca başlık tamamen daraldıktan sonra gizlenir) ve TopAppBarScrollBehavior arayüzü uygulanarak özel. İlk seçenek içerik akışları için uygundur, ikincisi MediumTopAppBar'lı ekranlar için uygundur.

ScrollBehavior, rememberLazyListState() aracılığıyla LazyColumn veya LazyRow ile koordinasyon gerektirir. Kaydırma durumu, scrollBehavior parametresi aracılığıyla TopAppBar'a iletilir. Bileşen otomatik olarak kaydırma olaylarına abone olur ve çubuğun görünürlüğünü canlandırır. Android Developers'a (2025) göre enterAlwaysScrollBehavior, kaydırılabilir TopAppBar'a sahip uygulamaların %75'inde kullanılan en popüler stratejidir.

Özel ScrollBehavior Yapılandırma

Özel davranış oluşturmak için TopAppBarScrollBehavior genişletin ve onScroll ile onDrag yöntemlerini geçersiz kılın. Özel davranış, standart senaryoların tasarım gereksinimlerini karşılamadığı durumlarda kullanışlıdır — örneğin, çubuğun yalnızca belirli bir kaydırma eşiği aşıldıktan sonra gizlenmesi gerektiğinde.

Varsayılan olarak scrollBehavior, içeriğe dolgu eklemez — paddingTop, Scaffold'da contentPadding aracılığıyla veya LazyColumn'da Modifier.padding aracılığıyla manuel olarak ayarlanmalıdır. MediumTopAppBar'da kenar boşlukları otomatik olarak TopAppBarState.collapsedFraction aracılığıyla hesaplanır.

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

ScrollBehavior yalnızca Material3'te kullanılabilir. Material2 TopAppBar'da kaydırma sırasında gizleme için yerleşik destek yoktur — benzer davranış için NestedScrollConnection aracılığıyla manuel uygulama gerekir.