Image

一个 React 组件，用于显示不同类型的图像，包括网络图像、静态资源、临时本地图像以及来自本地磁盘的图像，例如相机胶卷。

此示例显示了从本地存储以及从网络获取和显示图像，甚至从 'data:' uri 方案中提供的数据获取和显示图像。

请注意，对于网络和数据图像，您需要手动指定图像的尺寸！

示例

您还可以向图像添加 style

Android 上的 GIF 和 WebP 支持

在构建自己的原生代码时，Android 默认不支持 GIF 和 WebP。

您需要根据应用程序的需要在 android/app/build.gradle 中添加一些可选模块。

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

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

  // For WebP support, without animations
  implementation 'com.facebook.fresco:webpsupport:3.1.3'
}

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

参考

属性

View 属性

继承 View 属性。

`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 上，defaultSource 属性在调试版本中会被忽略。

`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：均匀缩放图像（保持图像的纵横比），以便
- 图像的两个维度（宽度和高度）都将等于或大于视图的相应维度（减去填充）
- 缩放图像的至少一个维度将等于视图的相应维度（减去填充）
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 属性来控制网络请求如何与本地缓存交互。（有关更多信息，请参阅图像缓存控制（仅限 iOS））。

当前支持的格式包括 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 的字符串。此属性优先于 source 属性。

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

类型
string

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

类型
string

`style`

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

`testID`

此元素的唯一标识符，用于 UI 自动化测试脚本。

类型
string

`tintColor`

将所有非透明像素的颜色更改为 tintColor。

类型
颜色

`width`

图像组件的宽度。

类型
number

方法

`abortPrefetch()`
Android

static abortPrefetch(requestId: number);

中止预取请求。

参数

名称	类型	描述
requestId 必需	number	`prefetch()` 返回的请求 ID。

`getSize()`

static getSize(
  uri: string,
  success: (width: number, height: number) => void,
  failure?: (error: any) => void,
): any;

在显示图像之前检索图像的宽度和高度（以像素为单位）。如果找不到图像或下载失败，则此方法可能会失败。

为了检索图像尺寸，可能需要先加载或下载图像，然后将其缓存。这意味着原则上您可以使用此方法预加载图像，但是它没有针对此目的进行优化，并且将来可能会以不完全加载/下载图像数据的方式实现。将提供一个单独的 API 作为预加载图像的正确且受支持的方式。

参数

名称	类型	描述
uri 必需	string	图像的位置。
success 必需	函数	如果成功找到图像并检索到宽度和高度，则将调用此函数。
failure	函数	如果发生错误（例如无法检索图像），则将调用此函数。

`getSizeWithHeaders()`

static getSizeWithHeaders(
  uri: string,
  headers: {[index: string]: string},
  success: (width: number, height: number) => void,
  failure?: (error: any) => void,
): any;

在显示图像之前检索图像的宽度和高度（以像素为单位），并能够为请求提供标头。如果找不到图像或下载失败，则此方法可能会失败。它也不适用于静态图像资源。

参数

名称	类型	描述
uri 必需	string	图像的位置。
headers 必需	对象	请求的标头。
success 必需	函数	如果成功找到图像并检索到宽度和高度，则将调用此函数。
failure	函数	如果发生错误（例如无法检索图像），则将调用此函数。

`prefetch()`

await Image.prefetch(url);

通过将其下载到磁盘缓存中，预取远程图像以供以后使用。返回一个 promise，该 promise 解析为一个布尔值。

参数

名称	类型	描述
url 必需	string	图像的远程位置。
callback	函数 Android	将使用 `requestId` 调用的函数。

`queryCache()`

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

执行缓存查询。返回一个 promise，该 promise 解析为从 URL 到缓存状态的映射，例如“disk”、“memory”或“disk/memory”。如果请求的 URL 不在映射中，则表示它不在缓存中。

参数

名称	类型	描述
urls 必需	数组	要检查其缓存的图像 URL 列表。

`resolveAssetSource()`

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	对象	源对象

源对象

属性

名称	类型	描述
width	number	加载图像的宽度。
height	number	加载图像的高度。
uri	string	表示图像资源标识符的字符串。

ImageSource

类型
对象、对象数组、数字

属性（如果作为对象或对象数组传递）

名称	类型	描述
uri	string	表示图像资源标识符的字符串，可以是 http 地址、本地文件路径或静态图像资源的名称。
width	number	如果在构建时已知，则可以指定它，在这种情况下，该值将用于设置默认的 `<Image/>` 组件尺寸。
height	number	如果在构建时已知，则可以指定它，在这种情况下，该值将用于设置默认的 `<Image/>` 组件尺寸。
scale	number	用于指示图像的缩放因子。如果未指定，则默认为 `1.0`，这意味着一个图像像素相当于一个显示点/DIP。
bundle iOS	string	包含图像的 iOS 资产包。如果未设置，则默认为 `[NSBundle mainBundle]`。
method	string	要使用的 HTTP 方法。如果未指定，则默认为 `'GET'`。
headers	对象	表示要与远程图像请求一起发送的 HTTP 标头的对象。
body	string	要与请求一起发送的 HTTP 正文。这必须是一个有效的 UTF-8 字符串，并且将按原样发送，不会应用任何额外的编码（例如 URL 编码或 base64）。
cache iOS	ImageCacheEnum	确定请求如何处理潜在的缓存响应。

如果传递数字

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

示例​

Android 上的 GIF 和 WebP 支持​

参考

属性​

View 属性​

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​

示例