Image

ネットワーク画像、静的リソース、一時的なローカル画像、カメラロールなどのローカルディスクからの画像を含む、さまざまな種類の画像を表示するためのReactコンポーネント。

この例では、ローカルストレージからの画像、ネットワークからの画像、さらには'data:' URIスキームで提供されたデータをフェッチして表示する方法を示しています。

注

ネットワーク画像およびデータ画像の場合、画像の寸法を手動で指定する必要があります！

例

画像にstyleを追加することもできます

AndroidでのGIFとWebPのサポート

独自のネイティブコードを構築する場合、AndroidではGIFとWebPはデフォルトでサポートされていません。

アプリのニーズに応じて、android/app/build.gradleにいくつかのオプションモジュールを追加する必要があります。

groovy
dependencies {
  // If your app supports Android versions before Ice Cream Sandwich (API level 14)
  implementation 'com.facebook.fresco:animated-base-support:1.3.0'

  // For animated GIF support
  implementation 'com.facebook.fresco:animated-gif:3.6.0'

  // For WebP support, including animated WebP
  implementation 'com.facebook.fresco:animated-webp:3.6.0'
  implementation 'com.facebook.fresco:webpsupport:3.6.0'

  // For WebP support, without animations
  implementation 'com.facebook.fresco:webpsupport:3.6.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

注

Androidでは、デバッグビルドでデフォルトのソースプロップは無視されます。

`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'`

`ref`

マウント時に要素ノードが割り当てられる ref セッター。

`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: 画像を均一に拡大縮小（画像の縦横比を維持）して、
- 画像の両方の寸法（幅と高さ）が、ビューの対応する寸法（パディングを除く）以上になるようにします。
- 拡大縮小された画像の少なくとも1つの寸法が、ビューの対応する寸法（パディングを除く）と等しくなるようにします。
contain: 画像を均一に拡大縮小（画像の縦横比を維持）して、画像のすべての寸法（幅と高さ）が、ビューの対応する寸法（パディングを除く）以下になるようにします。
stretch: 幅と高さを独立して拡大縮小します。これにより、srcの縦横比が変わる可能性があります。
repeat: 画像を繰り返してビューのフレームをカバーします。画像はビューよりも大きい場合を除き、サイズと縦横比を維持します。その場合、ビュー内に収まるように均一に縮小されます。
center: 画像をビューの中央に両方の寸法で配置します。画像がビューよりも大きい場合は、ビュー内に収まるように均一に縮小します。

型	デフォルト
enum(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

resizeMethodがresizeに設定されている場合、ターゲットの寸法はこの値で乗算されます。残りのサイズ変更にはscaleメソッドが使用されます。デフォルトの1.0は、ビットマップサイズがターゲットの寸法に合うように設計されていることを意味します。1.0より大きい乗数は、サイズ変更オプションをターゲットの寸法よりも大きく設定し、結果のビットマップはハードウェアサイズから縮小されます。デフォルトは1.0です。

このプロップは、ターゲットの寸法が非常に小さく、ソース画像が大幅に大きい場合に最も役立ちます。resizeサイズ変更メソッドはダウンサンプリングを実行し、ソース画像とターゲット画像サイズの間でかなりの画質が失われ、多くの場合、画像がぼやけてしまいます。乗数を使用すると、デコードされた画像はターゲットサイズよりもわずかに大きくなりますが、ソース画像よりも小さくなります（ソース画像が十分に大きい場合）。これにより、アンチエイリアシングアーティファクトは、乗算された画像の拡大縮小操作を通じて偽の品質を生成できます。

200x200のソース画像があり、ターゲットの寸法が24x24の場合、2.0のresizeMultiplierはFrescoに画像を48x48にダウンサンプルするように指示します。Frescoは最も近い2のべき乗（つまり50x50）を選択し、そのサイズのビットマップに画像をデコードします。乗数がない場合、最も近い2のべき乗は25x25になります。結果の画像はシステムによって縮小されます。

型	デフォルト
number	`1.0`

`source`

画像ソース（リモートURLまたはローカルファイルリソース）。

このプロップには、幅と高さ、およびスケール/その他のURI引数を指定した複数のリモートURLを含めることもできます。ネイティブ側は、画像のコンテナの測定サイズに基づいて表示する最適なuriを選択します。cacheプロパティを追加して、ネットワークリクエストとローカルキャッシュの相互作用を制御できます。(詳細については、画像のキャッシュ制御を参照してください)。

現在サポートされている形式は、png、jpg、jpeg、bmp、gif、webp、psd（iOSのみ）です。さらに、iOSはいくつかのRAW画像形式をサポートしています。現在サポートされているカメラモデルのリストについては、Appleのドキュメントを参照してください（iOS 12の場合、https://support.apple.com/en-ca/HT208967を参照）。

webp形式は、JavaScriptコードとバンドルされている場合にのみiOSでサポートされることに注意してください。

型
ImageSource

`src`

画像のリモートURLを表す文字列。このプロップはsourceプロップよりも優先されます。

例: src={'https://reactnative.dokyumento.jp/img/tiny_logo.png'}

型
string

`srcSet`

可能な候補画像ソースのコンマ区切りリストを表す文字列。各画像ソースには、画像のURLとピクセル密度記述子が含まれます。記述子が指定されていない場合、デフォルトは1xの記述子になります。

srcSetに1x記述子が含まれていない場合、srcの値は1x記述子を持つ画像ソースとして使用されます（提供されている場合）。

このプロップは、srcとsourceの両方のプロップよりも優先されます。

例: srcSet={'https://reactnative.dokyumento.jp/img/tiny_logo.png 1x, https://reactnative.dokyumento.jp/img/header_logo.svg 2x'}

型
string

`style`

型
画像スタイルプロップ、レイアウトプロップ、シャドウプロップ、トランスフォーム

`testID`

UI自動化テストスクリプトで使用される、この要素の一意の識別子。

型
string

`tintColor`

すべての非透明ピクセルの色をtintColorに変更します。

型
color

`width`

画像コンポーネントの幅。

型
number

Methods

`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}>;

