Skip to main content
Version: Next

View

UI를 구축하는 데 가장 기본적인 컴포넌트인 View플렉스 박스, 스타일, 터치 핸들링, 그리고 접근성 컨트롤을 지원하는 컨테이너이다. View는 React Native가 실행되는 플랫폼에 따라 UIView, <div>, android.view 등과 같은 네이티브 뷰에 직접 매핑된다.

View는 다른 뷰 안에 중첩되도록 설계되었으며, 0개에서 여러 개의 자식 컴포넌트를 가질 수 있다.

아래 예제는 패딩이 적용된 행 안에 두 개의 색상 박스와 텍스트 컴포넌트를 감싸는 View를 생성한다.

View는 명확성과 성능을 위해 StyleSheet와 함께 사용하도록 설계되었지만, 인라인 스타일도 지원한다.

합성 터치 이벤트

View 컴포넌트의 응답자 속성(예: onResponderMove)에 전달되는 합성 터치 이벤트는 PressEvent 형태를 가진다.

참조

Props

accessibilityActions

접근성 액션은 보조 기술이 컴포넌트의 동작을 프로그래밍 방식으로 실행할 수 있게 한다. accessibilityActions 프로퍼티는 액션 객체의 목록을 포함해야 한다. 각 액션 객체는 namelabel 필드를 포함해야 한다.

자세한 내용은 접근성 가이드를 참고한다.

타입
배열

accessibilityElementsHidden
iOS

이 접근성 엘리먼트 내에 포함된 접근성 엘리먼트들이 숨겨져 있는지 여부를 나타내는 값이다. 기본값은 false이다.

자세한 내용은 접근성 가이드를 참고한다.

타입
bool

accessibilityHint

접근성 힌트는 사용자가 접근성 엘리먼트에 특정 동작을 수행했을 때 어떤 결과가 발생할지 이해하는 데 도움을 준다. 이는 접근성 레이블만으로는 명확하지 않은 경우에 유용하다.

타입
string

accessibilityLanguage
iOS

화면 리더가 사용자가 엘리먼트와 상호작용할 때 사용할 언어를 지정하는 값이다. 이 값은 BCP 47 사양을 따라야 한다.

자세한 정보는 iOS accessibilityLanguage 문서를 참고한다.

타입
string

accessibilityIgnoresInvertColors
iOS

색상 반전 기능이 활성화되었을 때, 이 뷰가 반전되어야 하는지 여부를 나타내는 값이다. true로 설정하면 색상 반전 기능이 켜져 있어도 뷰가 반전되지 않는다.

자세한 내용은 접근성 가이드를 참고한다.

타입
bool

accessibilityLabel

사용자가 엘리먼트와 상호작용할 때 스크린 리더가 읽는 텍스트를 재정의한다. 기본적으로 라벨은 모든 자식 엘리먼트를 순회하며 공백으로 구분된 Text 노드를 누적해 생성된다.

타입
string

accessibilityLiveRegion
Android

이 속성은 뷰가 변경될 때 접근성 서비스가 사용자에게 알릴지 여부를 지정한다. Android API 19 이상에서만 작동한다. 가능한 값은 다음과 같다:

  • 'none' - 접근성 서비스가 이 뷰의 변경 사항을 알리지 않는다.
  • 'polite' - 접근성 서비스가 이 뷰의 변경 사항을 알린다.
  • 'assertive' - 접근성 서비스가 진행 중인 음성을 중단하고 즉시 이 뷰의 변경 사항을 알린다.

자세한 내용은 Android View 문서를 참고한다.

타입
enum('none', 'polite', 'assertive')

accessibilityRole

accessibilityRole은 보조 기술 사용자에게 컴포넌트의 목적을 전달한다.

