Android 플랫폼은 상태 표시줄 및 탐색 메뉴와 같은 시스템 UI를 그려야 합니다. 이 시스템 UI는 사용자가 사용 중인 앱과 관계없이 표시됩니다. WindowInsets는 앱이 올바른 영역에 그리고 UI가 시스템 UI에 의해 가려지지 않도록 시스템 UI에 관한 정보를 제공합니다.
기본적으로 앱의 UI는 상태 표시줄 및 탐색 메뉴와 같은 시스템 UI 내에 배치되도록 제한됩니다. 이렇게 하면 앱의 콘텐츠가 시스템 UI 요소로 가리지 않습니다.
그러나 시스템 UI도 표시되는 이러한 영역에는 앱이 표시되도록 선택하는 것이 좋습니다. 이렇게 하면 더 원활한 사용자 환경이 제공되며 앱에서 사용 가능한 창 공간을 최대한 활용할 수 있습니다. 이렇게 하면 특히 소프트웨어 키보드를 표시하거나 숨길 때 앱이 시스템 UI와 함께 애니메이션을 적용할 수 있습니다.
이러한 영역에 표시하도록 선택하고 시스템 UI 뒤에 콘텐츠를 표시하는 것을 더 넓은 화면이라고 합니다. 이 페이지에서는 다양한 유형의 인셋, 더 넓은 화면 전환을 선택하는 방법, 인셋 API를 사용하여 UI에 애니메이션을 적용하고 앱의 일부를 가리지 않는 방법을 알아봅니다.
인셋 기초
앱을 더 넓은 화면으로 이동할 때는 시스템 UI가 중요한 콘텐츠와 상호작용을 가리지 않도록 해야 합니다. 예를 들어 버튼이 탐색 메뉴 뒤에 있으면 사용자가 클릭하지 못할 수 있습니다.
시스템 UI의 크기와 배치에 관한 정보는 인셋을 통해 지정됩니다.
시스템 UI의 각 부분에는 크기와 배치 위치를 설명하는 상응하는 유형의 인셋이 있습니다. 예를 들어 상태 표시줄 인셋은 상태 표시줄의 크기와 위치를 제공하고 탐색 메뉴 인셋은 탐색 메뉴의 크기와 위치를 제공합니다. 각 인셋 유형은 상단, 왼쪽, 오른쪽, 하단의 4개 픽셀 크기로 구성됩니다. 이러한 크기는 시스템 UI가 앱 창의 상응하는 측면에서 확장되는 정도를 지정합니다. 따라서 이러한 유형의 시스템 UI와 겹치지 않도록 하려면 앱 UI를 그만큼 인셋해야 합니다.
다음과 같은 내장 Android 인셋 유형은 WindowInsets를 통해 사용할 수 있습니다.
상태 표시줄을 설명하는 인셋입니다. 이는 알림 아이콘과 기타 표시기가 포함된 상단 시스템 UI 바입니다. |
|
상태 표시줄이 표시되는 경우를 위한 인셋입니다. 몰입형 전체 화면 모드로 전환되어 상태 표시줄이 현재 숨겨져 있는 경우 기본 상태 표시줄 인셋은 비어 있지만 이러한 인셋은 비어 있지 않습니다. |
|
탐색 메뉴를 설명하는 인셋입니다. 기기 왼쪽, 오른쪽, 하단에 있는 시스템 UI 표시줄로, 작업 표시줄이나 탐색 아이콘을 설명합니다. 사용자가 선호하는 탐색 방법 및 작업 표시줄과의 상호작용에 따라 런타임 시 변경될 수 있습니다. |
|
표시되는 경우를 위한 탐색 메뉴 인셋 (몰입형 전체 화면 모드로 인해) 탐색 메뉴가 현재 숨겨져 있는 경우 기본 탐색 메뉴 인셋은 비어 있지만 이러한 인셋은 비어 있지 않습니다. |
|
상단 제목 표시줄과 같은 자유 형식 창에 있는 경우의 시스템 UI 창 장식을 설명하는 인셋입니다. |
|
자막 막대가 표시되는 시점을 위한 인셋입니다. 자막 막대가 현재 숨겨져 있으면 기본 자막 표시줄 인셋은 비어 있지만 이 인셋은 비어 있지 않습니다. |
|
상태 표시줄, 탐색 메뉴 및 자막 표시줄을 포함한 시스템 표시줄 인셋의 합집합입니다. |
|
시스템 표시줄이 표시되는 경우를 위한 시스템 표시줄 인셋입니다. 몰입형 전체 화면 모드로 전환되어 시스템 표시줄이 현재 숨겨져 있는 경우 기본 시스템 표시줄 인셋은 비어 있지만 이러한 인셋은 비어 있지 않습니다. |
|
소프트웨어 키보드가 차지하는 하단의 공간 크기를 설명하는 인셋. |
|
현재 키보드 애니메이션 전에 소프트웨어 키보드가 차지한 공간의 양을 설명하는 인셋입니다. |
|
현재 키보드 애니메이션 뒤에 소프트웨어 키보드가 차지하게 될 공간의 양을 설명하는 인셋입니다. |
|
탐색 UI에 관한 자세한 정보를 설명하는 인셋의 한 유형으로, 앱이 아닌 시스템에서 '탭'을 처리하는 공간을 제공합니다. 동작 탐색이 있는 투명한 탐색 메뉴의 경우 일부 앱 요소는 시스템 탐색 UI를 통해 탭할 수 있습니다. |
|
탭 가능한 요소 삽입은 요소가 표시되는 경우를 위한 삽입입니다. 탭 가능 요소가 몰입형 전체 화면 모드로 전환되어 현재 숨겨져 있는 경우 기본 탭 가능 요소 인셋은 비어 있지만 이러한 인셋은 비어 있지 않습니다. |
|
시스템이 탐색을 위해 동작을 가로채는 인셋의 양을 나타내는 인셋입니다. 앱에서는 |
|
시스템에서 항상 처리하고 |
|
인셋은 디스플레이 컷아웃 (노치 또는 핀홀)과 겹치지 않도록 하는 데 필요한 간격의 양을 나타냅니다. |
|
워터폴 디스플레이의 곡선 영역을 나타내는 인셋입니다. 워터폴 디스플레이에는 화면 가장자리를 따라 화면이 기기 양측에 래핑되기 시작하는 곡선 영역이 있습니다. |
이러한 유형은 콘텐츠가 가려지지 않도록 하는 3가지 '안전한' 인셋 유형으로 요약됩니다.
이러한 '안전한' 인셋 유형은 기본 플랫폼 인셋에 따라 다양한 방식으로 콘텐츠를 보호합니다.
WindowInsets.safeDrawing를 사용하여 시스템 UI 아래에 그려서는 안 되는 콘텐츠를 보호합니다. 이는 인셋의 가장 일반적인 용도입니다. 시스템 UI가 (부분적으로 또는 전체적으로) 가려진 콘텐츠를 그리지 못하게 하기 위함입니다.WindowInsets.safeGestures을 사용하여 동작으로 콘텐츠를 보호합니다. 이렇게 하면 시스템 동작이 하단 시트, 캐러셀, 게임 내 동작과 같은 앱 동작과 충돌하는 것을 피할 수 있습니다.WindowInsets.safeDrawing및WindowInsets.safeGestures의 조합으로WindowInsets.safeContent를 사용하여 콘텐츠의 시각적 겹침과 동작이 겹치지 않도록 하세요.
인셋 설정
앱에서 콘텐츠를 그리는 위치를 완전히 제어할 수 있도록 하려면 다음 설정 단계를 따르세요. 이 단계가 없으면 앱이 시스템 UI 뒤에 검은색 또는 단색을 그리거나 소프트웨어 키보드와 동기식으로 애니메이션을 적용하지 않을 수 있습니다.
Activity.onCreate에서enableEdgeToEdge()를 호출합니다. 이 호출은 앱이 시스템 UI 뒤에 표시되도록 요청합니다. 그러면 앱에서 이러한 인셋을 사용하여 UI를 조정하는 방식을 제어합니다.활동의
AndroidManifest.xml항목에서android:windowSoftInputMode="adjustResize"를 설정하세요. 이 설정을 사용하면 앱에서 소프트웨어 IME의 크기를 인셋으로 수신할 수 있으며, 이 크기를 사용하여 IME가 앱에 나타났다가 사라질 때 콘텐츠를 적절하게 패딩하고 배치할 수 있습니다.<!-- in your AndroidManifest.xml file: --> <activity android:name=".ui.MainActivity" android:label="@string/app_name" android:windowSoftInputMode="adjustResize" android:theme="@style/Theme.MyApplication" android:exported="true">
Compose API
Activity에서 모든 인셋 처리를 제어하고 나면 Compose API를 사용하여 콘텐츠가 가려지지 않고 상호작용 가능한 요소가 시스템 UI와 겹치지 않도록 할 수 있습니다. 또한 이러한 API는 앱의 레이아웃을 인셋 변경사항과 동기화합니다.
예를 들어 다음은 인셋을 전체 앱의 콘텐츠에 적용하는 가장 기본적인 방법입니다.
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
enableEdgeToEdge()
setContent {
Box(Modifier.safeDrawingPadding()) {
// the rest of the app
}
}
}
이 스니펫은 safeDrawing 창 인셋을 앱의 전체 콘텐츠 주위에 패딩으로 적용합니다. 이렇게 하면 상호작용 가능한 요소가 시스템 UI와 겹치지 않습니다. 하지만 이렇게 하면 어떤 앱도 시스템 UI 뒤에 그려지지 않아 더 넓은 화면 효과를 달성할 수 없습니다. 전체 창을 최대한 활용하려면 화면 단위 또는 구성요소별로 인셋이 적용되는 위치를 세밀하게 조정해야 합니다.
이러한 모든 인셋 유형은 API 21로 백포팅된 IME 애니메이션으로 자동으로 애니메이션 처리됩니다. 또한 이러한 인셋을 사용하는 모든 레이아웃은 인셋 값이 변경될 때 자동으로 애니메이션 처리됩니다.
이러한 인셋 유형을 사용하여 컴포저블 레이아웃을 조정하는 두 가지 기본 방법은 패딩 수정자와 인셋 크기 수정자입니다.
패딩 수정자
Modifier.windowInsetsPadding(windowInsets: WindowInsets)는 Modifier.padding와 마찬가지로 지정된 창 인셋을 패딩으로 적용합니다.
예를 들어 Modifier.windowInsetsPadding(WindowInsets.safeDrawing)는 안전 그리기 인셋을 4개의 면 모두에 패딩으로 적용합니다.
가장 일반적인 인셋 유형을 위한 여러 내장 유틸리티 메서드도 있습니다.
Modifier.safeDrawingPadding()는 Modifier.windowInsetsPadding(WindowInsets.safeDrawing)와 동일한 메서드 중 하나입니다. 다른 인셋 유형에도 유사한 수정자가 있습니다.
인셋 크기 수정자
다음 수정자는 구성요소의 크기를 인셋의 크기로 설정하여 일정량의 창 인셋을 적용합니다.
windowInsets의 시작 측면을 너비로 적용합니다 (예: |
|
windowInsets의 끝을 너비로 적용합니다 (예: |
|
windowInsets의 상단을 높이로 적용합니다 (예: |
|
|
windowInsets의 하단을 높이로 적용합니다 (예: |
이러한 수정자는 인셋 공간을 차지하는 Spacer의 크기를 조정하는 데 특히 유용합니다.
LazyColumn(
Modifier.imePadding()
) {
// Other content
item {
Spacer(
Modifier.windowInsetsBottomHeight(
WindowInsets.systemBars
)
)
}
}
인셋 소비
인셋 패딩 수정자 (windowInsetsPadding 및 safeDrawingPadding과 같은 도우미)는 패딩으로 적용된 인셋 부분을 자동으로 사용합니다. 컴포지션 트리로 더 깊이 들어가면서 중첩된 인셋 패딩 수정자와 인셋 크기 수정자는 인셋의 일부가 이미 외부 인셋 패딩 수정자에 의해 사용되었다는 것을 알고 있으며 인셋의 동일한 부분을 두 번 이상 사용하지 않으므로 너무 많은 공간이 생길 수 있습니다.
또한 인셋 크기 수정자는 인셋이 이미 사용된 경우 인셋의 동일한 부분을 두 번 이상 사용하지 않습니다. 그러나 크기를 직접 변경하므로 인셋 자체를 사용하지 않습니다.
따라서 패딩 수정자를 중첩하면 각 컴포저블에 적용되는 패딩의 양이 자동으로 변경됩니다.
이전과 동일한 LazyColumn 예를 보면 LazyColumn는 imePadding 수정자에 의해 크기가 조절됩니다. LazyColumn 내에서 마지막 항목은 시스템 표시줄 하단의 높이와 동일하게 조정됩니다.
LazyColumn(
Modifier.imePadding()
) {
// Other content
item {
Spacer(
Modifier.windowInsetsBottomHeight(
WindowInsets.systemBars
)
)
}
}
IME가 닫히면 imePadding() 수정자는 패딩을 적용하지 않습니다. IME에 높이가 없기 때문입니다. imePadding() 수정자가 패딩을 적용하지 않으므로 인셋이 사용되지 않으며 Spacer의 높이는 시스템 표시줄의 하단 크기가 됩니다.
IME가 열리면 IME 인셋은 IME 크기에 맞게 애니메이션화되고 IME가 열릴 때 imePadding() 수정자는 하단 패딩을 적용하여 LazyColumn의 크기를 조절하기 시작합니다. imePadding() 수정자가 하단 패딩을 적용하기 시작하면 그만큼의 인셋도 사용하기 시작합니다. 따라서 Spacer의 높이가 감소하기 시작합니다. 시스템 표시줄 간격의 일부로 imePadding() 수정자가 이미 적용했기 때문입니다. imePadding() 수정자가 시스템 표시줄보다 큰 하단 패딩을 적용하면 Spacer의 높이는 0이 됩니다.
IME가 닫히면 변경사항은 반대로 발생합니다. imePadding()가 시스템 표시줄의 하단보다 적게 적용되면 Spacer의 높이가 0에서 확장되기 시작하여 IME가 완전히 애니메이션화되면 Spacer가 시스템 표시줄의 하단 높이와 일치하게 됩니다.
TextField를 사용한 더 넓은 지연 열이 동작은 모든 windowInsetsPadding 수정자 간의 통신을 통해 실행되며 다른 몇 가지 방법으로 영향을 받을 수 있습니다.
Modifier.consumeWindowInsets(insets: WindowInsets)도 Modifier.windowInsetsPadding와 같은 방식으로 인셋을 사용하지만 소비된 인셋을 패딩으로 적용하지는 않습니다. 이는 인셋 크기 수정자와 함께 사용하여 특정 양의 인셋이 이미 사용되었음을 형제에게 나타낼 때 유용합니다.
Column(Modifier.verticalScroll(rememberScrollState())) {
Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))
Column(
Modifier.consumeWindowInsets(
WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
)
) {
// content
Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
Modifier.consumeWindowInsets(paddingValues: PaddingValues)는 WindowInsets 인수가 있는 버전과 매우 유사하게 동작하지만 임의의 PaddingValues를 사용하여 사용합니다. 이는 일반적인 Modifier.padding 또는 고정 높이 스페이서와 같이 인셋 수정자가 아닌 다른 메커니즘에서 패딩 또는 간격을 제공하는 경우 하위 요소에 알리는 데 유용합니다.
@OptIn(ExperimentalLayoutApi::class)
Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
// content
Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
소비 없이 원시 창 인셋이 필요한 경우 WindowInsets 값을 직접 사용하거나 WindowInsets.asPaddingValues()를 사용하여 소비의 영향을 받지 않는 인셋의 PaddingValues를 반환합니다.
그러나 아래의 주의사항으로 인해 가능하면 창 인셋 패딩 수정자와 창 인셋 크기 수정자를 사용하는 것이 좋습니다.
인셋 및 Jetpack Compose 단계
Compose는 기본 AndroidX 핵심 API를 사용하여 인셋을 업데이트하고 애니메이션 처리합니다. 인셋은 인셋을 관리하는 기본 플랫폼 API를 사용합니다. 이러한 플랫폼 동작으로 인해 인셋은 Jetpack Compose 단계와 특별한 관계가 있습니다.
인셋의 값은 컴포지션 단계 이후, 레이아웃 단계 전에 업데이트됩니다. 즉, 컴포지션에서 인셋 값을 읽을 때는 일반적으로 한 프레임 늦게 인셋 값을 사용합니다. 이 페이지에서 설명하는 내장 수정자는 레이아웃 단계까지 인셋 값을 사용하여 지연하도록 빌드되어 인셋 값이 업데이트되는 것과 동일한 프레임에서 사용됩니다.
WindowInsets를 사용한 키보드 IME 애니메이션
스크롤 컨테이너에 Modifier.imeNestedScroll()를 적용하여 컨테이너 하단으로 스크롤할 때 IME를 자동으로 열고 닫을 수 있습니다.
class WindowInsetsExampleActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
WindowCompat.setDecorFitsSystemWindows(window, false)
setContent {
MaterialTheme {
MyScreen()
}
}
}
}
@OptIn(ExperimentalLayoutApi::class)
@Composable
fun MyScreen() {
Box {
LazyColumn(
modifier = Modifier
.fillMaxSize() // fill the entire window
.imePadding() // padding for the bottom for the IME
.imeNestedScroll(), // scroll IME at the bottom
content = { }
)
FloatingActionButton(
modifier = Modifier
.align(Alignment.BottomEnd)
.padding(16.dp) // normal 16dp of padding for FABs
.navigationBarsPadding() // padding for navigation bar
.imePadding(), // padding for when IME appears
onClick = { }
) {
Icon(imageVector = Icons.Filled.Add, contentDescription = "Add")
}
}
}
그림 1. IME 애니메이션
Material 3 구성요소의 인셋 지원
사용 편의성을 위해 많은 내장 Material 3 컴포저블(androidx.compose.material3)은 컴포저블이 Material 사양에 따라 앱에 배치되는 방식에 따라 인셋을 직접 처리합니다.
인셋 처리 컴포저블
다음은 인셋을 자동으로 처리하는 머티리얼 구성요소 목록입니다.
앱 바
TopAppBar/SmallTopAppBar/CenterAlignedTopAppBar/MediumTopAppBar/LargeTopAppBar: 창 상단에 사용되므로 시스템 표시줄의 상단 및 가로 측면을 패딩으로 적용합니다.BottomAppBar: 시스템 표시줄의 하단과 가로를 패딩으로 적용합니다.
콘텐츠 컨테이너
ModalDrawerSheet/DismissibleDrawerSheet/PermanentDrawerSheet(모달 탐색 창 내부의 콘텐츠): 콘텐츠에 세로 및 시작 인셋을 적용합니다.ModalBottomSheet: 하단 인셋을 적용합니다.NavigationBar: 하단 및 가로 인셋을 적용합니다.NavigationRail: 세로 및 시작 인셋을 적용합니다.
Scaffold
기본적으로 Scaffold는 개발자가 사용하고 사용할 수 있도록 인셋을 매개변수 paddingValues로 제공합니다.
Scaffold는 콘텐츠에 인셋을 적용하지 않습니다. 이 책임은 개발자에게 있습니다.
예를 들어 Scaffold 내에서 LazyColumn와 함께 이러한 인셋을 사용하려면 다음과 같이 합니다.
Scaffold { innerPadding ->
// innerPadding contains inset information for you to use and apply
LazyColumn(
// consume insets as scaffold doesn't do it by default
modifier = Modifier.consumeWindowInsets(innerPadding),
contentPadding = innerPadding
) {
items(count = 100) {
Box(
Modifier
.fillMaxWidth()
.height(50.dp)
.background(colors[it % colors.size])
)
}
}
}
기본 인셋 재정의
컴포저블에 전달된 windowInsets 매개변수를 변경하여 컴포저블의 동작을 구성할 수 있습니다. 이 매개변수는 대신 적용할 다른 유형의 창 인셋이거나 빈 인스턴스(WindowInsets(0, 0, 0, 0))를 전달하여 사용 중지할 수 있습니다.
예를 들어 LargeTopAppBar에서 인셋 처리를 사용 중지하려면 windowInsets 매개변수를 빈 인스턴스로 설정합니다.
LargeTopAppBar(
windowInsets = WindowInsets(0, 0, 0, 0),
title = {
Text("Hi")
}
)
뷰 시스템 인셋과의 상호 운용성
화면에 동일한 계층 구조에 뷰와 Compose 코드가 모두 있으면 기본 인셋을 재정의해야 할 수 있습니다. 이 경우 어느 것이 인셋을 사용해야 하고 어느 것이 인셋을 무시해야 하는지 명시해야 합니다.
예를 들어 가장 바깥쪽 레이아웃이 Android 뷰 레이아웃인 경우 뷰 시스템에서 인셋을 사용하고 Compose에서 이를 무시해야 합니다.
또는 가장 바깥쪽 레이아웃이 컴포저블인 경우 Compose에서 인셋을 사용하고 그에 따라 AndroidView 컴포저블을 패딩해야 합니다.
기본적으로 각 ComposeView는 WindowInsetsCompat 사용 수준에서 모든 인셋을 사용합니다. 이 기본 동작을 변경하려면 ComposeView.consumeWindowInsets를 false로 설정하세요.
리소스
- Now in Android - Kotlin과 Jetpack Compose로 완전히 빌드된 모든 기능을 갖춘 Android 앱입니다.
추천 서비스
- 참고: JavaScript가 사용 중지되어 있으면 링크 텍스트가 표시됩니다.
- Material 구성요소 및 레이아웃
CoordinatorLayout를 Compose로 이전- 기타 고려사항