expo-image

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

@amazon-devices/expo-image为React Native和Expo提供跨平台、高性能的图像组件。该库支持BlurHash和ThumbHash，它们是图像占位符的紧凑表示形式。它还支持在来源更改时在图像之间进行转换。@amazon-devices/expo-image实现CSS object-fit和object-position属性（仅提供英文版）。

安装
用法示例
API参考
实现详情
支持的版本
其他资源

安装

在package.json文件中添加JavaScript库依赖项。

已复制到剪贴板。

 dependencies: {
     ...
     "@amazon-devices/expo-image": "~2.0.0",
 }

使用npm install命令重新安装依赖项。

用法示例

下面的示例演示了一个带有thumbhash占位符和多个来源的图像。

已复制到剪贴板。

import React from 'react';
import {StyleSheet, View} from 'react-native';
import {Image} from '@amazon-devices/expo-image';

export const App = () => {
  return (
    <View style={styles.container}>
      <Image
        source={[
          'https://images.pexels.com/photos/842711/pexels-photo-842711.jpeg',
          'https://climateforlife.pl/wp-content/uploads/2023/10/panda.png',
        ]}
        style={styles.image}
        placeholder="thumbhash:/1QcSHQRnh493V4dIh4eXh1h4kJUI"
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    backgroundColor: 'white',
    flex: 1,
  },
  image: {
    width: 300,
    aspectRatio: 1,
  },
});

API参考

查看专门的文档页面，了解有关此库、API参考等的信息：针对expo-image的官方Expo文档（仅提供英文版）。

组件

组件	描述
`Image`	加载和呈现图像的跨平台React组件

Image属性

属性	描述
`accessibilityLabel`	当用户与图像交互时，屏幕阅读器读取的文本。在网页上设置alt标签，用于网络爬虫和链接遍历。
`accessible`	如果为`true`，则表示视图是无障碍功能元素。如果视图是无障碍功能元素，它会将其子项聚集成一个可选组件。
`allowDownscaling`	是否应缩小图像以匹配视图容器的大小。默认设置为`true`。设置为`false`可能会对应用性能产生负面影响，尤其是在处理大型资产时。但是，设置为`false`将使图像大小调整更加流畅，并且最终用户将始终可以获得尽可能高的资产质量
`alt`	当用户与图像交互时，屏幕阅读器读取的文本。在网页上设置用于网络爬虫和链接遍历的`alt`标签。是`accessibilityLabel`的别名
`blurRadius`	以点为单位的模糊半径，若为`0`，表示没有模糊效果。此效果不适用于占位符。
`contentFit`	确定应如何调整图像大小以适配其容器。此属性要求图像以多种方式填充容器；例如“保持该宽高比”或“拉伸并占用尽可能多的空间”。它是CSS `object-fit`属性的镜像。
`contentPosition`	它与`contentFit`一起使用，用于指定应如何使用x/y坐标将图像放置在其自身的容器内。CSS `object-position`属性的等效属性。
`defaultSource`	图像来源的默认值。警告：已弃用。为React Native图像中的defaultSource提供兼容性。可改用placeholder属性。
`fadeDuration`	警告：已弃用。为React Native图像中的`fadeDuration`提供兼容性。可改为使用transition规定时长。
`focusable`	确定此View是否应针对非触摸输入设备可设定焦点，并使用硬件键盘获得焦点。
`loadingIndicatorSource`	警告：已弃用。为React Native图像中的`loadingIndicatorSource`提供兼容性。可改用placeholder属性。
`onError`	在图像提取错误时调用。
`onLoad`	在图像加载成功完成时调用。
`onLoadEnd`	在图像加载成功或失败时调用。
`onLoadStart`	在图像开始加载时调用。
`placeholder`	在加载正确图像但尚未显示任何图像或未设置来源时要显示的图像。
`priority`	完成加载的优先级。如果一次有多个负载排队，则优先级较高的负载将首先启动。对于优先级，会尽最大努力去处理，但无法保证负载的开始或完成顺序。
`recyclingKey`	在加载和渲染最终图像之前，更改此属性会将图像视图内容重置为空白或占位符。这对于任何类型的再循环视图（例如`FlashList`）特别有用，可以防止在新视图完全加载之前显示先前的来源代码。
`resizeMode`	警告：已弃用。为React Native图像中的`resizeMode`提供兼容性。请注意，完全不支持`“repeat”`选项。可改用更强大的`contentFit`和`contentPosition`属性。
`source`	图像来源，可以是远程URL、本地文件资源或由`require()` 函数产生的数字。当以来源数组的形式提供时，将选择最适合容器大小且最接近屏幕比例的来源。在这种情况下，提供`width`、`height`和`scale`属性很重要。
`tintColor`	一种用于着色模板图像（只有不透明度重要的位图图像）的颜色。颜色应用于每个非透明像素，从而使图像的形状采用该颜色。此效果不适用于占位符。
`transition`	描述切换图像来源时图像视图应如何转换内容。如果以数字形式提供，则为`'cross-dissolve'`效果的持续时间（以毫秒为单位）。

方法

方法	描述
`clearDiskCache`	异步清除磁盘缓存中的所有图像。
`clearMemoryCache`	异步清除存储在内存中的所有图像。
`prefetch`	在给定的URL上预加载图像，以后可以在图像视图中使用这些图像。预加载的图像始终缓存在磁盘上，因此请务必使用`disk`（默认）或`memory-disk`缓存策略。

实现详情

不支持SVG和动画来源
不支持onProgress
有时无法在Vega上调用onLoadEnd、onLoadStart、onLoad

支持的版本

程序包版本	基于	@amazon-devices/react-native-kepler版本
2.0.x	1.6.0	2.0.x

其他资源

有关其他库的信息，请参阅支持的第三方库和服务。

Last updated: 2025年9月30日