跳到主要内容
新架构实战课 实操 + 基建 + 原理全维度包揽,抢先掌握 React Native 新架构精髓 立即查看 >Version: 0.70

Image

用于显示多种不同类型图片的 React 组件,包括网络图片、静态资源、临时的本地图片、以及本地磁盘上的图片(如相册)等。

下面的例子分别演示了如何显示从本地缓存、网络甚至是以'data:'的 base64 uri 形式提供的图片。

请注意对于网络和 base64 数据的图片需要手动指定尺寸!

示例

你可以给图片添加style属性:

在 Android 上支持 GIF 和 WebP 格式图片

默认情况下 Android 是不支持 GIF 和 WebP 格式的。你需要在android/app/build.gradle文件中根据需要手动添加以下模块:

dependencies {
// 如果你需要支持Android4.0(API level 14)之前的版本
implementation 'com.facebook.fresco:animated-base-support:1.3.0'

// 如果你需要支持GIF动图
implementation 'com.facebook.fresco:animated-gif:2.5.0'

// 如果你需要支持WebP格式,包括WebP动图
implementation 'com.facebook.fresco:animated-webp:2.5.0'
implementation 'com.facebook.fresco:webpsupport:2.5.0'

// 如果只需要支持WebP格式而不需要动图
implementation 'com.facebook.fresco:webpsupport:2.5.0'
}

文档

Props

accessible

当此属性为 true 时,表示此图片是一个启用了无障碍功能的元素。

TypeDefault
boolfalse

accessibilityLabel

设置一段文字。当用户与图片交互时,读屏器(无障碍功能)会朗读你所设置的这段文字。

类型
string

blurRadius

blurRadius(模糊半径):为图片添加一个指定半径的模糊滤镜。

类型
number

提示: 在 iOS 上 blurRadius最好不要低于5


capInsets
iOS

