首页指南参考教程

Expo 图片

GitHub

npm

一个跨平台、高性能的 React 组件，用于加载和渲染图片。

Android

iOS

tvOS

Web

expo-image 是一个跨平台的 React 组件，用于加载和渲染图片。

¥**expo-image** is a cross-platform React component that loads and renders images.

主要特点：

¥Main features:

专为速度而设计

¥Designed for speed
支持多种图片格式（包括动画格式）

¥Support for many image formats (including animated ones)
磁盘和内存缓存

¥Disk and memory caching
支持 BlurHash 和 ThumbHash - 图片占位符的紧凑表示

¥Supports BlurHash and ThumbHash - compact representations of a placeholder for an image
当源更改时在图片之间转换（不再闪烁！）

¥Transitioning between images when the source changes (no more flickering!)
实现 CSS object-fit 和 object-position 属性（参见 contentFit 和 contentPosition 属性）

¥Implements the CSS object-fit and object-position properties (see contentFit and contentPosition props)
在引擎盖下使用高性能 SDWebImage 和 Glide

¥Uses performant SDWebImage and Glide under the hood

支持的图片格式

¥Supported image formats

格式	安卓	iOS 系统	Web
WebP
PNG/APNG
AVIF			约 87% 采用率
HEIC			尚未采用
JPEG
GIF
SVG
ICO
ICNS

安装

¥Installation

Terminal

- npx expo install expo-image

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

用法

¥Usage

import { Image } from 'expo-image';
import { StyleSheet, View } from 'react-native';

const blurhash =
  '|rF?hV%2WCj[ayj[a|j[az_NaeWBj@ayfRayfQfQM{M|azj[azf6fQfQfQIpWXofj[ayj[j[fQayWCoeoeaya}j[ayfQa{oLj?j[WVj[ayayj[fQoff7azayj[ayj[j[ayofayayayj[fQj[ayayj[ayfjj[j[ayjuayj[';

export default function App() {
  return (
    <View style={styles.container}>
      <Image
        style={styles.image}
        source="https://picsum.photos/seed/696/3000/2000"
        placeholder={{ blurhash }}
        contentFit="cover"
        transition={1000}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
  image: {
    flex: 1,
    width: '100%',
    backgroundColor: '#0553',
  },
});

API

import { Image } from 'expo-image';

Props

`accessibilityLabel`

Optional • Type: string • Default: undefined

The text that's read by the screen reader when the user interacts with the image. Sets the the alt tag on web which is used for web crawlers and link traversal.

Only for:

Android

iOS

`accessible`

Optional • Type: boolean • Default: false

When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component.

On Android, the accessible property will be translated into the native isScreenReaderFocusable, so it's only affecting the screen readers behaviour.

`allowDownscaling`

Optional • Type: boolean • Default: true

Whether the image should be downscaled to match the size of the view container. Turning off this functionality could negatively impact the application's performance, particularly when working with large assets. However, it would result in smoother image resizing, and end-users would always have access to the highest possible asset quality.

Downscaling is never used when the contentFit prop is set to none or fill.

`alt`

Optional • Type: string • Default: undefined

The text that's read by the screen reader when the user interacts with the image. Sets the the alt tag on web which is used for web crawlers and link traversal. Is an alias for accessibilityLabel.

Only for:

Android

iOS

`autoplay`

Optional • Type: boolean • Default: true

Determines if an image should automatically begin playing if it is an animated image.

`blurRadius`

Optional • Type: number • Default: 0

The radius of the blur in points, 0 means no blur effect. This effect is not applied to placeholders.

`cachePolicy`

Optional • Type: null | 'disk' | 'memory-disk' | 'memory' | 'none' • Default: 'disk'

Determines whether to cache the image and where: on the disk, in the memory or both.

'none' - Image is not cached at all.
'disk' - Image is queried from the disk cache if exists, otherwise it's downloaded and then stored on the disk.
'memory' - Image is cached in memory. Might be useful when you render a high-resolution picture many times. Memory cache may be purged very quickly to prevent high memory usage and the risk of out of memory exceptions.
'memory-disk' - Image is cached in memory, but with a fallback to the disk cache.

`contentFit`

Optional • Type: ImageContentFit • Default: 'cover'

