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

注意

上面列出的版本可能未及时更新。请查看主仓库中的 packages/react-native/gradle/libs.versions.toml，以了解特定标签版本中使用的 fresco 版本。

参考

属性

视图属性

继承自 View 属性。

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

类型	默认
枚举 (`'anonymous'`, `'use-credentials'`)	`'anonymous'`

`defaultSource`

加载图片源时显示的静态图片。

类型
ImageSource

注意

在 Android 上，调试构建中会忽略 defaultSource 属性。

`fadeDuration`
Android

淡入动画持续时间（毫秒）。

类型	默认
数字	`300`

`height`

图片组件的高度。

类型
数字

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

类型	默认
布尔值	`false`

`referrerPolicy`

一个字符串，指示在获取资源时使用的 referrer。在图片请求中设置 Referrer-Policy 标头的值。它与 HTML 中的 referrerpolicy 属性类似。

类型	默认
枚举 (`'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。

类型	默认
枚举 (`'auto'`, `'resize'`, `'scale'`, `'none'`)	`'auto'`

`resizeMode`

确定当框架与原始图片尺寸不匹配时如何调整图片大小。默认为 cover。

cover：统一缩放图片（保持图片的宽高比），使
- 图片的两个维度（宽度和高度）将等于或大于视图的相应维度（减去内边距）
- 缩放图片至少一个维度将等于视图的相应维度（减去内边距）
contain：统一缩放图片（保持图片的宽高比），使图片的两个维度（宽度和高度）将等于或小于视图的相应维度（减去内边距）。
stretch：独立缩放宽度和高度，这可能会改变源的宽高比。
repeat：重复图片以覆盖视图的框架。图片将保持其大小和宽高比，除非它大于视图，在这种情况下，它将统一缩小以使其包含在视图中。
center：将图片沿两个维度居中在视图中。如果图片大于视图，则将其统一缩小以使其包含在视图中。

类型	默认
枚举 (`'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。生成的图片由系统缩小。

类型	默认
数字	`1.0`

`source`

图片源（可以是远程 URL 或本地文件资源）。

此属性还可以包含多个远程 URL，它们与宽度、高度以及可能与 scale/其他 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.net.cn/img/tiny_logo.png'}

类型
字符串

`srcSet`

一个字符串，表示逗号分隔的可能候选图片源列表。每个图片源都包含图片的 URL 和像素密度描述符。如果未指定描述符，则默认为 1x 描述符。

如果 srcSet 不包含 1x 描述符，则 src 中的值将用作具有 1x 描述符的图片源（如果提供）。

此属性优先于 src 和 source 属性。

示例： srcSet={'https://reactnative.net.cn/img/tiny_logo.png 1x, https://reactnative.net.cn/img/header_logo.svg 2x'}

类型
字符串

`style`

类型
图片样式属性、布局属性、阴影属性、变换

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

参数

姓名	类型	描述
网址必需	字符串	图片的远程位置。
callback	函数 Android	将使用 `requestId` 调用的函数。

`queryCache()`

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

执行缓存查询。返回一个 Promise，该 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，number	一个数字（由 `require('./foo.png')` 返回的不透明类型）或一个 ImageSource。

类型定义

ImageCacheEnum
iOS

可用于设置潜在缓存响应的缓存处理或策略的枚举。

类型	默认
枚举 (`'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 正文。这必须是有效的 UTF-8 字符串，并且将按指定原样发送，不进行额外编码（例如，URL 转义或 base64）。
cache iOS	ImageCacheEnum	确定请求如何处理潜在的缓存响应。

如果传递数字

number - 由 require('./image.jpg') 之类的东西返回的不透明类型。

示例​

Android 上的 GIF 和 WebP 支持​

参考

属性​

视图属性​

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​

方法​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

类型定义​

ImageCacheEnumiOS​

ImageLoadEvent​

源对象​

ImageSource​

示例