リクエストのヘッダーを提供する機能とともに、画像を表示する前にその幅と高さ（ピクセル単位）を取得します。画像が見つからない、またはダウンロードに失敗した場合、このメソッドは失敗する可能性があります。また、静的画像リソースでは機能しません。

パラメータ

名前	型	説明
uri 必須	string	画像の場所。
headers 必須	object	リクエストのヘッダー。

`prefetch()`

tsx
await Image.prefetch(url);

ディスクキャッシュにダウンロードすることで、後で使用するためにリモート画像をプリフェッチします。真偽値に解決される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がマッピングにない場合、キャッシュにないことを意味します。

パラメータ

名前	型	説明
urls 必須	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(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

default: ネイティブプラットフォームのデフォルト戦略を使用します。
reload: URLのデータは元のソースから読み込まれます。URL読み込みリクエストを満たすために既存のキャッシュデータを使用しないでください。
force-cache: 既存のキャッシュデータは、その古さや有効期限に関係なく、リクエストを満たすために使用されます。キャッシュにリクエストに対応する既存のデータがない場合、データは元のソースから読み込まれます。
only-if-cached: 既存のキャッシュデータは、その古さや有効期限に関係なく、リクエストを満たすために使用されます。URL読み込みリクエストに対応するキャッシュに既存のデータがない場合、元のソースからデータを読み込もうとせず、読み込みは失敗したとみなされます。

ImageLoadEvent

onLoadコールバックで返されるオブジェクト。

型
object

プロパティ

名前	型	説明
source	object	ソースオブジェクト

ソースオブジェクト

プロパティ

名前	型	説明
width	number	読み込まれた画像の幅。
height	number	読み込まれた画像の高さ。
uri	string	画像のリソース識別子を表す文字列。

ImageSource

型
オブジェクト、オブジェクトの配列、数値

プロパティ（オブジェクトまたはオブジェクトの配列として渡す場合）

名前	型	説明
uri	string	画像のリソース識別子を表す文字列。HTTPアドレス、ローカルファイルパス、または静的画像リソースの名前のいずれかです。
width	number	ビルド時にわかっている場合に指定でき、その場合、その値はデフォルトの`<Image/>`コンポーネントの寸法を設定するために使用されます。
height	number	ビルド時にわかっている場合に指定でき、その場合、その値はデフォルトの`<Image/>`コンポーネントの寸法を設定するために使用されます。
scale	number	画像のスケールファクターを示すために使用されます。指定されていない場合、デフォルトは`1.0`であり、これは1つの画像ピクセルが1つの表示ポイント/DIPに等しいことを意味します。
bundle iOS	string	画像が含まれているiOSアセットバンドル。設定されていない場合、デフォルトは`[NSBundle mainBundle]`になります。
method	string	使用するHTTPメソッド。指定されていない場合、デフォルトは`'GET'`です。
headers	object	リモート画像の要求とともに送信するHTTPヘッダーを表すオブジェクト。
body	string	リクエストとともに送信するHTTPボディ。これは有効なUTF-8文字列である必要があり、追加のエンコーディング（例：URLエスケープやbase64）は適用されず、指定されたとおりに正確に送信されます。
cache iOS	ImageCacheEnum	リクエストがキャッシュされた可能性のある応答をどのように処理するかを決定します。

数値を渡す場合

number - require('./image.jpg')のようなものによって返される不透明な型。

例​

AndroidでのGIFとWebPのサポート​

リファレンス

Props​

View Props​

accessible​

accessibilityLabel​

alt​

blurRadius​

capInsets iOS​

crossOrigin​

defaultSource​

fadeDuration Android​

height​

loadingIndicatorSource​

onError​

onLayout​

onLoad​

onLoadEnd​

onLoadStart​

onPartialLoad iOS​

onProgress​

progressiveRenderingEnabled Android​

referrerPolicy​

ref​

resizeMethod Android​

resizeMode​

resizeMultiplier Android​

source​

src​

srcSet​

style​

testID​

tintColor​

width​

Methods​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

型定義​

ImageCacheEnumiOS​

ImageLoadEvent​

ソースオブジェクト​

ImageSource​

例

AndroidでのGIFとWebPのサポート

Props

View Props

`accessible`

`accessibilityLabel`

`alt`

`blurRadius`

`capInsets`
iOS

`crossOrigin`

`defaultSource`

`fadeDuration`
Android

`height`

`loadingIndicatorSource`

`onError`

`onLayout`

`onLoad`

`onLoadEnd`

`onLoadStart`

`onPartialLoad`
iOS

`onProgress`

`progressiveRenderingEnabled`
Android

`referrerPolicy`

`ref`

`resizeMethod`
Android

`resizeMode`

`resizeMultiplier`
Android

`source`

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

Methods

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

型定義

ImageCacheEnum
iOS

ImageLoadEvent

ソースオブジェクト

ImageSource