react native webview

React Native WebView 전체 속성 가이드

이 문서는 react-native-webview의 모든 속성(Props)을 한글로 정리한 완전한 가이드입니다.

현재 사용 버전: react-native-webview@13.13.5

기본 속성

`ref`

타입: React.RefObject<WebView>
설명: WebView 인스턴스에 대한 참조
용도: WebView 메서드 호출 (injectJavaScript, goBack, reload, goForward, stopLoading 등)
예시: const webViewRef = useRef<WebView>(null)

`source`

타입: { uri: string } | { html: string, baseUrl?: string } | { method: string, uri: string, body?: string, headers?: object }
설명: 로드할 웹 페이지의 소스
옵션:
- { uri: string }: URL 로드
- { html: string, baseUrl?: string }: HTML 문자열 로드
- { method: string, uri: string, body?: string, headers?: object }: POST 요청 등
예시: source={{ uri: 'https://example.com' }}

`style`

타입: StyleProp<ViewStyle>
설명: WebView 컨테이너 스타일
예시: style={{ flex: 1, backgroundColor: '#fff' }}

소스 및 로딩

`startInLoadingState`

타입: boolean
기본값: false
설명: 초기 로딩 상태에서 시작할지 여부
효과: 페이지 로드 시작 시 즉시 로딩 인디케이터 표시
플랫폼: iOS, Android

`renderLoading`

타입: () => React.ReactElement
설명: 로딩 중 표시할 커스텀 컴포넌트
용도: 사용자에게 로딩 상태 피드백 제공
플랫폼: iOS, Android

`onLoadStart`

타입: (event: WebViewNavigationEvent) => void
설명: 페이지 로딩이 시작될 때 호출
이벤트 데이터: { url: string, navigationType: string }
플랫폼: iOS, Android

`onLoad`

타입: (event: WebViewNavigationEvent) => void
설명: 페이지 로드 완료 시 호출 (iOS의 경우 onLoadEnd와 유사)
플랫폼: iOS, Android

`onLoadEnd`

타입: (event: WebViewNavigationEvent) => void
설명: 페이지 로드 완료 시 호출
이벤트 데이터: { url: string, navigationType: string }
플랫폼: iOS, Android

`onLoadProgress`

타입: (event: WebViewProgressEvent) => void
설명: 페이지 로딩 진행률 변경 시 호출
이벤트 데이터: { nativeEvent: { progress: number, url: string } }
플랫폼: Android

이벤트 핸들러

`onError`

타입: (syntheticEvent: WebViewErrorEvent) => void
설명: 페이지 로드 실패 시 호출
이벤트 데이터: { nativeEvent: { code: number, description: string, domain?: string, url: string } }
플랫폼: iOS, Android

`onHttpError`

타입: (syntheticEvent: WebViewHttpErrorEvent) => void
설명: HTTP 에러 발생 시 호출 (4xx, 5xx 등)
이벤트 데이터: { nativeEvent: { statusCode: number, description: string, url: string } }
플랫폼: Android

`onMessage`

타입: (event: WebViewMessageEvent) => void
설명: 웹 페이지에서 window.ReactNativeWebView.postMessage()로 전송된 메시지 수신
이벤트 데이터: { nativeEvent: { data: string, url: string, title?: string } }
용도: 웹-네이티브 간 통신
플랫폼: iOS, Android

`onNavigationStateChange`

타입: (event: WebViewNavigation) => void
설명: 네비게이션 상태가 변경될 때 호출
이벤트 데이터: { url: string, title: string, loading: boolean, canGoBack: boolean, canGoForward: boolean, navigationType: string }
플랫폼: iOS, Android

`onShouldStartLoadWithRequest`

타입: (request: WebViewNavigation) => boolean
설명: 로딩을 시작하기 전에 호출되는 함수로, 로딩 여부를 결정할 수 있음
반환값: true면 로드 허용, false면 로드 차단
용도: 특정 URL 차단, 커스텀 스킴 처리 등
플랫폼: iOS, Android

`onContentProcessDidTerminate`

타입: (event: WebViewTerminatedEvent) => void
설명: iOS에서 WebView 프로세스가 종료되었을 때 호출
용도: 메모리 부족 등으로 프로세스가 종료된 경우 처리
플랫폼: iOS

`onRenderProcessGone`

