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.2.0'

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

  // For WebP support, without animations
  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

注意: Androidでは、default sourceプロパティはデバッグビルドでは無視されます。

`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 と比較して、scale は高速（通常はハードウェアアクセラレーション）で、より高品質な画像を生成します。画像がビューより小さい場合に使用すべきです。画像がビューよりわずかに大きい場合にも使用すべきです。
none: サンプリングは行われず、画像は完全な解像度で表示されます。Androidはメモリを過剰に消費する画像をレンダリングしようとすると実行時例外をスローするため、これは安全でないと考えられており、稀な状況でのみ使用すべきです。

resize と scale の詳細については、https://frescolib.org/docs/resizing を参照してください。

型	デフォルト
enum(`'auto'`, `'resize'`, `'scale'`, `'none'`)	`'auto'`

`resizeMode`

フレームが元の画像の寸法と一致しない場合に、画像をどのようにリサイズするかを決定します。デフォルトはcoverです。

cover: 画像のアスペクト比を維持したまま、均一にスケールします。
- 画像の幅と高さの両方の寸法が、ビューの対応する寸法（パディングを除く）以上になります。
- スケーリングされた画像の少なくとも1つの寸法が、ビューの対応する寸法（パディングを除く）と等しくなります。
contain: 画像のアスペクト比を維持したまま均一にスケールし、画像の幅と高さの両方の寸法がビューの対応する寸法（パディングを除く）以下になるようにします。
stretch: 幅と高さを独立してスケールします。これにより、元の画像のアスペクト比が変わる可能性があります。
repeat: 画像を繰り返してビューのフレームを覆います。画像はサイズとアスペクト比を維持しますが、ビューより大きい場合は、ビューに収まるように均一に縮小されます。
center: 画像を両次元に沿ってビューの中央に配置します。画像がビューより大きい場合は、ビューに収まるように均一に縮小します。

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

`resizeMultiplier`
Android

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

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

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

型	デフォルト
number	`1.0`

`source`

画像ソース（リモート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フォーマットは、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

メソッド

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

型	デフォルト
enum(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

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

ImageLoadEvent

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

型
object

プロパティ

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

Source オブジェクト

プロパティ

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

ImageSource

型
object, array of objects, number

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

名前	型	説明
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​

resizeMethod Android​

resizeMode​

resizeMultiplier Android​

source​

src​

srcSet​

style​

testID​

tintColor​

width​

メソッド​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

型定義​

ImageCacheEnumiOS​

ImageLoadEvent​

Source オブジェクト​

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`

`resizeMethod`
Android

`resizeMode`

`resizeMultiplier`
Android

`source`

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

メソッド

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

型定義

ImageCacheEnum
iOS

ImageLoadEvent

Source オブジェクト

ImageSource