This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 图片
一个跨平台、高性能的 React 组件,用于加载和渲染图片。
expo-image 是一个跨平台的 React 组件,用于加载和渲染图片。
主要特点:
- 专为速度而设计
- 支持多种图片格式(包括动画格式)
- 磁盘和内存缓存
- 支持 BlurHash 和 ThumbHash——图片占位符的紧凑表示
- 当源更改时在图片之间转换(不再闪烁!)
- 实现了 CSS
object-fit和object-position属性(参见contentFit和contentPosition属性) - 在底层使用高性能的
SDWebImage和Glide
支持的图片格式
† 在 iOS 上,系统的 SVG 解码器无法处理所有有效路径。带有多组参数的椭圆弧命令(
A或a)以及打包的large-arc-flag和sweep-flag值可能会导致渲染扭曲或根本无法渲染。大多数 SVG 压缩工具会生成这种紧凑形式,例如a6 6 0 0111.573-2.226 3.75 3.75 0 014.133 4.303。要修复文件,可以用空格分隔两个标志(a6 6 0 0 1 11.573 -2.226 3.75 3.75 0 0 1 4.133 4.303),或者给每个弧线单独一个命令。为了更广泛的 SVG 兼容性,可以使用react-native-svg,它可以正确渲染这些路径。
安装
🌐 Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
应用配置中的配置
🌐 Configuration in app config
你可以使用 expo-image 的 配置插件 配置构建时设置。将该插件添加到 app.json 或 app.config.js 中的 plugins 数组,然后重新构建原生项目。
🌐 You can configure build-time settings for expo-image using its config plugin. Add the plugin to the plugins array in your app.json or app.config.js and rebuild the native project.
Example app.json with config plugin
Configurable properties
Are you using this library in an existing React Native app?
如果你没有使用连续本地生成(CNG)或者你手动使用原生 iOS 项目,那么在运行 pod install 之前设置 shell 环境变量 EXPO_IMAGE_DISABLE_LIBDAV1D=1 可达到相同效果。或者,你也可以将 ENV['EXPO_IMAGE_DISABLE_LIBDAV1D'] ||= '0' 添加到你的 Podfile 顶部。
用法
🌐 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', }, });
使用本地资源的图片
🌐 Using images from native resources
可以通过名称使用 source={{ uri: 'app_icon' }} 加载打包在 Xcode 资源目录或 Android 可绘制资源中的图片。省略文件扩展名并手动提供图片尺寸:
🌐 Images bundled in Xcode asset catalogs or Android drawable resources can be loaded by name with
source={{ uri: 'app_icon' }}. Omit the file extension and provide image dimensions manually:
import { Image } from 'expo-image'; export default function AppIcon() { return <Image source={{ uri: 'app_icon' }} style={{ width: 40, height: 40 }} />; }
应用接口
🌐 API
import { Image } from 'expo-image';
No API data file found, sorry!
在服务器上生成模糊散列
🌐 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.
接下来,从已安装的包中导入所有所需的函数,并初始化 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( new Uint8ClampedArray(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.
生成 blurhash 的过程可以用多种语言和服务器技术完成,类似于使用 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 值表示)。如果不这样做,会导致诸如“宽度和高度必须与像素数组匹配”的错误。