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。

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

`defaultSource`

在加载图像源时要显示的静态图像。

类型
ImageSource

注意： 在 Android 上，调试构建中会忽略 default source 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 属性。

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

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

`resizeMode`

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

cover：均匀缩放图像（保持图像的纵横比），以便
- 图像的两个维度（宽度和高度）都将等于或大于视图的相应维度（减去内边距）
- 缩放图像的至少一个维度将等于视图的相应维度（减去内边距）
contain：均匀缩放图像（保持图像的纵横比），以便图像的两个维度（宽度和高度）都将等于或小于视图的相应维度（减去内边距）。
stretch：独立缩放宽度和高度，这可能会更改 src 的纵横比。
repeat：重复图像以覆盖视图的帧。图像将保持其大小和纵横比，除非它大于视图，在这种情况下，它将被均匀缩小，以便包含在视图中。
center：将图像在两个维度上都居中于视图中。如果图像大于视图，则均匀缩小图像，使其包含在视图中。

类型	默认值
枚举(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

当 resizeMethod 设置为 resize 时，目标尺寸乘以该值。 scale 方法用于执行其余的调整大小。默认值 1.0 表示位图大小旨在适合目标尺寸。大于 1.0 的乘数将设置大于目标尺寸的调整大小选项，并且生成的位图将从硬件大小缩小。默认为 1.0。

此 prop 在目标尺寸非常小且源图像大得多时最有用。 resize 调整大小方法执行降采样，并且源图像大小和目标图像大小之间会丢失显著的图像质量，通常会导致图像模糊。通过使用乘数，解码后的图像略大于目标大小但小于源图像（如果源图像足够大）。这允许混叠伪影通过对乘法图像进行缩放操作来产生伪质量。

如果您的源图像尺寸为 200x200，目标尺寸为 24x24，则 resizeMultiplier 为 2.0 将告诉 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）。

请注意，仅当与 JavaScript 代码捆绑在一起时，iOS 才支持 webp 格式。

类型
ImageSource

`src`

一个字符串，表示图像的远程 URL。此 prop 优先于 source prop。

示例： src={'https://reactnative.net.cn/img/tiny_logo.png'}

类型
字符串

`srcSet`

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

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

此 prop 优先于 src 和 source props。

示例： srcSet={'https://reactnative.net.cn/img/tiny_logo.png 1x, https://reactnative.net.cn/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，该 promise 解析为一个布尔值。

参数

名称	类型	描述
url 必需	字符串	图像的远程位置。
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，数字	一个数字（由 `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	对象	source 对象

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​

Source 对象​

ImageSource​

示例