跳到主要内容

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 时，表示该图片是一个无障碍元素。

类型默认值
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 上，调试构建会忽略 default source 属性。

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：独立缩放宽度和高度，这可能会改变源的宽高比。

  • 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。最终的图片由系统进行缩放。

类型默认值
number1.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）。

请注意，仅当与 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​

类型
Image 样式属性, 布局属性, 阴影属性, 变换

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。

参数

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

queryCache()​

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

执行缓存查询。返回一个 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

属性

名称类型描述
sourceobject该源对象

源对象​

属性

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

ImageSource​

类型
object, 对象数组, number

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

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

如果传递数字

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