当图片被缩放的时候,capInsets 指定的角上的尺寸会被固定而不进行缩放,而中间和边上其他的部分则会被拉伸。这在制作一些可变大小的圆角按钮、阴影、以及其它资源的时候非常有用(译注:这就是常说的九宫格或者.9 图。了解更多信息,可以参见苹果官方文档

Type
Rect

defaultSource

在读取图片时默认显示的图片。

Type
ImageSource

注意: 在 Android 的 debug 版本上本属性不会生效(但在 release 版本中会生效)。


fadeDuration
Android

渐入的动画持续时间。

TypeDefault
number300

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

Type
ImageSource (uri only), number

onError

当加载错误的时候调用此回调函数。

Type

| function({ nativeEvent: { error } }) => void


onLayout

当元素加载或者布局改变的时候调用。

Type
function(LayoutEvent) => void

onLoad

加载成功完成时调用此回调函数。

Example: onLoad={({nativeEvent: {source: {width, height}}}) => setImageRealSize({width, height})}

Type
({ nativeEvent: ImageLoadEvent }) => void

onLoadEnd

加载结束后,不论成功还是失败,调用此回调函数。

Type
function() => void

onLoadStart

加载开始时调用。

示例:onLoadStart={(e) => this.setState({loading: true})}

Type
function() => void

onPartialLoad
iOS

如果图片本身支持逐步加载,则逐步加载的过程中会调用此方法。“逐步加载”的具体定义与具体的标准和实现有关。

Type
function() => void

onProgress

下载进度的回调事件。

Type
function({ nativeEvent: { loaded, total } }) => void

progressiveRenderingEnabled
Android

When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeDefault
boolfalse

resizeMethod
Android

当图片实际尺寸和容器样式尺寸不一致时,决定以怎样的策略来调整图片的尺寸。默认为auto

  • auto: 使用启发式算法来在resizescale中自动决定。

  • resize: 在图片解码之前,使用软件算法对其在内存中的数据进行修改。当图片尺寸比容器尺寸大得多时,应该优先使用此选项。

  • scale: 对图片进行缩放。和resize相比,scale速度更快(一般有硬件加速),而且图片质量更优。在图片尺寸比容器尺寸小或者只是稍大一点时,应该优先使用此选项。

关于resizescale的详细说明请参考http://frescolib.org/docs/resizing.html

TypeDefault
enum('auto', 'resize', 'scale')'auto'

resizeMode

决定当组件尺寸和图片尺寸不成比例的时候如何调整图片的大小。默认值为cover

  • cover: 在保持图片宽高比的前提下缩放图片,直到宽度和高度都大于等于容器视图的尺寸(如果容器有 padding 内衬的话,则相应减去)。译注:这样图片完全覆盖甚至超出容器,容器中不留任何空白。

  • contain: 在保持图片宽高比的前提下缩放图片,直到宽度和高度都小于等于容器视图的尺寸(如果容器有 padding 内衬的话,则相应减去)。译注:这样图片完全被包裹在容器中,容器中可能留有空白。

  • stretch: 拉伸图片且不维持宽高比,直到宽高都刚好填满容器。

  • repeat: 重复平铺图片直到填满容器。图片会维持原始尺寸,但是当尺寸超过容器时会在保持宽高比的前提下缩放到能被容器包裹。

  • center: 居中不拉伸。

TypeDefault
enum('cover', 'contain', 'stretch', 'repeat', 'center')'cover'

source

图片源数据(远程 URL 地址或本地数据)。

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

目前原生支持的图片格式有pngjpgjpegbmpgifwebppsd (仅 iOS)。此外 iOS 还支持几种 RAW 格式。请参考 Apple 的官方文档来了解目前支持哪些相机型号的 raw 格式(对于 iOS 13 请访问 https://support.apple.com/en-us/HT210191)。

Type
ImageSource

style

Type
Image Style Props, Layout Props, Shadow Props, Transforms

testID

一个唯一的资源标识符,用来在自动测试脚本中标识这个元素。

类型
string

方法

abortPrefetch()
Android

Image.abortPrefetch(requestId);

中断预加载操作。

参数:

名称类型说明
requestId
Required
numberprefetch()返回的 id

getSize()

Image.getSize(uri, success, [failure]);

在显示图片前获取图片的宽高(以像素为单位)。如果图片地址不正确或下载失败,此方法也会失败。

要获取图片的尺寸,首先需要加载或下载图片(同时会被缓存起来)。这意味着理论上你可以用这个方法来预加载图片,虽然此方法并没有针对这一用法进行优化,而且将来可能会换一些实现方案使得并不需要完整下载图片即可获取尺寸。所以更好的预加载方案是使用下面那个专门的预加载方法。

此方法不能用于静态图片资源。

参数:

名称类型必需说明
uristring图片地址
successfunction成功的回调函数,返回图片宽高数据
failurefunction失败的回调函数

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

参数:

名称类型必需说明
uristring图片地址
headersobject请求的 headers
successfunctionThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

预加载一个远程图片(将其下载到本地磁盘缓存)。

参数:

名称类型必需说明
urlstring图片的远程地址

queryCache()

Image.queryCache(urls);

查询图片缓存状态。根据图片 URL 地址返回缓存状态,比如"disk"(缓存在磁盘文件中)或是"memory"(缓存在内存中)。

参数:

名称类型必需说明
urlsarray要查询缓存状态的图片 URL 数组。

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

参数:

名称类型说明
source
Required
ImageSource, number静态图片引用语法require('./image.jpg')所返回的资源 id 或是一个ImageSource.

ImageSource是一个对象,其结构为{ uri: '<http location || file path>' }

类型定义

ImageCacheEnum
iOS

Enum which can be used to set the cache handling or stategy for the potentially cached responses.

TypeDefault
enum('default', 'reload', 'force-cache', 'only-if-cached')'default'
  • default: Use the native platforms default strategy.
  • reload: The data for the URL will be loaded from the originating source. No existing cache data should be used to satisfy a URL load request.
  • force-cache: The existing cached data will be used to satisfy the request, regardless of its age or expiration date. If there is no existing data in the cache corresponding the request, the data is loaded from the originating source.
  • only-if-cached: The existing cache data will be used to satisfy a request, regardless of its age or expiration date. If there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the data from the originating source, and the load is considered to have failed.

ImageLoadEvent

Object returned in the onLoad callback.

NameTypeDescription
sourceobjectThe source object

Source Object

Properties:

NameTypeDescription
widthnumberThe width of loaded image.
heightnumberThe height of loaded image.
uristringA string representing the resource identifier for the image.

ImageSource

Type
object, array of objects, number

Properties (if passing as object or array of objects):

Name
TypeDescription
uristringA string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource.
widthnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
heightnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
scalenumberUsed to indicate the scale factor of the image. Defaults to 1.0 if unspecified, meaning that one image pixel equates to one display point / DIP.
bundle
iOS
stringThe iOS asset bundle which the image is included in. This will default to [NSBundle mainBundle] if not set.
methodstringThe HTTP Method to use. Defaults to 'GET' if not specified.
headersobjectAn object representing the HTTP headers to send along with the request for a remote image.
bodystringThe HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied.
cache
iOS
ImageCacheEnumDetermines how the requests handles potentially cached responses.

If passing a number:

  • number - opaque type returned by something like require('./image.jpg').