TopAppBar: Jetpack Compose에서의 개념, 설정 및 사용법

Jetpack Compose에서 TopAppBar란?

TopAppBar는 Jetpack Compose용 Material Design 라이브러리의 컴포저블 함수로, 상단 앱 바를 구현합니다. 이 구성 요소는 현재 화면의 제목, 왼쪽의 탐색 버튼 및 오른쪽의 추가 작업을 표시합니다.

기존 View 시스템과 달리 Compose 버전의 TopAppBar는 완전히 선언적입니다. findViewById를 통해 관리되는 대신 상태가 변경될 때 바가 다시 그려집니다. TopAppBar는 슬롯 API 개념을 사용하며, title, navigationIcon 및 actions가 컴포저블 람다로 전달됩니다. 이를 통해 상속 없이 바의 모든 요소를 사용자 지정할 수 있습니다.

Google Material Design(2025)에 따르면 Compose의 TopAppBar는 세 가지 유형으로 제공됩니다: CenterAlignedTopAppBar(중앙 정렬 제목), SmallTopAppBar(표준), MediumTopAppBar(확장). 각 유형은 바 높이, 제목 글꼴 크기 및 스크롤 동작을 정의합니다. 중앙 정렬 변형은 주 화면에서 더 자주 사용되며, MediumTopAppBar는 스크롤 시 제목이 부드럽게 축소되는 콘텐츠 페이지에 사용됩니다.

TopAppBar의 올바른 작동을 위해 시스템 여백(WindowInsetsCompat의 Insets)을 고려해야 합니다. Android Developers(2025)의 권장 사항에 따르면 Modifier.statusBarsPadding() 또는 windowInsetsPadding(WindowInsets.systemBars)을 호출하면 바가 상태 표시줄과 겹치는 것을 방지할 수 있습니다.

TopAppBar 매개변수: 제목 및 수정자 구성

TopAppBar 구성 요소는 여러 필수 및 선택적 매개변수를 허용합니다. 주요 매개변수는 title로, 제목 텍스트가 포함된 컴포저블 블록이 전달됩니다. title은 @Composable 람다이므로 텍스트뿐만 아니라 아이콘과 텍스트, 검색 필드 생성 또는 진행률 표시도 가능합니다.

@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 매개변수를 사용하면 전체 바의 패딩, 크기 및 정렬을 설정할 수 있습니다. Modifier.heightIn을 통해 최소 및 최대 높이를 제한할 수 있습니다. colors 매개변수는 배경, 제목 및 아이콘 색상을 재정의하는 TopAppBarColors 개체를 허용합니다.

기본적으로 TopAppBar는 현재 MaterialTheme의 색 구성표를 사용합니다. 사용자 지정 팔레트가 필요한 경우 TopAppBarDefaults.smallTopAppBarColors()를 사용합니다. Material3에서는 밝은 테마와 어두운 테마에서 배경색이 자동으로 surfaceColor에 적응하므로 수동 구성이 필요하지 않습니다.

TopAppBar의 탐색 버튼

NavigationIcon은 TopAppBar의 왼쪽 부분에 있는 컴포저블 블록으로, 이를 통해 탐색이 구현됩니다. 일반적인 시나리오: Navigation Drawer 열기(메뉴 아이콘), 이전 화면으로 돌아가기(ArrowBack 아이콘), 현재 화면 닫기(닫기 아이콘).

아이콘 선택은 탐색 스택에서 화면의 위치에 따라 달라집니다. 화면이 루트인 경우 Drawer를 열기 위해 메뉴 아이콘이 표시됩니다. 화면이 중첩된 경우 돌아가기 위해 ArrowBack 아이콘이 표시됩니다. Compose에서 이 로직은 NavController를 통해 구현됩니다. 현재 백 스택 항목이 표시할 아이콘을 결정합니다.

Material Design(2025) 권장 사항에 따르면 탐색 영역의 너비는 48 dp로, 터치 상호 작용의 표준 대상입니다. 아이콘은 시각적 피드백(ripple)과 함께 클릭 가능해야 합니다. Compose에서는 탐색을 트리거하는 onClick 콜백이 있는 IconButton으로 래핑하여 보장합니다.

Scaffold를 사용할 때 탐색 버튼은 TopAppBar에 직접 전달되지 않고 Scaffold에 전달되는 DrawerState를 복제할 수 있습니다. 이 경우 navigationIcon은 rememberDrawerState를 통해 Drawer 상태를 참조합니다.

액션 및 드롭다운 메뉴 추가

TopAppBar의 actions 매개변수는 RowScope 컨텍스트가 있는 컴포저블 블록을 허용하여 제목 오른쪽에 여러 아이콘이나 버튼을 배치할 수 있습니다. 각 액션은 클릭 가능한 아이콘 요소(검색, 알림, 설정, 즐겨찾기)여야 합니다.