타입: (event: WebViewRenderProcessGoneEvent) => void
설명: Android에서 렌더링 프로세스가 종료되었을 때 호출
이벤트 데이터: { nativeEvent: { didCrash: boolean } }
플랫폼: Android

JavaScript 및 스토리지

`javaScriptEnabled`

타입: boolean
기본값: true
설명: JavaScript 실행 활성화 여부
플랫폼: iOS, Android

`domStorageEnabled`

타입: boolean
기본값: false
설명: DOM Storage (localStorage, sessionStorage) 활성화
플랫폼: Android

`injectedJavaScript`

타입: string
설명: 페이지 로드 후 주입할 JavaScript 코드
용도: 페이지에 커스텀 JavaScript 코드 주입
주의: 문자열로 반환해야 하며, true를 반환하면 성공으로 간주
플랫폼: iOS, Android

`injectedJavaScriptBeforeContentLoaded`

타입: string
설명: 콘텐츠 로딩 전에 주입할 JavaScript 코드
용도: 페이지 로드 전에 스크립트 실행
플랫폼: iOS, Android

`injectedJavaScriptForMainFrameOnly`

타입: boolean
기본값: true
설명: 주입된 JavaScript를 메인 프레임에만 적용할지 여부
플랫폼: iOS, Android

`injectedJavaScriptForMainFrameOnlyIOS`

타입: boolean
기본값: true
설명: iOS에서 주입된 JavaScript를 메인 프레임에만 적용할지 여부
플랫폼: iOS

캐싱 및 성능

`cacheEnabled`

타입: boolean
기본값: true
설명: 캐시 사용 활성화
효과: 재방문 시 로딩 속도 향상
플랫폼: iOS, Android

`cacheMode`

타입: 'LOAD_DEFAULT' | 'LOAD_CACHE_ELSE_NETWORK' | 'LOAD_CACHE_ONLY' | 'LOAD_NO_CACHE'
기본값: 'LOAD_DEFAULT'
설명: 캐시 사용 모드
- LOAD_DEFAULT: 네트워크와 캐시 병행 사용
- LOAD_CACHE_ELSE_NETWORK: 캐시 우선, 없으면 네트워크
- LOAD_CACHE_ONLY: 캐시만 사용
- LOAD_NO_CACHE: 캐시 사용 안 함
플랫폼: Android

`incognito`

타입: boolean
기본값: false
설명: 시크릿 모드로 웹뷰 실행 (브라우징 데이터 저장 안 함)
효과: 쿠키, 캐시 등 저장 안 함
플랫폼: iOS, Android

보안 및 접근 제어

`originWhitelist`

타입: string[]
기본값: ['http://*', 'https://*']
설명: 허용할 URL origin 목록
와일드카드: * 사용 가능
예시: originWhitelist={['https://*', 'http://localhost:*']}

`allowsInlineMediaPlayback`

타입: boolean
기본값: false
설명: 인라인 미디어 재생 허용 (전체화면이 아닌 페이지 내 재생)
플랫폼: iOS

`allowFileAccess`

타입: boolean
기본값: false
설명: 파일 시스템 접근 허용
플랫폼: Android

`allowFileAccessFromFileURLs`

타입: boolean
기본값: false
설명: file:// URL에서 파일 접근 허용
플랫폼: Android

`allowUniversalAccessFromFileURLs`

타입: boolean
기본값: false
설명: file:// URL에서 모든 도메인 접근 허용
보안 주의: 보안 위험이 있으므로 신중히 사용
플랫폼: Android

`mixedContentMode`

타입: 'never' | 'always' | 'compatibility'
기본값: 'never'
설명: HTTPS 페이지에서 HTTP 리소스 로드 허용 여부
- never: HTTP 리소스 차단
- always: 모든 HTTP 리소스 허용
- compatibility: 호환성 모드 (일부 허용)
플랫폼: Android

`geolocationEnabled`

타입: boolean
기본값: false
설명: Geolocation API 사용 허용
플랫폼: Android

미디어 재생

`allowsInlineMediaPlayback`

타입: boolean
기본값: false
설명: 인라인 미디어 재생 허용
플랫폼: iOS

`mediaPlaybackRequiresUserAction`

타입: boolean
기본값: true
설명: 사용자 액션 없이 미디어 자동 재생 허용 여부
플랫폼: iOS, Android

`allowsFullscreenVideo`

타입: boolean
기본값: false
설명: 전체화면 비디오 재생 허용
플랫폼: iOS

`allowsAirPlayForMediaPlayback`

