TopAppBar: nədir, quraşdırma və Jetpack Compose-da istifadəsi

Jetpack Compose-da TopAppBar nədir?

TopAppBar — Jetpack Compose üçün Material Design kitabxanasından tətbiqin yuxarı panelini (App Bar) həyata keçirən composable funksiyadır. Komponent cari ekranın başlığını, sol tərəfdə naviqasiya düyməsini və sağ tərəfdə əlavə hərəkətləri göstərir.

Klassik View sistemindən fərqli olaraq, Compose versiyası TopAppBar tam deklarativdir: panel vəziyyət dəyişdikdə yenidən çəkilir, findViewById vasitəsilə idarə olunmur. TopAppBar slot API konsepsiyasından istifadə edir, burada title, navigationIcon və actions composable lambda kimi ötürülür. Bu, vərəsəlik olmadan panelin istənilən elementini fərdiləşdirməyə imkan verir.

Google Material Design (2025) məlumatına görə, Compose-da TopAppBar üç növdə olur: CenterAlignedTopAppBar (mərkəzləşdirilmiş başlıq), SmallTopAppBar (standart) və MediumTopAppBar (genişləndirilmiş). Hər növ panelin hündürlüyünü, başlıq şriftinin ölçüsünü və sürüşdürmə zamanı davranışı müəyyən edir. Mərkəzləşdirilmiş variant daha çox əsas ekranlarda, MediumTopAppBar isə başlığın sürüşdürmə zamanı tədricən kiçildiyi məzmun səhifələrində istifadə olunur.

TopAppBar-ın düzgün işləməsi üçün sistem boşluqlarını nəzərə almaq lazımdır: WindowInsetsCompat-dan Insets. Android Developers (2025) tövsiyələrinə əsasən, Modifier.statusBarsPadding() və ya windowInsetsPadding(WindowInsets.systemBars) çağırışı panelin status barının üzərinə düşməsinin qarşısını alır.

TopAppBar parametrləri: başlıq və modifierlərin konfiqurasiyası

TopAppBar komponenti bir sıra məcburi və isteğe bağlı parametrlər qəbul edir. Əsas parametr title-dir, ona başlıq mətni ilə composable bloku ötürülür. title @Composable lambda olduğundan, yalnız mətn deyil, həm də mətnlə ikona, axtarış sətri və ya gedişat paneli yerləşdirmək olar.

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

Modifier parametri bütün panel üçün boşluqlar, ölçü və düzləndirmə təyin etməyə imkan verir. Modifier.heightIn vasitəsilə minimum və maksimum hündürlüyü məhdudlaşdırmaq olar. colors parametri fon, başlıq və ikonların rənglərini dəyişdirmək üçün TopAppBarColors obyekti qəbul edir.

Susmaya görə TopAppBar cari MaterialTheme rəng sxemindən istifadə edir. Xüsusi palitra lazım olduqda TopAppBarDefaults.smallTopAppBarColors() istifadə edin. Material3-də fon rəngi avtomatik olaraq açıq və qaranlıq temalarda surfaceColor-a uyğunlaşır, bu da əl ilə konfiqurasiya ehtiyacını aradan qaldırır.

TopAppBar-da naviqasiya düyməsi

NavigationIcon — TopAppBar-ın sol hissəsində naviqasiyanı həyata keçirən composable blokdur. Tipik ssenarilər: Navigation Drawer-in açılması (Menu ikonu), əvvəlki ekrana qayıtma (ArrowBack ikonu) və ya cari ekranın bağlanması (Close ikonu).

İkonun seçimi ekranın naviqasiya yığınındakı mövqeyindən asılıdır. Ekran kökdədirsə — Drawer-i açmaq üçün Menu ikonu göstərilir. Ekran yerləşdirilmişdirsə — qayıtmaq üçün ArrowBack ikonu. Compose-da bu məntiq NavController vasitəsilə həyata keçirilir: cari back stack girişi hansı ikonun göstəriləcəyini müəyyən edir.

Material Design (2025) tövsiyələrinə görə, naviqasiya sahəsinin eni 48 dp — toxunma qarşılıqlı əlaqəsi üçün standart hədəfdir. İkon vizual əks əlaqə (ripple) ilə kliklənə bilən olmalıdır. Compose-da bu, naviqasiyanı işə salan onClick callback ilə IconButton-a bükülməklə təmin edilir.

Scaffold istifadə edərkən naviqasiya düyməsi birbaşa TopAppBar-a deyil, Scaffold-a ötürülən DrawerState-i təkrarlaya bilər. Bu halda navigationIcon rememberDrawerState vasitəsilə Drawer vəziyyətinə istinad edir.

Hərəkətlərin və açılan menyunun əlavə edilməsi

TopAppBar-da actions parametri RowScope konteksti ilə composable bloku qəbul edir, bu da başlığın sağ tərəfində çoxlu ikon və ya düymə yerləşdirməyə imkan verir. Hər bir hərəkət kliklənə bilən ikonoqrafik element olmalıdır: axtarış, bildirişlər, parametrlər, seçilmişlər.