accessibilityRole은 다음과 같은 값 중 하나를 가질 수 있다:

  • 'none' - 엘리먼트에 역할이 없을 때 사용한다.
  • 'button' - 엘리먼트를 버튼으로 처리해야 할 때 사용한다.
  • 'link' - 엘리먼트를 링크로 처리해야 할 때 사용한다.
  • 'search' - 텍스트 필드 엘리먼트를 검색 필드로도 처리해야 할 때 사용한다.
  • 'image' - 엘리먼트를 이미지로 처리해야 할 때 사용한다. 예를 들어 버튼이나 링크와 결합할 수 있다.
  • 'keyboardkey' - 엘리먼트가 키보드 키 역할을 할 때 사용한다.
  • 'text' - 엘리먼트를 변경할 수 없는 정적 텍스트로 처리해야 할 때 사용한다.
  • 'adjustable' - 엘리먼트가 조정 가능할 때 사용한다 (예: 슬라이더).
  • 'imagebutton' - 엘리먼트를 버튼으로 처리해야 하면서 동시에 이미지일 때 사용한다.
  • 'header' - 엘리먼트가 콘텐츠 섹션의 헤더 역할을 할 때 사용한다 (예: 네비게이션 바의 제목).
  • 'summary' - 앱이 처음 실행될 때 현재 상태를 빠르게 요약하는 데 사용할 수 있는 엘리먼트일 때 사용한다.
  • 'alert' - 엘리먼트가 사용자에게 중요한 텍스트를 포함하고 있을 때 사용한다.
  • 'checkbox' - 엘리먼트가 체크박스를 나타낼 때 사용한다. 체크, 언체크, 혼합 상태를 가질 수 있다.
  • 'combobox' - 엘리먼트가 콤보박스를 나타낼 때 사용한다. 사용자가 여러 선택지 중 하나를 선택할 수 있다.
  • 'menu' - 컴포넌트가 선택지 메뉴일 때 사용한다.
  • 'menubar' - 컴포넌트가 여러 메뉴의 컨테이너일 때 사용한다.
  • 'menuitem' - 메뉴 내의 항목을 나타낼 때 사용한다.
  • 'progressbar' - 작업의 진행 상태를 나타내는 컴포넌트일 때 사용한다.
  • 'radio' - 라디오 버튼을 나타낼 때 사용한다.
  • 'radiogroup' - 라디오 버튼 그룹을 나타낼 때 사용한다.
  • 'scrollbar' - 스크롤 바를 나타낼 때 사용한다.
  • 'spinbutton' - 선택지 목록을 열 수 있는 버튼을 나타낼 때 사용한다.
  • 'switch' - 켜고 끌 수 있는 스위치를 나타낼 때 사용한다.
  • 'tab' - 탭을 나타낼 때 사용한다.
  • 'tablist' - 탭 목록을 나타낼 때 사용한다.
  • 'timer' - 타이머를 나타낼 때 사용한다.
  • 'toolbar' - 툴바(액션 버튼이나 컴포넌트의 컨테이너)를 나타낼 때 사용한다.
  • 'grid' - ScrollView, VirtualizedList, FlatList, SectionList와 함께 사용해 그리드를 나타낼 때 사용한다. 안드로이드 GridView에 그리드 내/외부 알림을 추가한다.
타입
string

accessibilityState

어시스턴트 기술 사용자에게 컴포넌트의 현재 상태를 설명한다.

더 자세한 내용은 접근성 가이드를 참고한다.

타입
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}

accessibilityValue

컴포넌트의 현재 값을 나타낸다. 컴포넌트 값에 대한 텍스트 설명이거나, 슬라이더나 프로그레스 바와 같은 범위 기반 컴포넌트의 경우 범위 정보(최소값, 현재값, 최대값)를 포함한다.

자세한 내용은 접근성 가이드를 참고한다.

타입
객체: {min: number, max: number, now: number, text: string}

accessibilityViewIsModal
iOS

VoiceOver가 수신자와 동일한 레벨에 있는 뷰의 엘리먼트들을 무시해야 하는지 여부를 나타내는 값이다. 기본값은 false이다.

자세한 내용은 접근성 가이드를 참고한다.

타입
bool

accessibletrue로 설정되면, 해당 뷰가 접근성 엘리먼트임을 나타낸다. 기본적으로 모든 터치 가능한 엘리먼트는 접근성을 갖는다.

aria-busy

