StatusBar
앱의 상태 표시줄을 제어하는 컴포넌트. 상태 표시줄은 일반적으로 화면 상단에 위치하며 현재 시간, Wi-Fi 및 셀룰러 네트워크 정보, 배터리 수준 및 기타 상태 아이콘을 표시하는 영역이다.
Navigator와 함께 사용하기
여러 개의 StatusBar 컴포넌트를 동시에 마운트할 수 있다. 이때 StatusBar 컴포넌트가 마운트된 순서대로 props가 병합된다.
- TypeScript
- JavaScript
명령형 API
컴포넌트를 사용하기 어려운 경우를 대비해, 컴포넌트에 정적 함수 형태로 명령형 API를 제공한다. 하지만 동일한 프로퍼티에 대해 정적 API와 컴포넌트를 함께 사용하는 것은 권장하지 않는다. 정적 API로 설정한 값은 다음 리렌더링에서 컴포넌트가 설정한 값으로 덮어쓰이기 때문이다.
참조
상수
currentHeight Android
상태 표시줄의 높이로, 노치가 있는 경우 노치 높이도 포함된다.
Props
animated
상태 표시줄 속성 변경 시 트랜지션에 애니메이션을 적용할지 여부를 결정한다. backgroundColor, barStyle, hidden 속성에서 지원한다.
| 타입 | 필수 여부 | 기본값 |
|---|---|---|
| boolean | 아니오 | false |
backgroundColor Android
상태 바의 배경색을 설정한다.
Android 15에서 도입된 edge-to-edge 강제 적용으로 인해, API 레벨 35부터 상태 바의 배경색 설정은 더 이상 사용되지 않는다.
| 타입 | 필수 여부 | 기본값 |
|---|---|---|
| color | 아니오 | 시스템 기본 상태 바 배경색. 정의되지 않은 경우 'black'으로 설정된다. |
barStyle
상태 바 텍스트의 색상을 설정한다.
Android에서는 API 버전 23 이상에서만 적용된다.
| 타입 | 필수 여부 | 기본값 |
|---|---|---|
| StatusBarStyle | 아니오 | 'default' |
hidden
상태 바가 숨겨져 있는지 여부를 나타낸다.
| 타입 | 필수 여부 | 기본값 |
|---|---|---|
| boolean | 아니오 | false |
networkActivityIndicatorVisible iOS
네트워크 활동 표시기가 보여야 하는지 여부를 설정한다.
| 타입 | 기본값 |
|---|---|
| boolean | false |
showHideTransition iOS
hidden 속성을 사용해 상태 바를 보이거나 숨길 때 적용되는 트랜지션 효과.
| 타입 | 기본값 |
|---|---|
| StatusBarAnimation | 'fade' |
translucent Android
상태 바가 반투명인지 여부를 나타낸다. translucent를 true로 설정하면 앱이 상태 바 아래에 그려진다. 이 설정은 반투명 상태 바 색상을 사용할 때 유용하다.
| 타입 | 기본값 |
|---|---|
| boolean | false |
메서드
popStackEntry()
static popStackEntry(entry: StatusBarProps);
스택에서 마지막 StatusBar 엔트리를 가져와 제거한다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| entry 필수 | any | pushStackEntry에서 반환된 엔트리. |
pushStackEntry()
static pushStackEntry(props: StatusBarProps): StatusBarProps;
스택에 StatusBar 항목을 추가한다. 반환된 값은 작업이 완료된 후 popStackEntry로 전달해야 한다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| props 필수 | any | 스택 항목에 사용할 StatusBar 속성을 포함한 객체. |
replaceStackEntry()
static replaceStackEntry(
entry: StatusBarProps,
props: StatusBarProps
): StatusBarProps;
기존 StatusBar 스택 엔트리를 새로운 props로 교체한다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| entry 필수 | any | 교체할 엔트리. pushStackEntry에서 반환된 값을 사용한다. |
| props 필수 | any | 교체할 스택 엔트리에 사용할 StatusBar props를 포함한 객체. |
setBackgroundColor() Android
static setBackgroundColor(color: ColorValue, animated?: boolean);
상태 바의 배경색을 설정한다.
Android 15에서 도입된 edge-to-edge 강제 적용으로 인해, API 레벨 35부터 상태 바 배경색 설정은 더 이상 사용되지 않는다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| color 필수 | string | 배경색. |
| animated | boolean | 스타일 변경 시 애니메이션 적용 여부. |
setBarStyle()
static setBarStyle(style: StatusBarStyle, animated?: boolean);
상태 바 스타일을 설정한다.
인자:
| 이름 | 타입 | 설명 |
|---|---|---|
| style 필수 | StatusBarStyle | 설정할 상태 바 스타일. |
| animated | boolean | 스타일 변경 시 애니메이션 적용 여부. |
setHidden()
static setHidden(hidden: boolean, animation?: StatusBarAnimation);
상태 바를 보이거나 숨긴다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| hidden 필수 | boolean | 상태 바를 숨길지 여부를 결정한다. |
| animation iOS | StatusBarAnimation | 상태 바의 숨김 속성을 변경할 때 사용할 애니메이션을 지정한다. |
setNetworkActivityIndicatorVisible() iOS
static setNetworkActivityIndicatorVisible(visible: boolean);
네트워크 활동 표시기의 가시성을 제어한다.
매개변수:
| 이름 | 타입 | 설명 |
|---|---|---|
| visible 필수 | boolean | 표시기를 보여줄지 여부. |
setTranslucent() Android
static setTranslucent(translucent: boolean);
상태 바의 반투명 효과를 제어한다.
인자:
| 이름 | 타입 | 설명 |
|---|---|---|
| translucent 필수 | boolean | 반투명으로 설정한다. |
타입 정의
StatusBarAnimation
iOS에서 상태 바 전환 시 사용하는 애니메이션 타입.
| 타입 |
|---|
| enum |
상수:
| 값 | 타입 | 설명 |
|---|---|---|
'fade' | string | 페이드 애니메이션 |
'slide' | string | 슬라이드 애니메이션 |
'none' | string | 애니메이션 없음 |
StatusBarStyle
상태 바 스타일 타입을 정의한다.
| 타입 |
|---|
| enum |
상수 값:
| 값 | 타입 | 설명 |
|---|---|---|
'default' | string | 기본 상태 바 스타일 (iOS는 어두운 스타일, 안드로이드는 밝은 스타일) |
'light-content' | string | 흰색 텍스트와 아이콘 |
'dark-content' | string | 어두운 텍스트와 아이콘 (안드로이드 API 23 이상 필요) |