Version: Next

이미지

로컬 디스크, 네트워크, 정적 리소스, 임시 로컬 이미지 등 다양한 유형의 이미지를 표시하는 React 컴포넌트이다. 이 예제는 로컬 스토리지에서 이미지를 가져와 표시하는 방법과 네트워크에서 이미지를 가져오는 방법, 그리고 'data:' URI 스키마로 제공된 데이터에서 이미지를 표시하는 방법을 보여준다.

네트워크 이미지와 데이터 이미지의 경우, 이미지의 크기를 수동으로 지정해야 한다는 점에 유의한다!

예제

이미지에 style을 추가할 수도 있다:

Android에서 GIF와 WebP 지원

자체 네이티브 코드를 빌드할 때, Android에서는 기본적으로 GIF와 WebP를 지원하지 않는다.

앱의 필요에 따라 android/app/build.gradle에 몇 가지 선택적 모듈을 추가해야 한다.

groovy
dependencies {
  // Android Ice Cream Sandwich (API 레벨 14) 이전 버전을 지원하는 경우
  implementation 'com.facebook.fresco:animated-base-support:1.3.0'

  // 애니메이션 GIF 지원을 위해
  implementation 'com.facebook.fresco:animated-gif:3.2.0'

  // WebP 지원을 위해, 애니메이션 WebP 포함
  implementation 'com.facebook.fresco:animated-webp:3.2.0'
  implementation 'com.facebook.fresco:webpsupport:3.2.0'

  // 애니메이션 없는 WebP 지원을 위해
  implementation 'com.facebook.fresco:webpsupport:3.2.0'
}

참고: 위에 나열된 버전은 최신 버전이 아닐 수 있다. 특정 태그 버전에서 사용 중인 fresco 버전을 확인하려면 메인 리포지토리의 packages/react-native/gradle/libs.versions.toml 파일을 참고한다.

참고 자료

Props

View Props

View Props를 상속한다.

accessible

이 값이 true로 설정되면, 해당 이미지가 접근성 요소임을 나타낸다.

타입	기본값
bool	`false`

`accessibilityLabel`

사용자가 이미지와 상호작용할 때 스크린 리더가 읽어주는 텍스트다.

타입
string

`alt`

이미지의 대체 텍스트 설명을 정의하는 문자열이다. 사용자가 이미지와 상호작용할 때 스크린 리더가 이 텍스트를 읽어준다. 이 속성을 사용하면 해당 엘리먼트가 접근 가능한 것으로 자동으로 표시된다.

타입
string

`blurRadius`

blurRadius: 이미지에 추가되는 블러 필터의 블러 반경을 나타낸다.

타입
number

팁: IOS에서는 blurRadius를 5 이상으로 설정해야 한다.

`capInsets`
iOS

이미지 크기를 조정할 때, capInsets로 지정한 크기의 모서리는 고정된 크기를 유지하지만, 이미지의 중앙 부분과 테두리는 늘어난다. 이 기능은 크기 조정이 가능한 둥근 버튼, 그림자, 그리고 다른 크기 조정 가능한 애셋을 만들 때 유용하다. 더 자세한 정보는 공식 Apple 문서에서 확인할 수 있다.

타입
Rect

`crossOrigin`

이미지 리소스를 가져올 때 사용할 CORS 모드를 지정하는 키워드 문자열이다. HTML의 crossorigin 속성과 유사하게 동작한다.

anonymous: 이미지 요청 시 사용자 인증 정보를 교환하지 않는다.
use-credentials: 이미지 요청에서 Access-Control-Allow-Credentials 헤더 값을 true로 설정한다.

타입	기본값
enum(`'anonymous'`, `'use-credentials'`)	`'anonymous'`

`defaultSource`

이미지 소스를 로드하는 동안 표시할 정적 이미지를 설정한다.

타입
ImageSource

참고: 안드로이드 디버그 빌드에서는 defaultSource prop이 무시된다.

`fadeDuration`
Android

페이드 애니메이션 지속 시간을 밀리초 단위로 설정한다.

타입	기본값
number	`300`

`height`

이미지 컴포넌트의 높이를 지정한다.

타입
number

`loadingIndicatorSource`

source 속성과 유사하게, 이 속성은 이미지의 로딩 인디케이터를 렌더링하는 데 사용되는 리소스를 나타낸다. 로딩 인디케이터는 이미지가 표시될 준비가 될 때까지, 일반적으로 이미지가 다운로드된 후에 표시된다.

