Skip to main content
Version: Next

StatusBar

앱의 상태 표시줄을 제어하는 컴포넌트. 상태 표시줄은 일반적으로 화면 상단에 위치하며, 현재 시간, Wi-Fi 및 셀룰러 네트워크 정보, 배터리 수준 및 기타 상태 아이콘을 표시하는 영역이다.

네비게이터와 함께 사용하기​

동시에 여러 StatusBar 컴포넌트를 마운트할 수 있다. 이때 StatusBar 컴포넌트가 마운트된 순서대로 props가 병합된다.

명령형 API​

컴포넌트를 사용하기 어려운 경우를 대비해, 컴포넌트에 정적 함수로 명령형 API를 제공한다. 하지만 동일한 프로퍼티에 대해 정적 API와 컴포넌트를 함께 사용하는 것은 권장하지 않는다. 정적 API로 설정한 값은 다음 리렌더링에서 컴포넌트가 설정한 값으로 덮어쓰일 수 있기 때문이다.

참조

상수​

currentHeight
Android
​

상태 표시줄의 높이를 나타낸다. 노치가 있는 경우 노치 높이도 포함된다.

Props​

animated​

상태 바 속성 변경 시 트랜지션에 애니메이션을 적용할지 여부를 결정한다. backgroundColor, barStyle, hidden 속성에서 지원된다.

타입필수 여부기본값
boolean아니오false

backgroundColor
Android
​

상태 바의 배경색을 지정한다.

warning

Android 15에서 도입된 edge-to-edge 강제 적용으로 인해, API 레벨 35부터는 상태 바의 배경색 설정이 더 이상 사용되지 않는다.

타입필수 여부기본값
color아니오시스템 기본 상태 바 배경색, 정의되지 않은 경우 'black'으로 설정됨

barStyle​

상태 바 텍스트의 색상을 설정한다.

안드로이드에서는 API 버전 23 이상에서만 적용된다.

타입필수 여부기본값
StatusBarStyle아니오'default'

hidden​

상태 바를 숨길지 여부를 결정한다.

타입필수 여부기본값
boolean아니오false

networkActivityIndicatorVisible
iOS
​

네트워크 활동 표시기가 보여야 하는지 여부를 설정한다.

타입기본값
booleanfalse

showHideTransition
iOS
​

hidden prop을 사용하여 상태 바를 보이거나 숨길 때 적용되는 트랜지션 효과를 설정한다.

타입기본값
StatusBarAnimation'fade'

translucent
Android
​

상태 바가 반투명일 때 사용한다. translucent를 true로 설정하면 앱이 상태 바 아래에 그려진다. 이 설정은 반투명 상태 바 색상을 사용할 때 유용하다.

타입기본값
booleanfalse

메서드​

popStackEntry()​

tsx
static popStackEntry(entry: StatusBarProps);

스택에서 마지막 StatusBar 엔트리를 가져와 제거한다.

매개변수:

이름타입설명
entry
필수
anypushStackEntry에서 반환된 엔트리.

pushStackEntry()​

static pushStackEntry(props: StatusBarProps): StatusBarProps;

StatusBar 엔트리를 스택에 추가한다. 반환된 값은 작업이 완료된 후 popStackEntry에 전달해야 한다.

매개변수:

이름타입설명
props
필수
any스택 엔트리에 사용할 StatusBar 속성을 담은 객체.

replaceStackEntry()​

tsx
static replaceStackEntry(
  entry: StatusBarProps,
  props: StatusBarProps
): StatusBarProps;

기존 StatusBar 스택 엔트리를 새로운 props로 교체한다.

매개변수:

이름타입설명
entry
필수
any교체할 pushStackEntry에서 반환된 엔트리.
props
필수
any교체된 스택 엔트리에서 사용할 StatusBar props를 포함하는 객체.

setBackgroundColor()
Android
​

tsx
static setBackgroundColor(color: ColorValue, animated?: boolean);

상태 표시줄의 배경색을 설정한다.

warning

안드로이드 15에서 도입된 edge-to-edge 강제 적용으로 인해, API 레벨 35부터는 상태 표시줄의 배경색 설정이 더 이상 사용되지 않는다.

인자:

이름타입설명
color
필수
string배경색.
animatedboolean스타일 변경 시 애니메이션 적용 여부.

setBarStyle()​

tsx
static setBarStyle(style: StatusBarStyle, animated?: boolean);

상태 바 스타일을 설정한다.

매개변수:

이름타입설명
style
필수
StatusBarStyle설정할 상태 바 스타일.
animatedboolean스타일 변경 시 애니메이션 적용 여부.

setHidden()​

tsx
static setHidden(hidden: boolean, animation?: StatusBarAnimation);

상태 바를 보이거나 숨긴다.

매개변수:

이름타입설명
hidden
필수
boolean상태 바를 숨긴다.
animation
iOS
StatusBarAnimation상태 바 숨김 속성을 변경할 때 사용할 애니메이션.

setNetworkActivityIndicatorVisible()
iOS
​

tsx
static setNetworkActivityIndicatorVisible(visible: boolean);

네트워크 활동 표시기의 가시성을 제어한다.

매개변수:

이름타입설명
visible
필수
boolean표시기를 보여준다.

setTranslucent()
Android
​

tsx
static setTranslucent(translucent: boolean);

상태 바의 반투명 여부를 설정한다.

매개변수:

이름타입설명
translucent
필수
boolean반투명으로 설정할지 여부.

타입 정의​

StatusBarAnimation​

iOS에서 상태 바 전환 시 사용하는 애니메이션 타입.

타입
enum

상수:

값타입설명
'fade'string페이드 애니메이션
'slide'string슬라이드 애니메이션
'none'string애니메이션 없음

StatusBarStyle​

상태 바 스타일 타입.

타입
enum

상수:

값타입설명
'default'string기본 상태 바 스타일 (iOS는 어두운, Android는 밝은)
'light-content'string흰색 텍스트와 아이콘
'dark-content'string어두운 텍스트와 아이콘 (Android API>=23 필요)