해당 엘리먼트가 수정 중임을 나타내며, 보조 기술이 변경이 완료될 때까지 기다린 후 사용자에게 업데이트를 알려야 할 수 있음을 의미한다.

타입기본값
booleanfalse

aria-checked

체크 가능한 엘리먼트의 상태를 나타낸다. 이 속성은 불리언 값이나 "mixed" 문자열을 받아 혼합 체크박스를 표현할 수 있다.

타입기본값
boolean, 'mixed'false

aria-disabled

해당 엘리먼트가 인지 가능하지만 비활성화 상태임을 나타낸다. 따라서 편집이 불가능하거나 다른 방식으로 동작하지 않는다.

타입기본값
booleanfalse

aria-expanded

확장 가능한 엘리먼트가 현재 확장되었는지 혹은 축소되었는지를 나타낸다.

타입기본값
booleanfalse

aria-hidden

이 속성은 접근성 엘리먼트 내부의 접근성 요소들이 숨겨져 있는지 여부를 나타낸다.

예를 들어, AB라는 형제 뷰를 포함하는 윈도우에서 뷰 Baria-hiddentrue로 설정하면, VoiceOver가 뷰 B 내부의 요소들을 무시하게 된다.

타입기본값
booleanfalse

aria-label은 상호작용 가능한 엘리먼트에 대한 레이블 문자열을 정의한다.

타입
string

aria-labelledby
Android

해당 속성이 적용된 엘리먼트를 설명하는 엘리먼트를 식별한다. aria-labelledby의 값은 관련 엘리먼트의 nativeID와 일치해야 한다:

tsx
<View>
<Text nativeID="formLabel">입력 필드 라벨</Text>
<TextInput aria-label="input" aria-labelledby="formLabel" />
</View>
타입
string

aria-live
Android

엘리먼트가 업데이트될 것임을 나타내며, 사용자 에이전트, 보조 기술, 사용자가 라이브 영역에서 어떤 업데이트를 기대할 수 있는지 설명한다.

  • off 보조 기술이 이 뷰의 변경 사항을 알리지 않아야 한다.
  • polite 보조 기술이 이 뷰의 변경 사항을 알려야 한다.
  • assertive 보조 기술이 진행 중인 음성을 중단하고 즉시 이 뷰의 변경 사항을 알려야 한다.
타입기본값
enum('assertive', 'off', 'polite')'off'

aria-modal
iOS

VoiceOver가 해당 엘리먼트의 형제 뷰 내부의 엘리먼트들을 무시해야 하는지를 나타내는 불리언 값이다. 이 속성은 accessibilityViewIsModal 속성보다 우선한다.

타입기본값
booleanfalse

aria-selected

선택 가능한 엘리먼트가 현재 선택되었는지 여부를 나타낸다.

타입
boolean

aria-valuemax

범위 기반 컴포넌트(예: 슬라이더, 진행률 표시기)의 최대값을 나타낸다. accessibilityValue prop의 max 값보다 우선순위가 높다.

타입
number

aria-valuemin

범위 기반 컴포넌트(예: 슬라이더, 프로그레스 바)에서 사용할 수 있는 최소값을 나타낸다. 이 값은 accessibilityValue prop의 min 값보다 우선순위를 가진다.

타입
number

aria-valuenow

범위 기반 컴포넌트(예: 슬라이더, 프로그레스 바)의 현재 값을 나타낸다. accessibilityValue 프로퍼티의 now 값보다 우선순위가 높다.

타입
number

aria-valuetext

컴포넌트의 텍스트 설명을 나타낸다. accessibilityValue prop의 text 값보다 우선순위를 가진다.

타입
string

collapsable

자식 요소를 배치하거나 아무것도 그리지 않는 뷰는 최적화를 위해 네이티브 계층 구조에서 자동으로 제거될 수 있다. 이 최적화를 비활성화하고 해당 뷰가 네이티브 뷰 계층 구조에 존재하도록 보장하려면 이 속성을 false로 설정한다.

타입기본값
booleantrue

collapsableChildren

