跳到主要内容

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 时，表示图像是可访问性元素。

类型默认值
boolfalse

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 上，默认源 prop 在 debug 构建中被忽略。

fadeDuration
Android
​

淡入动画持续时间，以毫秒为单位。

类型默认值
number300

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。

类型默认值
boolfalse

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

类型默认值
number1.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'}

类型
string

srcSet​

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

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

此 prop 优先于 src 和 source prop。

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

类型
string

style​

类型
Image Style Props, Layout Props, Shadow Props, Transforms

testID​

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

类型
string

tintColor​

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

类型
color

width​

图像组件的宽度。

类型
number

方法​

abortPrefetch()
Android
​

tsx
static abortPrefetch(requestId: number);

中止预取请求。

参数

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

getSize()​

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

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

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

参数

名称
类型描述
uri
必需
string图像的位置。

getSizeWithHeaders()​

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

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

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

参数

名称
类型描述
uri
必需
string图像的位置。
headers
必需
object请求的标头。

prefetch()​

tsx
await Image.prefetch(url);

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

参数

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

queryCache()​

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

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

参数

名称类型描述
urls
必需
array要检查缓存的图像 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 回调中返回的对象。

类型
object

属性

名称类型描述
sourceobjectsource object

Source Object​

属性

名称类型描述
widthnumber加载图像的宽度。
heightnumber加载图像的高度。
uristring表示图像的资源标识符的字符串。

ImageSource​

类型
object, array of objects, number

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

名称
类型描述
uristring表示图像的资源标识符的字符串，可以是 http 地址、本地文件路径或静态图像资源的名称。
widthnumber如果构建时已知，则可以指定，在这种情况下，该值将用于设置默认的 <Image/> 组件尺寸。
heightnumber如果构建时已知，则可以指定，在这种情况下，该值将用于设置默认的 <Image/> 组件尺寸。
scalenumber用于指示图像的缩放因子。如果未指定，则默认为 1.0，这意味着一个图像像素等于一个显示点 / DIP。
bundle
iOS
string图像包含在其中的 iOS 资源包。如果未设置，则默认为 [NSBundle mainBundle]。
methodstring要使用的 HTTP 方法。如果未指定，则默认为 'GET'。
headersobject一个对象，表示要随远程图像请求一起发送的 HTTP 标头。
bodystring要随请求一起发送的 HTTP body。这必须是有效的 UTF-8 字符串，并且将完全按指定发送，而无需应用额外的编码（例如 URL 转义或 base64）。
cache
iOS
ImageCacheEnum确定请求如何处理潜在的缓存响应。

如果传递数字

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