Daşqın hərəkətlər üçün DropdownMenu vasitəsilə açılan menyu istifadə olunur. Hərəkətlərin sayı üçdən çox olarsa, əlavələr MoreVert ikonu ilə OverflowMenu-də yerləşdirilir. Tıklananda gizli hərəkətlərin siyahısı açılır. DropdownMenu avtomatik olaraq ikona nisbətən yerləşdirilir.

@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("Parametrlər") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("Haqqında") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Hər bir ikon üçün contentDescription təyin etmək vacibdir — bu əlçatanlıq tələbidir. Təsvir olmadan TalkBack düyməni səsləndirməyəcək. Sırf dekorativ elementlər üçün contentDescription = null istifadə edin.

Material3-də TopAppBar: Dynamic Color və adaptasiya

Material3 (M3) — Google tərəfindən yeni layihələr üçün tövsiyə olunan Material Design-ın cari versiyasıdır. M3-də TopAppBar TopAppBar, CenterAlignedTopAppBar və MediumTopAppBar vasitəsilə həyata keçirilir. Material2-dən əsas fərq — dynamic color, adaptiv hündürlük və scroll behavior üçün daxili dəstəkdir.

Dynamic Color avtomatik olaraq cihazın divar kağızı əsasında panel rənglərini seçir (Android 12+). M3-də TopAppBar fon üçün surfaceColor, başlıq üçün primary istifadə edir. Dynamic color mövcud deyilsə, MaterialTheme-dən fallback palitrası tətbiq olunur. Google Material Design (2025) məlumatına görə, Android 12+ istifadəçilərinin 63%-i tətbiqlərdə dynamic color-dan istifadə edir.

MediumTopAppBar — böyük başlıqlı (32 sp) genişləndirilmiş variantdır, sürüşdürmə zamanı hamar şəkildə 20 sp-ə qədər kiçilir və SmallTopAppBar-a çevrilir. Bu effekt TopAppBarDefaults.mediumTopAppBarColors() və scrollBehavior parametri vasitəsilə həyata keçirilir. Keçid animasiyası başlığın yığılmasını izləyən TopAppBarState tərəfindən idarə olunur.

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

Material3 TopAppBar üçün @OptIn(ExperimentalMaterial3Api::class) istifadə etmək lazımdır — annotasiya API-nin gələcək versiyalarda dəyişə biləcəyini göstərir. 2025-ci ilə qədər M3-də TopAppBar experimental olaraq qalır, lakin Google müvafiq yoxlama ilə istehsalda istifadəni tövsiyə edir.

ScrollBehavior: sürüşdürmə zamanı panelin gizlədilməsi

ScrollBehavior — məzmunun şaquli sürüşdürülməsi zamanı TopAppBar-ın görünməsini idarə edən mexanizmdir. Jetpack Compose-da scrollBehavior paneli gizlətməyə və ya kiçiltməyə imkan verir ki, bu da xüsusilə böyük məzmun siyahısı olan ekranlarda faydalıdır.

Material3 üç strategiya təqdim edir: enterAlways (panel yuxarı sürüşdürdükdə görünür, aşağı sürüşdürdükdə gizlənir), exitUntilCollapsed (panel yalnız başlıq tam yığıldıqdan sonra gizlənir) və TopAppBarScrollBehavior interfeysinin tətbiqi ilə fərdi. Birinci variant məzmun lentləri üçün, ikincisi — MediumTopAppBar olan ekranlar üçün uyğundur.

ScrollBehavior rememberLazyListState() vasitəsilə LazyColumn və ya LazyRow ilə koordinasiya tələb edir. Sürüşdürmə vəziyyəti scrollBehavior parametri vasitəsilə TopAppBar-a ötürülür. Komponent avtomatik olaraq sürüşdürmə hadisələrinə abunə olur və panelin görünməsini animasiya edir. Android Developers (2025) məlumatına görə, enterAlwaysScrollBehavior ən populyar strategiyadır, sürüşdürülə bilən TopAppBar olan tətbiqlərin 75%-də istifadə olunur.

Fərdi ScrollBehavior quraşdırması

Fərdi davranış yaratmaq üçün TopAppBarScrollBehavior-dan vərəsəlik götürün və onScroll və onDrag metodlarını dəyişdirin. Fərdi davranış standart ssenarilər dizayn tələblərini əhatə etmədikdə faydalıdır — məsələn, panel yalnız müəyyən sürüşdürmə həddi keçildikdən sonra gizlənməlidir.

Susmaya görə scrollBehavior məzmun üçün boşluq əlavə etmir — paddingTop əl ilə Scaffold-da contentPadding və ya LazyColumn-da Modifier.padding vasitəsilə təyin edilməlidir. MediumTopAppBar-da boşluqlar avtomatik olaraq TopAppBarState.collapsedFraction vasitəsilə hesablanır.

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

ScrollBehavior yalnız Material3-də mövcuddur. Material2-də TopAppBar-ın sürüşdürmə zamanı gizlənməsi üçün daxili dəstəyi yoxdur — oxşar davranış üçün NestedScrollConnection vasitəsilə əl ilə tətbiq tələb olunur.