이 값을 false로 설정하면 뷰의 직접적인 자식들이 네이티브 뷰 계층 구조에서 제거되지 않는다. 이는 각 자식에 collapsable={false}를 설정한 것과 같은 효과를 낸다.

타입기본값
booleantrue

focusable
Android

View가 터치가 아닌 입력 장치(예: 하드웨어 키보드)로 포커스를 받을 수 있는지 여부를 결정한다.

타입
boolean

hitSlop

이 속성은 터치 이벤트가 뷰에서 얼마나 멀리 떨어진 곳에서 시작할 수 있는지를 정의한다. 일반적인 인터페이스 가이드라인에서는 터치 대상이 최소 30~40 포인트 또는 밀도 독립적 픽셀(density-independent pixels)이 되도록 권장한다.

예를 들어, 터치 가능한 뷰의 높이가 20일 때, hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}을 사용하면 터치 가능한 높이를 40으로 확장할 수 있다.

터치 영역은 부모 뷰의 경계를 넘어가지 않으며, 두 개의 겹치는 뷰에 동시에 터치가 발생할 경우 형제 뷰의 Z-index가 항상 우선순위를 가진다.

타입
객체: {top: number, left: number, bottom: number, right: number}

id

이 속성은 네이티브 클래스에서 이 뷰를 찾기 위해 사용한다. nativeID 속성보다 우선순위가 높다.

이 속성을 사용하면 '레이아웃 전용 뷰 제거' 최적화가 비활성화된다!

타입
string

importantForAccessibility
Android

이 속성은 뷰가 접근성 이벤트를 발생시키는지, 그리고 화면을 조회하는 접근성 서비스에 보고되는지 여부를 제어한다. Android에서만 동작한다.

가능한 값:

  • 'auto' - 시스템이 뷰가 접근성에 중요한지 여부를 결정한다. 기본값이며 권장된다.
  • 'yes' - 뷰가 접근성에 중요하다.
  • 'no' - 뷰가 접근성에 중요하지 않다.
  • 'no-hide-descendants' - 뷰뿐만 아니라 하위 뷰들도 접근성에 중요하지 않다.

참고: Android importantForAccessibility 문서

타입
enum('auto', 'yes', 'no', 'no-hide-descendants')

nativeID

이 속성은 네이티브 클래스에서 해당 뷰를 찾는 데 사용한다.

이 속성을 사용하면 해당 뷰에 대해 '레이아웃 전용 뷰 제거' 최적화 기능이 비활성화된다!

타입
string

View가 100% 정확한 색상과 블렌딩 동작을 유지하기 위해 오프스크린에서 렌더링되고 알파 값과 함께 합성되어야 하는지 여부를 결정한다. 기본값(false)은 전체 컴포넌트를 오프스크린에서 렌더링하고 알파 값으로 다시 합성하는 대신, 각 엘리먼트를 그리는 데 사용된 페인트에 알파를 적용해 컴포넌트와 그 자식 요소를 그리는 방식으로 동작한다. 이 기본값은 투명도를 설정한 View에 여러 겹치는 요소(예: 여러 겹치는 View 또는 텍스트와 배경)가 있는 경우 눈에 띄고 원치 않는 결과를 초래할 수 있다.

올바른 알파 동작을 유지하기 위해 오프스크린에서 렌더링하는 것은 매우 비용이 많이 들고, 네이티브 개발자가 아닌 경우 디버깅이 어렵기 때문에 기본적으로 활성화되지 않는다. 애니메이션을 위해 이 속성을 활성화해야 한다면, 뷰 내용이 정적일 경우(즉, 매 프레임마다 다시 그릴 필요가 없는 경우) renderToHardwareTextureAndroid와 함께 사용하는 것을 고려해보라. 해당 속성이 활성화되면, 이 View는 한 번 오프스크린에서 렌더링되고 하드웨어 텍스처로 저장된 후, GPU에서 렌더링 대상을 전환할 필요 없이 매 프레임마다 알파 값과 함께 화면에 합성된다.

타입
bool

nextFocusDown
Android

