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 版本。

参考

属性

View 属性

继承自 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`。

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

`defaultSource`

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

类型
ImageSource

注意：在 Android 上，调试构建时会忽略 default source 属性。

`fadeDuration`
Android

淡入动画时长，单位为毫秒。

类型	默认
数字	`300`

`height`

图片组件的高度。

类型
数字

`loadingIndicatorSource`

与 `source` 类似，此属性表示用于渲染图像加载指示器的资源。加载指示器在图像准备好显示（通常在图像下载完成后）之前一直显示。

类型
ImageSource (`uri` only), 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` 属性类似。

类型	默认
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。结果图像由系统缩小。

类型	默认
数字	`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.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

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

类型	默认
enum(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

`default`：使用原生平台的默认策略。
`reload`：URL 的数据将从原始源加载。不应使用任何现有缓存数据来满足 URL 加载请求。
`force-cache`：现有缓存数据将用于满足请求，无论其年龄或过期日期如何。如果缓存中没有与请求对应的现有数据，则数据将从原始源加载。
`only-if-cached`：现有缓存数据将用于满足请求，无论其年龄或过期日期如何。如果缓存中没有与 URL 加载请求对应的现有数据，则不尝试从原始源加载数据，并且加载被视为失败。

ImageLoadEvent

`onLoad` 回调中返回的对象。

类型
对象

属性

姓名	类型	描述
source	对象	source 对象

Source Object

属性

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

ImageSource

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

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

姓名	类型	描述
uri	字符串	表示图像资源标识符的字符串，可以是 http 地址、本地文件路径或静态图像资源的名称。
width	数字	如果在构建时已知，则可以指定此属性，其值将用于设置默认的 `` 组件尺寸。
height	数字	如果在构建时已知，则可以指定此属性，其值将用于设置默认的 `` 组件尺寸。
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 支持​

参考

属性​

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​

Source Object​

ImageSource​

示例