타입: boolean
기본값: false
설명: AirPlay를 통한 미디어 재생 허용
플랫폼: iOS

`allowsPictureInPictureMediaPlayback`

타입: boolean
기본값: false
설명: PIP(Picture-in-Picture) 미디어 재생 허용
플랫폼: iOS

`mediaCapturePermissionGrantType`

타입: 'grant' | 'deny' | 'prompt'
기본값: 'prompt'
설명: 미디어 캡처 권한 부여 유형
플랫폼: Android

UI 및 스타일링

`scalesPageToFit`

타입: boolean
기본값: false
설명: 페이지를 화면 크기에 맞게 스케일링
플랫폼: iOS, Android

`bounces`

타입: boolean
기본값: true
설명: iOS에서 스크롤 시 튕김 효과 사용 여부
플랫폼: iOS

`pagingEnabled`

타입: boolean
기본값: false
설명: iOS에서 스크롤을 페이지 단위로 할지 여부
플랫폼: iOS

`scrollEnabled`

타입: boolean
기본값: true
설명: 스크롤 활성화 여부
플랫폼: iOS, Android

`showsHorizontalScrollIndicator`

타입: boolean
기본값: true
설명: 수평 스크롤 인디케이터 표시 여부
플랫폼: iOS, Android

`showsVerticalScrollIndicator`

타입: boolean
기본값: true
설명: 수직 스크롤 인디케이터 표시 여부
플랫폼: iOS, Android

`contentInset`

타입: { top: number, left: number, bottom: number, right: number }
설명: iOS에서 웹뷰의 콘텐츠 인셋 설정
플랫폼: iOS

`automaticallyAdjustContentInsets`

타입: boolean
기본값: true
설명: iOS에서 콘텐츠 인셋을 자동으로 조정할지 여부
플랫폼: iOS

`contentInsetAdjustmentBehavior`

타입: 'never' | 'automatic' | 'always' | 'scrollableAxes'
기본값: 'never'
설명: iOS에서 콘텐츠 인셋 조정 동작
플랫폼: iOS

`decelerationRate`

타입: 'normal' | 'fast' | number
기본값: 'normal'
설명: iOS에서 스크롤 감속 속도
플랫폼: iOS

`directionalLockEnabled`

타입: boolean
기본값: false
설명: iOS에서 스크롤 방향 잠금 활성화
플랫폼: iOS

네비게이션

`allowsBackForwardNavigationGestures`

타입: boolean
기본값: false
설명: iOS에서 앞뒤로 이동하는 제스처 허용 여부
플랫폼: iOS

`pullToRefreshEnabled`

타입: boolean
기본값: true
설명: Android에서 당겨서 새로고침 기능 사용 여부
플랫폼: Android

쿠키 및 사용자 에이전트

`sharedCookiesEnabled`

타입: boolean
기본값: false
설명: 앱과 WebView 간 쿠키 공유
효과: 인증 상태 유지 및 성능 향상
플랫폼: iOS

`thirdPartyCookiesEnabled`

타입: boolean
기본값: false
설명: 서드파티 쿠키 허용
플랫폼: Android

`userAgent`

타입: string
설명: 사용자 에이전트 문자열 설정
용도: 웹사이트가 특정 브라우저로 인식하도록 설정

`applicationNameForUserAgent`

타입: string
설명: 사용자 에이전트에 추가할 애플리케이션 이름
용도: 기본 User-Agent에 앱 이름 추가

Android 전용

`androidLayerType`

타입: 'none' | 'software' | 'hardware'
기본값: 'none'
설명: 렌더링 레이어 타입
- none: 기본 레이어
- software: 소프트웨어 렌더링
- hardware: 하드웨어 가속 렌더링
효과: 하드웨어 가속으로 렌더링 성능 향상

`androidHardwareAccelerationDisabled`

타입: boolean
기본값: false
설명: 하드웨어 가속 비활성화 여부

`overScrollMode`

타입: 'always' | 'content' | 'never'
기본값: 'content'
설명: 오버스크롤 모드 설정

`saveFormDataDisabled`

타입: boolean
기본값: false
설명: 폼 데이터 저장 비활성화 여부

`textZoom`

타입: number
기본값: 100
설명: 텍스트 줌 비율 (100 = 기본 크기)

`nestedScrollEnabled`

타입: boolean
기본값: false
설명: 중첩 스크롤 활성화 여부