오버플로 액션의 경우 DropdownMenu를 통해 드롭다운 메뉴가 사용됩니다. 액션 수가 3개를 초과하면 추가 액션이 MoreVert 아이콘과 함께 OverflowMenu에 배치됩니다. 클릭하면 숨겨진 액션 목록이 열립니다. DropdownMenu는 아이콘을 기준으로 자동으로 배치됩니다.

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

각 아이콘에 contentDescription을 설정하는 것이 중요합니다. 이는 접근성 요구 사항입니다. 설명이 없으면 TalkBack이 버튼을 읽어주지 않습니다. 순전히 장식용 요소의 경우 contentDescription = null을 사용합니다.

Material3의 TopAppBar: 다이나믹 컬러 및 적응

Material3(M3)는 Material Design의 현재 버전으로, Google이 새 프로젝트에 권장합니다. M3의 TopAppBar는 TopAppBar, CenterAlignedTopAppBar 및 MediumTopAppBar를 통해 구현됩니다. Material2와의 주요 차이점은 다이나믹 컬러, 적응형 높이 및 스크롤 동작에 대한 기본 제공 지원입니다.

다이나믹 컬러는 기기 배경화면(Android 12+)을 기반으로 바 색상을 자동으로 선택합니다. M3의 TopAppBar는 배경에 surfaceColor를, 제목에 primary를 사용합니다. 다이나믹 컬러를 사용할 수 없는 경우 MaterialTheme의 폴백 팔레트가 적용됩니다. Google Material Design(2025)에 따르면 Android 12+ 사용자의 63%가 애플리케이션에서 다이나믹 컬러를 사용합니다.

MediumTopAppBar는 큰 제목(32 sp)이 있는 확장 변형으로, 스크롤 시 20 sp로 부드럽게 축소되어 SmallTopAppBar로 전환됩니다. 이 효과는 TopAppBarDefaults.mediumTopAppBarColors()와 scrollBehavior 매개변수를 통해 구현됩니다. 전환 애니메이션은 제목 축소를 추적하는 TopAppBarState를 통해 제어됩니다.

@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를 사용하려면 @OptIn(ExperimentalMaterial3Api::class)를 사용해야 합니다. 이 어노테이션은 API가 향후 버전에서 변경될 수 있음을 나타냅니다. 2025년 현재 M3의 TopAppBar는 실험적이지만 Google은 적절한 테스트와 함께 프로덕션에서 사용할 것을 권장합니다.

ScrollBehavior: 스크롤 시 바 숨기기

ScrollBehavior는 콘텐츠를 세로로 스크롤하는 동안 TopAppBar의 가시성을 제어하는 메커니즘입니다. Jetpack Compose에서 scrollBehavior를 사용하면 공간을 확보하기 위해 바를 숨기거나 축소할 수 있으며, 이는 큰 콘텐츠 목록이 있는 화면에서 특히 유용합니다.

Material3는 세 가지 전략을 제공합니다: enterAlways(위로 스크롤하면 바가 나타나고 아래로 스크롤하면 숨겨짐), exitUntilCollapsed(제목이 완전히 축소된 후에만 바가 숨겨짐), TopAppBarScrollBehavior 인터페이스를 구현한 사용자 지정. 첫 번째 옵션은 콘텐츠 피드에 적합하고, 두 번째는 MediumTopAppBar가 있는 화면에 적합합니다.

ScrollBehavior는 rememberLazyListState()를 통해 LazyColumn 또는 LazyRow와의 조정이 필요합니다. 스크롤 상태는 scrollBehavior 매개변수를 통해 TopAppBar에 전달됩니다. 구성 요소는 스크롤 이벤트를 자동으로 구독하고 바 가시성을 애니메이션화합니다. Android Developers(2025)에 따르면 enterAlwaysScrollBehavior는 가장 인기 있는 전략으로, 스크롤 가능한 TopAppBar가 있는 애플리케이션의 75%에서 사용됩니다.

사용자 지정 ScrollBehavior 구성

사용자 지정 동작을 만들려면 TopAppBarScrollBehavior를 확장하고 onScroll 및 onDrag 메서드를 재정의합니다. 사용자 지정 동작은 표준 시나리오가 디자인 요구 사항을 충족하지 못할 때 유용합니다. 예를 들어, 특정 스크롤 임계값을 초과한 후에만 바를 숨겨야 하는 경우입니다.

기본적으로 scrollBehavior는 콘텐츠에 패딩을 추가하지 않습니다. paddingTop은 Scaffold의 contentPadding을 통해 또는 LazyColumn의 Modifier.padding을 통해 수동으로 설정해야 합니다. MediumTopAppBar에서는 여백이 TopAppBarState.collapsedFraction을 통해 자동으로 계산됩니다.

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

ScrollBehavior는 Material3에서만 사용할 수 있습니다. Material2 TopAppBar에는 스크롤 시 숨기기에 대한 기본 제공 지원이 없으며, 유사한 동작을 위해서는 NestedScrollConnection을 통한 수동 구현이 필요합니다.