사용자가 아래로 이동할 때 포커스를 받을 다음 뷰를 지정한다. 자세한 내용은 Android 문서를 참고한다.

타입
number

nextFocusForward
Android

사용자가 앞으로 이동할 때 포커스를 받을 다음 뷰를 지정한다. 자세한 내용은 Android 공식 문서를 참고한다.

타입
number

nextFocusLeft
Android

사용자가 왼쪽으로 네비게이션할 때 포커스를 받을 다음 뷰를 지정한다. 자세한 내용은 Android 문서를 참고한다.

타입
number

nextFocusRight
Android

사용자가 오른쪽으로 네비게이션할 때 포커스를 받을 다음 뷰를 지정한다. 자세한 내용은 Android 문서를 참고한다.

타입
number

nextFocusUp
Android

사용자가 위로 네비게이션할 때 포커스를 받을 다음 뷰를 지정한다. 자세한 내용은 Android 문서를 참고한다.

타입
number

onAccessibilityAction

사용자가 접근성 액션을 수행할 때 호출된다. 이 함수는 수행할 액션의 이름을 포함한 이벤트 객체를 유일한 인자로 받는다.

자세한 내용은 접근성 가이드를 참고한다.

타입
function

onAccessibilityEscape
iOS

accessibletrue로 설정된 상태에서 사용자가 탈출 제스처를 수행하면 시스템이 이 함수를 호출한다.

타입
function

onAccessibilityTap
iOS

accessible이 true로 설정되어 있을 때, 사용자가 접근성 탭 제스처를 수행하면 시스템이 이 함수를 호출하려고 시도한다.

타입
function

onLayout

마운트 시와 레이아웃 변경 시 호출된다.

이 이벤트는 레이아웃이 계산된 직후에 발생하지만, 특히 레이아웃 애니메이션이 진행 중일 경우 이벤트가 수신될 때 새로운 레이아웃이 아직 화면에 반영되지 않을 수 있다.

타입
({nativeEvent: LayoutEvent}) => void

onMagicTap
iOS

accessibletrue로 설정된 경우, 사용자가 매직 탭 제스처를 수행하면 시스템이 이 함수를 호출한다.

타입
function

onMoveShouldSetResponder

이 뷰가 터치 응답을 '주장'하고 싶은지 여부를 결정한다. 현재 뷰가 응답자가 아닐 때, 뷰에서 발생하는 모든 터치 이동에 대해 호출된다.

타입
({nativeEvent: PressEvent}) => boolean

onMoveShouldSetResponderCapture

부모 View가 자식 View가 이동 시 응답자(responder)가 되는 것을 막으려면, 이 핸들러가 true를 반환해야 한다.

타입
({nativeEvent: PressEvent}) => boolean

onResponderGrant

이제 뷰가 터치 이벤트에 응답한다. 이 시점에서 사용자에게 어떤 일이 발생하는지 강조하고 보여줄 수 있다.

안드로이드에서는 이 콜백에서 true를 반환하면 현재 응답자가 종료될 때까지 다른 네이티브 컴포넌트가 응답자가 되는 것을 막을 수 있다.

타입
({nativeEvent: PressEvent}) => void | boolean

onResponderMove

사용자가 손가락을 움직이고 있다.

타입
({nativeEvent: PressEvent}) => void

onResponderReject

다른 응답자(responder)가 이미 활성화되어 있어, 해당 View가 응답자로 요청했지만 이를 승인하지 않았다.

타입
({nativeEvent: PressEvent}) => void

onResponderRelease

터치가 끝날 때 발생한다.

타입
({nativeEvent: PressEvent}) => void

onResponderTerminate

View에서 응답자(responder) 권한이 제거되었다. 이는 onResponderTerminationRequest 호출 후 다른 뷰가 응답자 권한을 가져갔거나, OS가 묻지 않고 권한을 가져간 경우(예: iOS의 제어 센터/알림 센터) 발생할 수 있다.

타입
({nativeEvent: PressEvent}) => void

onResponderTerminationRequest

다른 View가 응답자(responder)가 되기를 원하며, 현재 View에게 응답자 권한을 해제할 것을 요청한다. true를 반환하면 권한을 해제한다.

