이미지

로컬 저장소, 네트워크, 그리고 'data:' URI 스키마를 통해 제공된 이미지 등 다양한 유형의 이미지를 표시하는 React 컴포넌트를 만드는 예제이다.

이 예제는 로컬 저장소에서 이미지를 가져와 표시하는 방법과 네트워크에서 이미지를 가져오는 방법, 그리고 'data:' URI 스키마를 통해 제공된 이미지를 표시하는 방법을 보여준다.

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

예제

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

안드로이드에서 GIF와 WebP 지원

안드로이드에서 네이티브 코드를 직접 빌드할 때, GIF와 WebP는 기본적으로 지원되지 않는다. 앱의 필요에 따라 android/app/build.gradle에 몇 가지 선택적 모듈을 추가해야 한다.

groovy
dependencies {
  // 아이스크림 샌드위치(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 속성이 무시된다.

`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 스트리밍을 활성화한다. 자세한 내용은 Fresco 문서를 참고한다.

타입	기본값
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에 비해 scale은 더 빠르고(일반적으로 하드웨어 가속됨) 더 높은 품질의 이미지를 생성한다. 이미지가 뷰보다 작은 경우 이 방식을 사용해야 한다. 또한 이미지가 뷰보다 약간 큰 경우에도 이 방식을 사용한다.
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`

이미지 소스는 원격 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 설명자와 함께 이미지 소스로 사용된다.

이 prop은 src와 source prop보다 우선순위를 가진다.

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

타입
string

`style`

타입
이미지 스타일 속성, 레이아웃 속성, 그림자 속성, 변형 속성

`testID`

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

타입
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);

원격 이미지를 미리 가져와 디스크 캐시에 저장한다. 이후 사용을 위해 이미지를 준비한다. 이 함수는 Promise를 반환하며, 이 Promise는 boolean 값으로 resolve 된다.

매개변수:

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

`queryCache()`

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

캐시 상태를 조회한다. 이 메서드는 URL을 키로 하고 캐시 상태("disk", "memory", "disk/memory")를 값으로 하는 맵핑을 반환하는 Promise를 리턴한다. 요청한 URL이 맵핑에 포함되지 않았다면, 해당 URL은 캐시에 없다는 의미다.

매개변수:

이름	타입	설명
urls Required	array	캐시 상태를 확인할 이미지 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: 캐시에 저장된 기존 데이터만 사용해 요청을 처리한다. 데이터의 유효 기간이나 만료 날짜에 상관없이 캐시된 데이터를 우선적으로 사용한다. 요청에 해당하는 데이터가 캐시에 없을 경우, 원본 소스에서 데이터를 불러오지 않고 요청이 실패한 것으로 간주한다.

ImageLoadEvent

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	요청이 캐시된 응답을 어떻게 처리할지 결정한다.

숫자로 전달할 경우:

숫자 - require('./image.jpg')와 같은 방식으로 반환되는 불투명 타입.

예제​

안드로이드에서 GIF와 WebP 지원​

참조

Props​

View Props​

accessible​

accessibilityLabel​

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​

src​

srcSet​

style​

testID​

tintColor​

width​

메서드​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

타입 정의​

ImageCacheEnum iOS​

ImageLoadEvent​

소스 객체​

이미지 소스(ImageSource)​

예제

안드로이드에서 GIF와 WebP 지원

Props

View Props

`accessible`

`accessibilityLabel`

`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

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

메서드

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

타입 정의

ImageCacheEnum
iOS

ImageLoadEvent

소스 객체

이미지 소스(ImageSource)