第51章 React Native Image 组件详解

版本：0.77 Image 用于显示各类图片的 React 组件，支持网络图片、静态资源、临时本地图片，以及来自本地磁盘（如相册）的图片。 下面的示例演示了如何获取并显示本地存储的图片、网络图片，甚至通过 'data:' uri 格式提供的图片。 注意：网络图片和 data 图片需要手动指定图片的尺寸！ 示例​ 你也可以为图片添加样式： Android 上的 GIF 和 WebP 支持​ 自己编译原生代码时，Android 默认不支持 GIF 和 WebP。你需要根据应用需求，在 android/app/build.gradle 中添加一些可选模块。 Groovy dependencies {
// 如果你的应用需要支持 Android 4.0（API level 14）之前的版本
implementation 'com.facebook.fresco:animated-base-support:1.3.0'

// 动画 GIF 支持
implementation 'com.facebook.fresco:animated-gif:3.4.0'

// WebP 支持，包括动画 WebP
implementation 'com.facebook.fresco:animated-webp:3.4.0'
implementation 'com.facebook.fresco:webpsupport:3.4.0'

// WebP 支持，不含动画
implementation 'com.facebook.fresco:webpsupport:3.4.0'
}
注意：上面列出的版本可能不会及时更新。如需查看某个具体 tag 版本所使用的 fresco 版本，请查看主仓库中的 packages/react-native/gradle/libs.versions.toml。 参考 Props View Props 继承 View Props。 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 上，debug 构建会忽略 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 字符串，会在图片请求中设置 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 的倍数会让 resize 的尺寸大于目标尺寸，最终的位图再由硬件按比例缩小。默认为 1.0。 此属性最适用于目标尺寸很小而源图片明显更大的情况。resize 方式会进行降采样，当源图片与目标尺寸差距过大时会损失大量画质，导致图片模糊。使用倍数后，解码出的图片会略大于目标尺寸但小于源图片（前提是源图片足够大），从而通过缩放操作借助混叠伪影产生近似的高画质。 例如源图片尺寸为 200x200，目标尺寸为 24x24，设置 resizeMultiplier 为 2.0 后，Fresco 会将图片降采样到 48x48。Fresco 会选取最接近的 2 的幂（即 50x50）并解码为该尺寸的位图。如果不使用倍数，最接近的 2 的幂则是 25x25，最终图片会被系统进一步缩小。 类型：number，默认值：1.0 source 图片源（远程 URL 或本地文件资源）。 此属性也可以包含多个远程 URL，同时指定各自的宽高，还可以带 scale 及其他 URI 参数。原生端会根据图片容器的实测尺寸选择最合适的 uri 进行显示。可以添加 cache 属性来控制网络请求与本地缓存的交互方式（更多信息见图片缓存控制）。 目前支持的格式有 png、jpg、jpeg、bmp、gif、webp、psd（仅 iOS）。此外 iOS 还支持几种 RAW 图片格式，当前支持的相机型号列表请参考 Apple 文档（iOS 12 见 https://support.apple.com/en-ca/HT208967）。 注意：iOS 上仅当 webp 与 JavaScript 代码一起打包时才支持该格式。 类型：ImageSource src 表示图片远程 URL 的字符串。此属性优先于 source 属性。 示例：src={'https://reactnative.dev/img/tiny_logo.png'} 类型：string srcSet 表示候选图片源列表的字符串，以逗号分隔。每个图片源包含一个图片 URL 和一个像素密度描述符；未指定描述符时默认为 1x。 如果 srcSet 不包含 1x 描述符，则 src 中的值会作为带 1x 描述符的图片源使用（如果提供了 src）。 此属性优先于 src 和 source 属性。 示例：srcSet={'https://reactnative.dev/img/tiny_logo.png 1x, https://reactnative.dev/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 React TSX：static abortPrefetch(requestId: number);
取消预取请求。 参数： NameTypeDescriptionrequestId RequirednumberRequest id as returned by prefetch(). getSize()​ React TSXstatic getSize(uri: string): Promise<{width: number, height: number}>;
在显示图片之前获取其宽度和高度（单位为像素）。如果图片找不到或下载失败，此方法可能会失败。 为了获取图片尺寸，可能需要先加载或下载图片，之后会将其缓存。这意味着原则上你可以用这个方法来预加载图片，但它并没有针对这个用途做优化，未来实现方式也可能改为不完整加载/下载图片数据。官方会提供专门的 API 来支持图片预加载。 参数： NameTypeDescriptionuri Requiredstring图片的位置。 getSizeWithHeaders()​ React TSXstatic getSizeWithHeaders(
uri: string,
headers: {[index: string]: string}
): Promise<{width: number, height: number}>;
在显示图片之前获取其宽度和高度（单位为像素），并支持为请求指定 headers。如果图片找不到或下载失败，此方法可能会失败。它也不适用于静态图片资源。 为了获取图片尺寸，可能需要先加载或下载图片，之后会将其缓存。这意味着原则上你可以用这个方法来预加载图片，但它并没有针对这个用途做优化，未来实现方式也可能改为不完整加载/下载图片数据。官方会提供专门的 API 来支持图片预加载。 参数： NameTypeDescriptionuri Requiredstring图片的位置。headers Requiredobject请求的 headers。 prefetch()​ React TSXawait Image.prefetch(url);
预取远程图片，将其下载到磁盘缓存以备后用。返回一个 Promise，其结果为布尔值。 参数： NameTypeDescriptionurl Requiredstring远程图片地址。callbackfunction Android回调函数，会收到 requestId。 queryCache()​ React TSXstatic queryCache(
urls: string[],
): Promise>;
查询缓存状态。返回一个 Promise，解析结果是从 URL 到缓存状态的映射，状态值如 "disk"、"memory" 或 "disk/memory"。如果请求的 URL 不在映射中，说明该图片不在缓存里。 参数： 名称类型说明urls Requiredarray需要检查缓存的图片 URL 列表。 resolveAssetSource()​ React TSXstatic 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：无论数据是否过期，都使用已有的缓存数据来响应请求。如果缓存中没有与请求对应的数据，则不会尝试从原始来源加载，加载视为失败。 ImageLoadEvent​ 在 onLoad 回调中返回的对象。 类型object 属性： 名称类型说明sourceobject来源对象 Source Object​ 属性： 名称类型说明widthnumber已加载图片的宽度。heightnumber已加载图片的高度。uristring表示图片资源标识符的字符串。 ImageSource​ 类型object、对象数组、number 属性（当传入对象或对象数组时）： 名称类型说明uristring表示图片资源标识符的字符串，可以是 http 地址、本地文件路径或静态图片资源的名称。widthnumber如果构建时已知，可以指定此值，它将用于设置 组件的默认尺寸。heightnumber如果构建时已知，可以指定此值，它将用于设置 组件的默认尺寸。scalenumber用于指定图片的缩放系数。未指定时默认为 1.0，即一个图片像素对应一个显示点 / DIP。bundleiOSstring图片所在的 iOS 资源包（asset bundle）。未设置时默认为 [NSBundle mainBundle]。methodstring要使用的 HTTP 请求方法。未指定时默认为 'GET'。headersobject随远程图片请求一起发送的 HTTP 头。bodystring随请求发送的 HTTP body。必须是有效的 UTF-8 字符串，并且会按原样发送，不做任何额外编码（如 URL 转义或 base64）。cacheiOSImageCacheEnum决定请求如何处理可能被缓存的响应。 当传入数字时： number - 类似 require('./image.jpg') 返回的不透明类型。