타입
ImageSource (`uri`만 해당), number

`onError`

로드 오류가 발생했을 때 호출된다.

타입
(`{nativeEvent: {error} }`) => void

`onLayout`

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

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

`onLoad`

로드가 성공적으로 완료될 때 호출된다.

예제: onLoad={({nativeEvent: {source: {width, height}}}) => setImageRealSize({width, height})}

타입
`({nativeEvent: ImageLoadEvent} => void`

`onLoadEnd`

로드가 성공하거나 실패했을 때 호출된다.

타입
() => void

`onLoadStart`

로드가 시작될 때 호출된다.

예제: onLoadStart={() => this.setState({loading: true})}

타입
() => void

`onPartialLoad`
iOS

이미지의 일부가 로드 완료될 때 호출된다. "일부 로드"의 정의는 로더에 따라 다르지만, 주로 점진적 JPEG 로드를 위해 사용된다.

타입
() => void

`onProgress`

다운로드 진행 상황에서 호출된다.

타입
(`{nativeEvent: {loaded, total} }`) => void

`progressiveRenderingEnabled`
Android

true로 설정하면 점진적 JPEG 스트리밍을 활성화한다. 자세한 내용은 https://frescolib.org/docs/progressive-jpegs를 참고한다.

타입	기본값
bool	`false`

`referrerPolicy`

리소스를 가져올 때 사용할 리퍼러를 지정하는 문자열이다. 이미지 요청 시 Referrer-Policy 헤더의 값을 설정한다. HTML의 referrerpolicy 속성과 유사하게 동작한다.

타입	기본값
enum(`'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`, `'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`, `'strict-origin-when-cross-origin'`, `'unsafe-url'`)	`'strict-origin-when-cross-origin'`

`resizeMethod`
Android

이미지 뷰의 크기와 이미지의 크기가 다를 때 이미지를 조정하는 방식을 설정한다. 기본값은 auto이다.

auto: resize와 scale 중 적절한 방식을 자동으로 선택한다.
resize: 이미지를 디코딩하기 전에 메모리에서 인코딩된 이미지의 크기를 변경하는 소프트웨어 연산이다. 이미지가 뷰보다 훨씬 큰 경우 scale 대신 이 방식을 사용한다.
scale: 이미지를 축소하거나 확대하여 그린다. resize에 비해 일반적으로 더 빠르고(주로 하드웨어 가속을 사용) 더 높은 품질의 이미지를 생성한다. 이미지가 뷰보다 작거나 약간 큰 경우 이 방식을 사용한다.
none: 이미지 샘플링을 수행하지 않고 원본 해상도로 이미지를 표시한다. 이 방식은 메모리를 과도하게 소모하는 이미지를 렌더링하려고 할 때 Android가 런타임 예외를 발생시킬 수 있으므로, 특수한 경우에만 사용해야 한다.

resize와 scale에 대한 자세한 내용은 https://frescolib.org/docs/resizing에서 확인할 수 있다.

타입	기본값
enum(`'auto'`, `'resize'`, `'scale'`, `'none'`)	`'auto'`

`resizeMode`

이미지의 원본 크기와 프레임 크기가 일치하지 않을 때 이미지를 어떻게 조정할지 결정한다. 기본값은 cover이다.

cover: 이미지를 균일하게 스케일링한다(이미지의 가로세로 비율 유지).
- 이미지의 너비와 높이가 뷰의 해당 차원(패딩 제외)보다 크거나 같게 조정된다.
- 스케일링된 이미지의 최소 한 차원은 뷰의 해당 차원(패딩 제외)과 동일하게 맞춰진다.
contain: 이미지를 균일하게 스케일링한다(이미지의 가로세로 비율 유지).
- 이미지의 너비와 높이가 뷰의 해당 차원(패딩 제외)보다 작거나 같게 조정된다.
stretch: 너비와 높이를 독립적으로 스케일링한다. 이 경우 이미지의 가로세로 비율이 변경될 수 있다.
repeat: 이미지를 반복하여 뷰의 프레임을 채운다. 이미지는 원래 크기와 가로세로 비율을 유지하되, 뷰보다 큰 경우 균일하게 축소되어 뷰 안에 포함된다.
center: 이미지를 뷰의 중앙에 배치한다. 이미지가 뷰보다 큰 경우 균일하게 축소되어 뷰 안에 포함된다.

