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

注意：上面列出的版本可能未及時更新。請查看主要儲存庫中的 packages/react-native/gradle/libs.versions.toml，以查看特定標籤版本中使用的 Fresco 版本。

參考

Props

View Props

繼承 View Props。

`accessible`

當為 true 時，表示圖片是可訪問性元素。

類型	預設值
布林值	`false`

`accessibilityLabel`

當使用者與圖片互動時，螢幕閱讀器會讀取的文字。

類型
字串

`alt`

一個字串，定義圖片的替代文字描述，當使用者與圖片互動時，螢幕閱讀器會讀取此描述。使用此屬性將自動將此元素標記為可訪問。

類型
字串

`blurRadius`

blurRadius：新增至圖片的模糊濾鏡的模糊半徑。

類型
數字

提示：在 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 上，預設來源 prop 在偵錯版本中會被忽略。

`fadeDuration`
Android

淡入動畫持續時間，以毫秒為單位。

類型	預設值
數字	`300`

`height`

圖片組件的高度。

類型
數字

`loadingIndicatorSource`

與 source 類似，此屬性表示用於呈現圖片載入指示器的資源。載入指示器會顯示直到圖片準備好顯示為止，通常是在圖片下載之後。

類型
ImageSource (僅限 `uri`)、數字

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

類型	預設值
布林值	`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：獨立縮放寬度和高度，這可能會變更 src 的縱橫比。
repeat：重複圖片以覆蓋檢視的影格。圖片將保持其大小和縱橫比，除非它大於檢視，在這種情況下，它將均勻縮小，以便包含在檢視中。
center：將圖片在兩個尺寸上都置於檢視的中心。如果圖片大於檢視，則均勻縮小它，以便包含在檢視中。

類型	預設值
enum(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

當 resizeMethod 設定為 resize 時，目的地尺寸會乘以這個值。scale 方法用於執行剩餘的調整大小。預設值 1.0 表示點陣圖大小旨在符合目的地尺寸。大於 1.0 的乘數會將調整大小選項設定為大於目的地尺寸，且產生的點陣圖將從硬體大小縮小。預設值為 1.0。

在目的地尺寸非常小且來源圖片明顯較大的情況下，此 prop 最有用。resize 調整大小方法會執行降採樣，且來源和目的地圖片大小之間會損失顯著的圖片品質，通常會導致圖片模糊。透過使用乘數，解碼後的圖片會略大於目標大小，但小於來源圖片（如果來源圖片夠大）。這允許混疊偽影透過對乘法圖片進行縮放操作來產生虛假的品質。

如果您有一個尺寸為 200x200 的來源圖片和 24x24 的目的地尺寸，則 2.0 的 resizeMultiplier 將告訴 Fresco 將圖片降採樣至 48x48。Fresco 會選擇最接近的 2 的冪（因此為 50x50），並將圖片解碼為該大小的點陣圖。如果沒有乘數，最接近的 2 的冪將為 25x25。產生的圖片會由系統縮小。

類型	預設值
數字	`1.0`

`source`

圖片來源（遠端 URL 或本機檔案資源）。

此 prop 也可以包含多個遠端 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。此 prop 的優先順序高於 source prop。

範例： src={'https://reactnative.dev.org.tw/img/tiny_logo.png'}

類型
字串

`srcSet`

一個字串，表示以逗號分隔的可能候選圖片來源清單。每個圖片來源都包含圖片的 URL 和像素密度描述符。如果未指定描述符，則預設為 1x 的描述符。

如果 srcSet 未包含 1x 描述符，則 src 中的值會用作具有 1x 描述符的圖片來源（如果已提供）。

此 prop 的優先順序高於 src 和 source prop。

範例： srcSet={'https://reactnative.dev.org.tw/img/tiny_logo.png 1x, https://reactnative.dev.org.tw/img/header_logo.svg 2x'}

類型
字串

`style`

類型
圖片樣式 Props、版面配置 Props、陰影 Props、變換

`testID`

此元素的唯一識別碼，用於 UI 自動化測試腳本中。

類型
字串

`tintColor`

將所有非透明像素的顏色變更為 tintColor。

類型
顏色

`width`

圖片組件的寬度。

類型
數字

方法

`abortPrefetch()`
Android

tsx
static abortPrefetch(requestId: number);

中止預先提取請求。

參數

名稱	類型	描述
requestId 必要	數字	由 `prefetch()` 傳回的請求 ID。

`getSize()`

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

在顯示圖片之前，先擷取圖片的寬度和高度（以像素為單位）。如果找不到圖片或下載失敗，此方法可能會失敗。

為了擷取圖片尺寸，可能需要先載入或下載圖片，然後將其快取。這表示原則上您可以使用此方法來預先載入圖片，但它並未針對該目的進行最佳化，而且未來可能會以不會完全載入/下載圖片資料的方式實作。預先載入圖片的正確且受支援的方式將作為個別 API 提供。

參數

名稱	類型	描述
uri 必要	字串	圖片的位置。

`getSizeWithHeaders()`

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

在顯示圖片之前，先擷取圖片的寬度和高度（以像素為單位），並能夠為請求提供標頭。如果找不到圖片或下載失敗，此方法可能會失敗。它也不適用於靜態圖片資源。

參數

名稱	類型	描述
uri 必要	字串	圖片的位置。
headers 必要	物件	請求的標頭。

`prefetch()`

tsx
await Image.prefetch(url);

預先提取遠端圖片以供稍後使用，方法是將其下載到磁碟快取。傳回一個 Promise，解析為布林值。

參數

名稱	類型	描述
url 必要	字串	圖片的遠端位置。
callback	函式 Android	將使用 `requestId` 呼叫的函式。

`queryCache()`

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

執行快取查詢。傳回一個 Promise，解析為從 URL 到快取狀態的對應，例如「disk」、「memory」或「disk/memory」。如果請求的 URL 不在對應中，則表示它不在快取中。

參數

名稱	類型	描述
urls 必要	陣列	要檢查快取的圖片 URL 清單。

`resolveAssetSource()`

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

將資產參考解析為具有屬性 uri、scale、width 和 height 的物件。

參數

名稱	類型	描述
source 必要	ImageSource、數字	數字（由 `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 回呼中傳回的物件。

類型
物件

屬性

名稱	類型	描述
source	物件	來源物件

來源物件

屬性

名稱	類型	描述
width	數字	載入圖片的寬度。
height	數字	載入圖片的高度。
uri	字串	表示圖片資源識別碼的字串。

ImageSource

類型
物件、物件陣列、數字

屬性（如果作為物件或物件陣列傳遞）

名稱	類型	描述
uri	字串	表示圖片資源識別碼的字串，可以是 http 位址、本機檔案路徑或靜態圖片資源的名稱。
width	數字	如果建置時已知，則可以指定，在這種情況下，該值將用於設定預設的 `<Image/>` 組件尺寸。
height	數字	如果建置時已知，則可以指定，在這種情況下，該值將用於設定預設的 `<Image/>` 組件尺寸。
scale	數字	用於指示圖片的比例因子。如果未指定，則預設為 `1.0`，表示一個圖片像素等於一個顯示點/DIP。
bundle iOS	字串	圖片包含在其中的 iOS 資產包。如果未設定，則預設為 `[NSBundle mainBundle]`。
method	字串	要使用的 HTTP 方法。如果未指定，則預設為 `'GET'`。
headers	物件	表示要與遠端圖片請求一起傳送的 HTTP 標頭的物件。
body	字串	要與請求一起傳送的 HTTP body。這必須是有效的 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​

來源物件​

ImageSource​

範例