`setSupportMultipleWindows`

타입: boolean
기본값: true
설명: 다중 창 지원 여부

`setBuiltInZoomControls`

타입: boolean
기본값: false
설명: 내장 줌 컨트롤 표시 여부

`setDisplayZoomControls`

타입: boolean
기본값: false
설명: 줌 컨트롤 표시 여부

iOS 전용

`allowsLinkPreview`

타입: boolean
기본값: true
설명: 링크 프리뷰 (3D Touch/Long Press) 허용 여부
효과: 링크 프리뷰 비활성화로 성능 개선 가능

`dataDetectorTypes`

타입: 'phoneNumber' | 'link' | 'address' | 'calendarEvent' | 'trackingNumber' | 'flightNumber' | 'lookupSuggestion' | 'all' | 'none' | DataDetectorTypes[]
기본값: 'phoneNumber'
설명: 자동 감지할 데이터 타입
효과: 자동 감지 비활성화로 성능 개선 가능

`keyboardDisplayRequiresUserAction`

타입: boolean
기본값: true
설명: 키보드 표시 시 사용자 액션 필요 여부

`hideKeyboardAccessoryView`

타입: boolean
기본값: false
설명: 키보드 액세서리 뷰 숨김 여부

`useSharedProcessPool`

타입: boolean
기본값: true
설명: 웹뷰 간 프로세스 풀 공유 여부

`contentMode`

타입: 'recommended' | 'mobile' | 'desktop'
기본값: 'recommended'
설명: 콘텐츠 모드 설정

`enableApplePay`

타입: boolean
기본값: false
설명: Apple Pay 활성화 여부

`limitsNavigationsToAppBoundDomains`

타입: boolean
기본값: false
설명: 앱 바인딩 도메인으로 네비게이션 제한

`textInteractionEnabled`

타입: boolean
기본값: true
설명: 텍스트 상호작용 활성화 여부

`isFraudulentWebsiteWarningEnabled`

타입: boolean
기본값: true
설명: 사기 웹사이트 경고 활성화 여부

JavaScript 주입

`injectedJavaScript`

타입: string
설명: 페이지 로드 후 주입할 JavaScript 코드
반환값: 문자열을 반환해야 하며, true를 반환하면 성공으로 간주
예시:

injectedJavaScript={`
  window.ReactNativeWebView.postMessage(JSON.stringify({type: 'ready'}));
  true;
`}

`injectedJavaScriptBeforeContentLoaded`

타입: string
설명: 콘텐츠 로딩 전에 주입할 JavaScript 코드
용도: 페이지 로드 전에 스크립트 실행

`injectedJavaScriptForMainFrameOnly`

타입: boolean
기본값: true
설명: 주입된 JavaScript를 메인 프레임에만 적용할지 여부

WebView 메서드 (ref를 통한 호출)

`injectJavaScript(script: string)`

설명: 런타임에 JavaScript 코드 주입
예시: webViewRef.current?.injectJavaScript('window.location.reload();')

`goBack()`

설명: 이전 페이지로 이동

`goForward()`

설명: 다음 페이지로 이동

`reload()`

설명: 현재 페이지 새로고침

`stopLoading()`

설명: 로딩 중단

`postMessage(message: string)`

설명: 웹 페이지로 메시지 전송

`requestFocus()`

설명: WebView에 포커스 요청 (Android)

`clearCache(includeDiskFiles: boolean)`

설명: 캐시 삭제 (Android)

`clearHistory()`

설명: 히스토리 삭제 (Android)

성능 최적화 권장 사항

캐싱 활성화: cacheEnabled={true}, cacheMode="LOAD_DEFAULT"
하드웨어 가속: androidLayerType="hardware" (Android)
쿠키 공유: sharedCookiesEnabled={true} (iOS), thirdPartyCookiesEnabled={true} (Android)
불필요한 기능 비활성화: allowsLinkPreview={false}, dataDetectorTypes="none" (iOS)
JavaScript 주입 최적화: injectedJavaScriptForMainFrameOnly={true}

보안 권장 사항

originWhitelist 사용: 허용할 도메인만 명시
allowUniversalAccessFromFileURLs 주의: 보안 위험이 있으므로 신중히 사용
mixedContentMode: 가능하면 'never' 사용, 필요시 'compatibility'

참고 자료

react-native-webview GitHub
공식 문서
현재 사용 버전: react-native-webview@13.13.5