타입
({nativeEvent: PressEvent}) => void

onStartShouldSetResponder

터치가 시작될 때 이 뷰가 응답자(responder)가 되길 원하는지 여부를 결정한다.

타입
({nativeEvent: PressEvent}) => boolean

onStartShouldSetResponderCapture

부모 View가 자식 View가 터치 시작 시 응답자(responder)가 되는 것을 막으려면, 이 핸들러가 true를 반환하도록 설정해야 한다.

타입
({nativeEvent: PressEvent}) => boolean

pointerEvents

View가 터치 이벤트의 대상이 될 수 있는지 여부를 제어한다.

  • 'auto': View가 터치 이벤트의 대상이 될 수 있다.
  • 'none': View는 절대 터치 이벤트의 대상이 되지 않는다.
  • 'box-none': View 자체는 터치 이벤트의 대상이 되지 않지만, 하위 뷰는 대상이 될 수 있다. 이는 CSS에서 다음과 같은 클래스를 가진 것과 동일하게 동작한다:
css
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': View는 터치 이벤트의 대상이 될 수 있지만, 하위 뷰는 대상이 되지 않는다. 이는 CSS에서 다음과 같은 클래스를 가진 것과 동일하게 동작한다:
css
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}
타입
enum('box-none', 'none', 'box-only', 'auto')

removeClippedSubviews

이 속성은 RCTView에서 제공하는 성능 최적화를 위한 예약된 속성이다. 화면 밖에 위치한 많은 하위 뷰를 가진 스크롤 콘텐츠에 유용하다. 이 속성이 효과를 발휘하려면, 뷰 경계를 벗어나는 많은 하위 뷰를 포함한 뷰에 적용해야 한다. 또한, 하위 뷰와 해당 뷰(또는 상위 뷰 중 하나)는 overflow: hidden 속성을 가져야 한다.

타입
bool

renderToHardwareTextureAndroid
Android

View가 자신과 모든 자식 뷰를 GPU의 단일 하드웨어 텍스처로 렌더링할지 여부를 결정한다.

안드로이드에서는 투명도, 회전, 이동, 크기 조정만 변경하는 애니메이션과 인터랙션에 유용하다. 이 경우 뷰를 다시 그리거나 디스플레이 리스트를 다시 실행할 필요가 없다. 텍스처를 재사용하고 다른 매개변수로 합성할 수 있다. 단점은 제한된 비디오 메모리를 사용할 수 있으므로, 인터랙션이나 애니메이션이 끝나면 이 속성을 false로 설정해야 한다.

타입
bool

role

role은 컴포넌트의 목적을 보조 기술 사용자에게 전달한다. accessibilityRole 프로퍼티보다 우선순위가 높다.

타입
Role

shouldRasterizeIOS
iOS

View를 합성하기 전에 비트맵으로 렌더링할지 여부를 결정한다.

iOS에서는 이 컴포넌트의 크기나 자식 요소를 변경하지 않는 애니메이션과 인터랙션에 유용하다. 예를 들어, 정적 뷰의 위치를 이동할 때, 래스터화를 사용하면 렌더러가 정적 뷰의 캐시된 비트맵을 재사용할 수 있고, 각 프레임마다 빠르게 합성할 수 있다.

래스터화는 오프스크린 드로잉 과정을 수반하며, 비트맵은 메모리를 소모한다. 이 속성을 사용할 때는 테스트와 측정이 필요하다.

타입
bool

style

타입
View Style

tabIndex
Android

View가 터치가 아닌 입력 장치(예: 하드웨어 키보드)로 포커스를 받을 수 있는지 여부를 결정한다. 다음 값을 지원한다:

  • 0 - View가 포커스를 받을 수 있음
  • -1 - View가 포커스를 받을 수 없음
타입
enum(0, -1)

testID

이 뷰를 엔드투엔드 테스트에서 찾기 위해 사용한다.

이 설정은 해당 뷰에 대해 '레이아웃 전용 뷰 제거' 최적화를 비활성화한다!

타입
string