타입	기본값
enum(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

resizeMethod가 resize로 설정된 경우, 목표 크기에 이 값을 곱한다. 나머지 크기 조정은 scale 메서드를 사용해 수행한다. 기본값인 1.0은 비트맵 크기가 목표 크기에 맞도록 설계됨을 의미한다. 1.0보다 큰 값을 사용하면 크기 조정 옵션이 목표 크기보다 크게 설정되고, 결과 비트맵은 하드웨어 크기에서 축소된다. 기본값은 1.0이다.

이 속성은 목표 크기가 매우 작고 원본 이미지가 상당히 큰 경우에 가장 유용하다. resize 메서드는 다운샘플링을 수행하며, 원본과 목표 이미지 크기 사이에서 상당한 화질 손실이 발생해 흐릿한 이미지가 나올 수 있다. resizeMultiplier를 사용하면 디코딩된 이미지가 목표 크기보다 약간 크지만 원본 이미지보다는 작아진다(원본 이미지가 충분히 큰 경우). 이를 통해 배율이 적용된 이미지에 스케일링 작업을 수행해 가짜 화질을 생성하는 앨리어싱 아티팩트를 활용할 수 있다.

예를 들어, 원본 이미지 크기가 200x200이고 목표 크기가 24x24인 경우, resizeMultiplier를 2.0으로 설정하면 Fresco는 이미지를 48x48로 다운샘플링한다. Fresco는 가장 가까운 2의 거듭제곱 크기(즉, 50x50)를 선택하고 그 크기의 비트맵으로 이미지를 디코딩한다. resizeMultiplier를 사용하지 않으면 가장 가까운 2의 거듭제곱 크기는 25x25가 된다. 결과 이미지는 시스템에 의해 축소된다.

타입	기본값
number	`1.0`

`source`

이미지 소스는 원격 URL이나 로컬 파일 리소스를 지정한다.

이 속성은 여러 개의 원격 URL을 함께 지정할 수 있다. 각 URL은 너비와 높이를 포함하며, 스케일이나 기타 URI 인자를 추가로 지정할 수도 있다. 네이티브 측에서는 이미지 컨테이너의 측정된 크기를 기반으로 가장 적합한 uri를 선택하여 표시한다. cache 속성을 추가하면 네트워크 요청이 로컬 캐시와 어떻게 상호작용할지 제어할 수 있다. (자세한 내용은 이미지 캐시 제어를 참조)

현재 지원되는 포맷은 png, jpg, jpeg, bmp, gif, webp, psd (iOS 전용)이다. 또한 iOS는 여러 RAW 이미지 포맷을 지원한다. 지원되는 카메라 모델의 최신 목록은 Apple의 문서를 참조한다 (iOS 12의 경우 https://support.apple.com/en-ca/HT208967 참조).

webp 포맷은 iOS에서 JavaScript 코드와 함께 번들링된 경우에만 지원된다는 점에 유의한다.

타입
ImageSource

`src`

이미지의 원격 URL을 나타내는 문자열이다. 이 prop은 source prop보다 우선순위가 높다.

예제: src={'https://reactnative.dev/img/tiny_logo.png'}

타입
string

`srcSet`

이미지 소스의 후보 목록을 쉼표로 구분한 문자열이다. 각 이미지 소스는 이미지의 URL과 픽셀 밀도 설명자를 포함한다. 설명자가 지정되지 않으면 기본값으로 1x 설명자가 사용된다.

srcSet에 1x 설명자가 포함되어 있지 않으면, src에 제공된 값이 1x 설명자와 함께 이미지 소스로 사용된다.

이 프로퍼티는 src와 source 프로퍼티보다 우선순위가 높다.

예시: srcSet={'https://reactnative.dev/img/tiny_logo.png 1x, https://reactnative.dev/img/header_logo.svg 2x'}

타입
string

`style`

타입
이미지 스타일 프로퍼티, 레이아웃 프로퍼티, 그림자 프로퍼티, 변형

`testID`

UI Automation 테스트 스크립트에서 사용할 이 엘리먼트의 고유 식별자이다.

타입
string

`tintColor`

모든 불투명 픽셀의 색상을 tintColor로 변경한다.

타입
color

`width`

이미지 컴포넌트의 너비를 나타낸다.

타입
number

메서드

`abortPrefetch()`
Android

tsx
static abortPrefetch(requestId: number);

미리 가져오기 요청을 중단한다.

매개변수:

이름	타입	설명
requestId 필수	number	`prefetch()`에서 반환된 요청 ID.

`getSize()`

tsx
static getSize(uri: string): Promise<{width: number, height: number}>;

이미지를 화면에 표시하기 전에 해당 이미지의 너비와 높이를 픽셀 단위로 가져온다. 이미지를 찾을 수 없거나 다운로드에 실패하면 이 메서드는 실패할 수 있다.

이미지의 크기를 가져오기 위해, 이미지를 먼저 로드하거나 다운로드해야 할 수 있으며, 이후 캐싱된다. 이 원리를 활용해 이미지를 미리 로드하는 용도로 이 메서드를 사용할 수 있지만, 이 메서드는 그 목적으로 최적화되지는 않았다. 또한 향후 이미지 데이터를 완전히 로드하거나 다운로드하지 않는 방식으로 구현될 가능성이 있다. 이미지를 미리 로드하기 위한 적절하고 공식적으로 지원되는 방법은 별도의 API로 제공될 예정이다.

매개변수:

이름	타입	설명
uri 필수	string	이미지의 위치를 나타낸다.

`getSizeWithHeaders()`

tsx
static getSizeWithHeaders(
  uri: string,
  headers: {[index: string]: string}
): Promise<{width: number, height: number}>;

이미지를 화면에 표시하기 전에 해당 이미지의 너비와 높이(픽셀 단위)를 가져온다. 요청 시 헤더를 제공할 수 있는 기능을 포함한다. 이미지를 찾을 수 없거나 다운로드에 실패하면 이 메서드는 실패할 수 있다. 또한 정적 이미지 리소스에는 작동하지 않는다.

이미지의 크기를 가져오기 위해 이미지를 먼저 로드하거나 다운로드해야 할 수 있으며, 이후 캐싱된다. 이 원리를 통해 이미지를 미리 로드하는 데 이 메서드를 사용할 수 있지만, 이 목적에 최적화되지는 않았다. 또한 향후 이미지 데이터를 완전히 로드하거나 다운로드하지 않는 방식으로 구현될 가능성이 있다. 이미지를 미리 로드하는 적절하고 지원되는 방법은 별도의 API로 제공될 예정이다.

매개변수:

이름	타입	설명
uri 필수	string	이미지의 위치.
headers 필수	object	요청에 사용할 헤더.

`prefetch()`

tsx
await Image.prefetch(url);

원격 이미지를 디스크 캐시에 미리 다운로드하여 나중에 사용할 수 있도록 준비한다. 이 메서드는 boolean 값을 반환하는 Promise를 리턴한다.

인자:

이름	타입	설명
url 필수	string	이미지의 원격 위치.
callback	function Android	`requestId`와 함께 호출될 함수.

`queryCache()`

tsx
static queryCache(
  urls: string[],
): Promise<Record<string, 'memory' | 'disk' | 'disk/memory'>>;

캐시 조회를 수행한다. URL과 캐시 상태("disk", "memory", "disk/memory")를 매핑한 결과를 반환하는 Promise를 반환한다. 요청한 URL이 매핑에 포함되지 않았다면 해당 URL이 캐시에 없다는 의미이다.

매개변수:

이름	타입	설명
urls Required	배열	캐시를 확인할 이미지 URL 목록.

`resolveAssetSource()`

tsx
static resolveAssetSource(source: ImageSourcePropType): {
  height: number;
  width: number;
  scale: number;
  uri: string;
};

이 메서드는 에셋 참조를 uri, scale, width, height 속성을 가진 객체로 변환한다.

인자:

이름	타입	설명
source 필수	ImageSource, number	`require('./foo.png')`로 반환된 숫자(불투명 타입) 또는 ImageSource.

타입 정의

ImageCacheEnum
iOS

캐시 처리 방식 또는 전략을 설정할 때 사용할 수 있는 열거형(enum)이다. 이는 잠재적으로 캐시된 응답에 적용된다.

타입	기본값
enum(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

default: 네이티브 플랫폼의 기본 전략을 사용한다.
reload: URL에 대한 데이터는 원본 소스에서 로드된다. URL 로드 요청을 처리하기 위해 기존 캐시 데이터를 사용하지 않는다.
force-cache: 캐시에 저장된 기존 데이터를 사용해 요청을 처리한다. 데이터의 유효 기간이나 만료 날짜와 상관없이 캐시 데이터를 활용한다. 요청에 해당하는 데이터가 캐시에 없을 경우, 원본 소스에서 데이터를 로드한다.
only-if-cached: 캐시에 저장된 기존 데이터를 사용해 요청을 처리한다. 데이터의 유효 기간이나 만료 날짜와 상관없이 캐시 데이터를 활용한다. 요청에 해당하는 데이터가 캐시에 없을 경우, 원본 소스에서 데이터를 로드하지 않고 요청이 실패한 것으로 간주한다.

이미지 로드 이벤트

onLoad 콜백에서 반환되는 객체.

타입
object

속성:

이름	타입	설명
source	object	소스 객체

소스 객체

속성:

이름	타입	설명
width	number	로드된 이미지의 너비.
height	number	로드된 이미지의 높이.
uri	string	이미지의 리소스 식별자를 나타내는 문자열.

이미지 소스(ImageSource)

타입
객체, 객체 배열, 숫자

객체 또는 객체 배열로 전달할 경우의 속성:

이름	타입	설명
uri	문자열	이미지의 리소스 식별자를 나타내는 문자열. HTTP 주소, 로컬 파일 경로, 또는 정적 이미지 리소스 이름일 수 있다.
width	숫자	빌드 시점에 알려진 경우 지정할 수 있으며, 이 값은 기본 `<Image/>` 컴포넌트의 크기를 설정하는 데 사용된다.
height	숫자	빌드 시점에 알려진 경우 지정할 수 있으며, 이 값은 기본 `<Image/>` 컴포넌트의 크기를 설정하는 데 사용된다.
scale	숫자	이미지의 스케일 팩터를 나타낸다. 지정하지 않으면 기본값은 `1.0`이며, 이는 하나의 이미지 픽셀이 하나의 디스플레이 포인트(DIP)에 해당함을 의미한다.
bundle iOS	문자열	이미지가 포함된 iOS 에셋 번들. 설정하지 않으면 기본값은 `[NSBundle mainBundle]`이다.
method	문자열	사용할 HTTP 메서드. 지정하지 않으면 기본값은 `'GET'`이다.
headers	객체	원격 이미지 요청과 함께 보낼 HTTP 헤더를 나타내는 객체.
body	문자열	요청과 함께 보낼 HTTP 본문. 유효한 UTF-8 문자열이어야 하며, 추가 인코딩(예: URL 이스케이핑 또는 base64) 없이 지정된 대로 전송된다.
cache iOS	ImageCacheEnum	요청이 캐시된 응답을 어떻게 처리할지 결정한다.

숫자로 전달할 경우:

number - require('./image.jpg')와 같은 방식으로 반환된 불투명 타입.

예제​

Android에서 GIF와 WebP 지원​

참고 자료

Props​

View Props​

accessibilityLabel​

alt​

blurRadius​

capInsets iOS​

crossOrigin​

defaultSource​

fadeDuration Android​

height​

loadingIndicatorSource​

onError​

onLayout​

onLoad​

onLoadEnd​

onLoadStart​

onPartialLoad iOS​

onProgress​

progressiveRenderingEnabled Android​

referrerPolicy​

resizeMethod Android​

resizeMode​

resizeMultiplier Android​

source​

src​

srcSet​

style​

testID​

tintColor​

width​

메서드​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

타입 정의​

ImageCacheEnum iOS​

이미지 로드 이벤트​

소스 객체​

이미지 소스(ImageSource)​

예제

Android에서 GIF와 WebP 지원

Props

View Props

`accessibilityLabel`

`alt`

`blurRadius`

`capInsets`
iOS

`crossOrigin`

`defaultSource`

`fadeDuration`
Android

`height`

`loadingIndicatorSource`

`onError`

`onLayout`

`onLoad`

`onLoadEnd`

`onLoadStart`

`onPartialLoad`
iOS

`onProgress`

`progressiveRenderingEnabled`
Android

`referrerPolicy`

`resizeMethod`
Android

`resizeMode`

`resizeMultiplier`
Android

`source`

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

메서드

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

타입 정의

ImageCacheEnum
iOS

이미지 로드 이벤트

소스 객체

이미지 소스(ImageSource)