Determines how the image should be resized to fit its container. This property tells the image to fill the container in a variety of ways; such as "preserve that aspect ratio" or "stretch up and take up as much space as possible". It mirrors the CSS object-fit property.

'cover' - The image is sized to maintain its aspect ratio while filling the container box. If the image's aspect ratio does not match the aspect ratio of its box, then the object will be clipped to fit.
'contain' - The image is scaled down or up to maintain its aspect ratio while fitting within the container box.
'fill' - The image is sized to entirely fill the container box. If necessary, the image will be stretched or squished to fit.
'none' - The image is not resized and is centered by default. When specified, the exact position can be controlled with contentPosition prop.
'scale-down' - The image is sized as if none or contain were specified, whichever would result in a smaller concrete image size.

`contentPosition`

Optional • Type: ImageContentPosition • Default: 'center'

It is used together with contentFit to specify how the image should be positioned with x/y coordinates inside its own container. An equivalent of the CSS object-position property.

Only for:

Android

`decodeFormat`

Optional • Type: ImageDecodeFormat • Default: 'argb'

The format in which the image data should be decoded. It's not guaranteed that the platform will use the specified format.

'argb' - The image is decoded into a 32-bit color space with alpha channel (https://developer.android.com/reference/android/graphics/Bitmap.Config#ARGB_8888).
'rgb' - The image is decoded into a 16-bit color space without alpha channel (https://developer.android.com/reference/android/graphics/Bitmap.Config#RGB_565).

Deprecated. Provides compatibility for defaultSource from React Native Image. Use placeholder prop instead.

`defaultSource`

Optional • Type: null | ImageSource

Only for:

iOS 16.0+

`enableLiveTextInteraction`

Optional • Type: boolean • Default: false

Enables Live Text interaction with the image. Check official Apple documentation for more details.

Deprecated. Provides compatibility for fadeDuration from React Native Image. Instead use transition with the provided duration.

`fadeDuration`

Optional • Type: number

Only for:

Android

`focusable`

Optional • Type: boolean • Default: false

Whether this View should be focusable with a non-touch input device and receive focus with a hardware keyboard.

Deprecated. Provides compatibility for loadingIndicatorSource from React Native Image. Use placeholder prop instead.

`loadingIndicatorSource`

Optional • Type: null | ImageSource

`onError`

Optional • Type: (event: ImageErrorEventData) => void

Called on an image fetching error.

`onLoad`

Optional • Type: (event: ImageLoadEventData) => void

Called when the image load completes successfully.

`onLoadEnd`

Optional • Type: () => void

Called when the image load either succeeds or fails.

`onLoadStart`

Optional • Type: () => void

Called when the image starts to load.

`onProgress`

Optional • Type: (event: ImageProgressEventData) => void

Called when the image is loading. Can be called multiple times before the image has finished loading. The event object provides details on how many bytes were loaded so far and what's the expected total size.

`placeholder`

An image to display while loading the proper image and no image has been displayed yet or the source is unset.

`placeholderContentFit`

Optional • Type: ImageContentFit • Default: 'scale-down'

Determines how the placeholder should be resized to fit its container. Available resize modes are the same as for the contentFit prop.

`priority`

Optional • Type: null | 'low' | 'normal' | 'high' • Default: 'normal'

Priorities for completing loads. If more than one load is queued at a time, the load with the higher priority will be started first. Priorities are considered best effort, there are no guarantees about the order in which loads will start or finish.

Only for:

Android

iOS

`recyclingKey`

Optional • Type: null | string • Default: null

Changing this prop resets the image view content to blank or a placeholder before loading and rendering the final image. This is especially useful for any kinds of recycling views like FlashList to prevent showing the previous source before the new one fully loads.

Deprecated. Provides compatibility for resizeMode from React Native Image. Note that "repeat" option is not supported at all. Use the more powerful contentFit and contentPosition props instead.

`resizeMode`

Optional • Type: 'cover' | 'contain' | 'center' | 'stretch' | 'repeat'

Only for:

Web

`responsivePolicy`

Optional • Type: 'live' | 'initial' | 'static' • Default: 'static'

Controls the selection of the image source based on the container or viewport size on the web.

If set to 'static', the browser selects the correct source based on user's viewport width. Works with static rendering. Make sure to set the 'webMaxViewportWidth' property on each source for best results. For example, if an image occupies 1/3 of the screen width, set the 'webMaxViewportWidth' to 3x the image width. The source with the largest 'webMaxViewportWidth' is used even for larger viewports.

If set to 'initial', the component will select the correct source during mount based on container size. Does not work with static rendering.

If set to 'live', the component will select the correct source on every resize based on container size. Does not work with static rendering.

`source`

The image source, either a remote URL, a local file resource or a number that is the result of the require() function. When provided as an array of sources, the source that fits best into the container size and is closest to the screen scale will be chosen. In this case it is important to provide width, height and scale properties.

`tintColor`

Optional • Type: null | string • Default: null

A color used to tint template images (a bitmap image where only the opacity matters). The color is applied to every non-transparent pixel, causing the image’s shape to adopt that color. This effect is not applied to placeholders.

`transition`

Optional • Type: null | number | ImageTransition

Describes how the image view should transition the contents when switching the image source.
If provided as a number, it is the duration in milliseconds of the 'cross-dissolve' effect.

Inherited Props

ViewProps

Static Methods

Only for:

Android

iOS

`clearDiskCache()`

Asynchronously clears all images from the disk cache.

Returns

Promise<boolean>

A promise resolving to true when the operation succeeds. It may resolve to false on Android when the activity is no longer available. Resolves to false on Web.

Only for:

Android

iOS

`clearMemoryCache()`

Asynchronously clears all images stored in memory.

Returns

Promise<boolean>

A promise resolving to true when the operation succeeds. It may resolve to false on Android when the activity is no longer available. Resolves to false on Web.

Only for:

iOS

`generateBlurhashAsync(url, numberOfComponents)`

Name	Type	Description
url	`string`	The URL of the image to generate a blurhash from.
numberOfComponents	`[number, number] \| { height: number, width: number }`	The number of components to encode the blurhash with. Must be between 1 and 9. Defaults to `[4, 3]`.

Asynchronously generates a Blurhash from an image.

Returns

Promise<null | string>

A promise resolving to the blurhash string.

Only for:

Android

iOS

`getCachePathAsync(cacheKey)`

Name	Type	Description
cacheKey	`string`	The cache key for the requested image. Unless you have set a custom cache key, this will be the source URL of the image.

Asynchronously checks if an image exists in the disk cache and resolves to the path of the cached image if it does.

Returns

Promise<null | string>

A promise resolving to the path of the cached image. It will resolve to null if the image does not exist in the cache.

`prefetch(urls, cachePolicy)`

Name	Type	Description
urls	`string \| string[]`	A URL string or an array of URLs of images to prefetch.
cachePolicy (optional)	`'disk' \| 'memory-disk' \| 'memory'`	The cache policy for prefetched images.

Preloads images at the given URLs that can be later used in the image view. Preloaded images are cached to the memory and disk by default, so make sure to use disk (default) or memory-disk cache policy.

Returns

Promise<boolean>

A promise resolving to true as soon as all images have been successfully prefetched. If an image fails to be prefetched, the promise will immediately resolve to false regardless of whether other images have finished prefetching.

`prefetch(urls, options)`

Name	Type	Description
urls	`string \| string[]`	A URL string or an array of URLs of images to prefetch.
options (optional)	`ImagePrefetchOptions`	Options for prefetching images.

Returns

Promise<boolean>

Component Methods

Only for:

Android

iOS

`startAnimating()`

Asynchronously starts playback of the view's image if it is animated.

Returns

Promise<void>

Only for:

Android

iOS

`stopAnimating()`

Asynchronously stops the playback of the view's image if it is animated.

Returns

Promise<void>

Types

`ImageContentPosition`

Specifies the position of the image inside its container. One value controls the x-axis and the second value controls the y-axis.

Additionally, it supports stringified shorthand form that specifies the edges to which to align the image content:
'center', 'top', 'right', 'bottom', 'left', 'top center', 'top right', 'top left', 'right center', 'right top', 'right bottom', 'bottom center', 'bottom right', 'bottom left', 'left center', 'left top', 'left bottom'.
If only one keyword is provided, then the other dimension is set to 'center' ('50%'), so the image is placed in the middle of the specified edge.
As an example, 'top right' is the same as { top: 0, right: 0 } and 'bottom' is the same as { bottom: 0, left: '50%' }.

ImageContentPositionString or object shaped as below:

Name	Type	Description
right (optional)	`ImageContentPositionValue`	-
top (optional)	`ImageContentPositionValue`	-

Name	Type	Description
left (optional)	`ImageContentPositionValue`	-
top (optional)	`ImageContentPositionValue`	-

Name	Type	Description
bottom (optional)	`ImageContentPositionValue`	-
right (optional)	`ImageContentPositionValue`	-

Name	Type	Description
bottom (optional)	`ImageContentPositionValue`	-
left (optional)	`ImageContentPositionValue`	-

`ImageContentPositionValue`

Literal Type: multiple types

A value that represents the relative position of a single axis.

If number, it is a distance in points (logical pixels) from the respective edge.
If string, it must be a percentage value where '100%' is the difference in size between the container and the image along the respective axis, or 'center' which is an alias for '50%' that is the default value. You can read more regarding percentages on the MDN docs for background-position that describes this concept well.

Acceptable values are: number | string | 'center'

`ImageErrorEventData`

Name	Type	Description
error	`string`	-

`ImageLoadEventData`

Name	Type	Description
cacheType	`'none' \| 'disk' \| 'memory'`	-
source	`{ height: number, isAnimated: boolean, mediaType: string \| null, url: string, width: number }`	-

`ImagePrefetchOptions`

Name	Type	Description
cachePolicy (optional)	`'disk' \| 'memory-disk' \| 'memory'`	The cache policy for prefetched images. Default: `'memory-disk'`
headers (optional)	`Record<string, string>`	A map of headers to use when prefetching the images.

`ImageProgressEventData`

Name	Type	Description
loaded	`number`	-
total	`number`	-

`ImageSource`

Name	Type	Description
blurhash (optional)	`string`	A string used to generate the image `placeholder`. For example, `placeholder={blurhash}`. If `uri` is provided as the value of the `source` prop, this is ignored since the `source` can only have `blurhash` or `uri`. When using the blurhash, you should also provide `width` and `height` (higher values reduce performance), otherwise their default value is `16`. For more information, see `woltapp/blurhash` repository.
cacheKey (optional)	`string`	The cache key used to query and store this specific image. If not provided, the `uri` is used also as the cache key.
headers (optional)	`Record<string, string>`	An object representing the HTTP headers to send along with the request for a remote image. On web requires the `Access-Control-Allow-Origin` header returned by the server to include the current domain.
height (optional)	`number`	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.
isAnimated (optional)	`boolean`	Only for: Android iOS Whether the image is animated (an animated GIF or WebP for example).
thumbhash (optional)	`string`	A string used to generate the image `placeholder`. For example, `placeholder={thumbhash}`. If `uri` is provided as the value of the `source` prop, this is ignored since the `source` can only have `thumbhash` or `uri`. For more information, see `thumbhash website`.
uri (optional)	`string`	A string representing the resource identifier for the image, which could be an HTTPS address, a local file path, or the name of a static image resource.
webMaxViewportWidth (optional)	`number`	Only for: Web The max width of the viewport for which this source should be selected. Has no effect if `source` prop is not an array or has only 1 element. Has no effect if `responsivePolicy` is not set to `static`. Ignored if `blurhash` or `thumbhash` is provided (image hashes are never selected if passed in an array).
width (optional)	`number`	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.

`ImageTransition`

An object that describes the smooth transition when switching the image source.

Name	Type	Description
duration (optional)	`number`	The duration of the transition in milliseconds. Default: `0`
effect (optional)	`'cross-dissolve' \| 'flip-from-top' \| 'flip-from-right' \| 'flip-from-bottom' \| 'flip-from-left' \| 'curl-up' \| 'curl-down' \| null`	An animation effect used for transition. Default: 'cross-dissolve' On Android, only `'cross-dissolve'` is supported. On Web, `'curl-up'` and `'curl-down'` effects are not supported.
timing (optional)	`'ease-in-out' \| 'ease-in' \| 'ease-out' \| 'linear'`	Specifies the speed curve of the transition effect and how intermediate values are calculated. Default: `'ease-in-out'`

在服务器上生成模糊散列

¥Generating a blurhash on a server

图片可以显着改善视觉体验，但是，由于文件大小较大，它们也会减慢应用/页面的加载时间。为了克服这个问题，你可以使用 blurhash 算法创建占位符图片，该算法提供身临其境的体验，同时将实际图片的加载推迟到以后。

¥Images can significantly improve the visual experience, however, they can also slow down app/page loading times due to their large file sizes. To overcome this, you can create placeholder images using blurhash algorithm that provides an immersive experience while deferring the loading of the actual picture until later.

本指南演示了如何使用 JavaScript 和 Express.js 在后端创建上传图片的模糊散列。相同的技术和原理适用于其他语言和服务器技术。

¥This guide demonstrates how to create a blurhash of an uploaded image on the backend using JavaScript and Express.js. The same techniques and principles apply to other languages and server technologies.

首先安装一些依赖：multer 用于处理多部分请求，sharp 用于将文件转换为数据缓冲区，以及官方的 blurhash JavaScript 包。

¥Start by installing a few dependencies: multer for handling multipart requests, sharp for converting files to a data buffer, and the official blurhash JavaScript package.

Terminal

- npm install multer sharp blurhash

接下来，从已安装的包中导入所有必需的功能并初始化 multer：

¥Next, import all required functions from installed packages and initialize multer:

// Multer is a middleware for handling `multipart/form-data`.
const multer = require('multer');
// Sharp allows you to receive a data buffer from the uploaded image.
const sharp = require('sharp');
// Import the encode function from the blurhash package.
const { encode } = require('blurhash');

// Initialize `multer`.
const upload = multer();

假设 app 是一个保存对 Express 服务器的引用的变量，则可以创建一个端点来接受图片并返回包含生成的模糊哈希的 JSON 响应。

¥Assuming the app is a variable that holds a reference to the Express server, an endpoint can be created that accepts an image and returns a JSON response containing the generated blurhash.

app.post('/blurhash', upload.single('image'), async (req, res) => {
  const { file } = req;
  // If the file is not available we're returning with error.
  if (file === null) {
    res.status(400).json({ message: 'Image is missing' });
    return;
  }

  // Users can specify number of components in each axes.
  const componentX = req.body.componentX ?? 4;
  const componentY = req.body.componentY ?? 3;

  // We're converting provided image to a byte buffer.
  // Sharp currently supports multiple common formats like JPEG, PNG, WebP, GIF, and AVIF.
  const { data, info } = await sharp(file.buffer).ensureAlpha().raw().toBuffer({
    resolveWithObject: true,
  });

  const blurhash = encode(data, info.width, info.height, componentX, componentY);
  res.json({ blurhash });
});

此外，请求可以包含两个参数：componentX 和 componentY，通过算法。这些值可以在服务器上计算或硬编码或由用户指定。但是，它们必须在 1 到 9 的范围内，并且宽高比与上传的图片相似。值 9 将给出最佳结果，但生成哈希可能需要更长的时间。

¥Additionally, the request can include two parameters: componentX and componentY, are passed through the algorithm. These values can be calculated or hard-coded on the server or specified by the user. However, they must be within the range of 1 to 9 and have an aspect ratio similar to the uploaded image. A value of 9 will give the best results but may take longer to generate the hash.

生成模糊哈希的过程可以通过多种语言和服务器技术来完成，类似于使用 JavaScript。关键步骤是找到你选择的语言的编码器，该编码器通常可以在 woltapp/blurhash 存储库中找到。拥有编码器后，你将需要获取图片的表示。某些库使用默认图片类（例如，Swift 实现使用 UIImage）。在其他情况下，你将必须提供原始字节数据。请务必检查编码器的文档以确认预期的数据格式。

¥The process of generating a blurhash can be accomplished in various languages and server technologies, similar to the one using JavaScript. The key step is to locate an encoder for your chosen language, which can often be found in the woltapp/blurhash repository. Once you have the encoder, you will need to obtain a representation of the image. Some libraries use a default image class (for example, the Swift implementation uses UIImage). In other cases, you will have to provide raw byte data. Make sure to check the encoder's documentation to confirm the expected data format.

使用原始字节数据时，请确保存在 alpha 层（每个像素由红色、绿色、蓝色和 alpha 值表示）。否则会导致诸如 "宽度和高度必须与像素数组匹配" 之类的错误。

¥When working with raw byte data, ensure that the alpha layer is present (each pixel is represented by red, green, blue, and alpha values). Failing to do so will lead to errors such as "width and height must match the pixels array".