This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo ImagePicker
一个库,可提供对系统 UI 的访问,以便从手机库中选择图片和视频或使用相机拍照。
expo-image-picker 提供访问系统界面,以便从手机图库中选择图片和视频,或使用相机拍照。
已知问题 iOS
🌐 Known issues
在 iOS 上,当从相机胶卷中选择图片(通常是更高分辨率的图片)时,裁剪后的图片结果在某些情况下会给出错误的裁剪矩形值。不幸的是,这个问题出在底层的 UIImagePickerController 上,这是由于 iOS 内置的闭源工具中的一个 bug 引起的。
🌐 On iOS, when an image (usually of a higher resolution) is picked from the camera roll, the result of the cropped image gives the wrong value for the cropped rectangle in some cases. Unfortunately, this issue is with the underlying UIImagePickerController due to a bug in the closed-source tools built into iOS.
安装
🌐 Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
应用配置中的配置
🌐 Configuration in app config
如果你的项目中使用配置插件(连续原生生成(CNG)),你可以使用其内置的 config 插件 配置 expo-image-picker。该插件允许你配置一些无法在运行时设置的属性,这些属性需要构建新的应用二进制文件才能生效。如果你的应用不使用 CNG,那么你需要手动配置该库。
🌐 You can configure expo-image-picker using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
默认情况下,expo-image-picker 会在 Android 上添加 RECORD_AUDIO 权限。你可以通过在下面的配置中将 microphonePermission 设置为 false 来移除它。
🌐 By default expo-image-picker will add RECORD_AUDIO permission on Android. You can remove it by setting the microphonePermission to false in the config below.
Example app.json with config plugin
Configurable properties
Are you using this library in an existing React Native app?
如果你没有使用连续原生生成(CNG)或者你是手动使用原生 iOS 项目,那么你需要在你的 ios/[app]/Info.plist 中添加 NSPhotoLibraryUsageDescription、NSCameraUsageDescription 和 NSMicrophoneUsageDescription 键:
🌐 If you're not using Continuous Native Generation (CNG) or you're using a native ios project manually, then you need to add NSPhotoLibraryUsageDescription, NSCameraUsageDescription, and NSMicrophoneUsageDescription keys to your ios/[app]/Info.plist:
用法
🌐 Usage
当你运行此示例并选择一个图片时,你将看到你选择的图片显示在应用中,并且控制台中将显示类似的日志:
🌐 When you run this example and pick an image, you will see the image that you picked show up in your app, and a similar log will be shown in the console:
{ "assets": [ { "assetId": "C166F9F5-B5FE-4501-9531", "base64": null, "duration": null, "exif": null, "fileName": "IMG.HEIC", "fileSize": 6018901, "height": 3025, "type": "image", "uri": "file:///data/user/0/host.exp.exponent/cache/cropped1814158652.jpg" "width": 3024 } ], "canceled": false }
调用视频权限 iOS
🌐 Invoke permissions for videos
在 SDK 54 及更高版本中,默认配置保持 allowsEditing 设置为 false,并将 videoExportPreset 设置为 'Passthrough'。这些设置会立即返回原始资源(包括 HEIC 和 AVIF 文件),因为选择器会跳过压缩,但 iOS 需要媒体库权限才能访问原始文件,并在用户选择视频后立即显示权限对话框。
🌐 In SDK 54 and later, the default configuration keeps allowsEditing set to false and videoExportPreset set to 'Passthrough'. These settings return the original asset (including HEIC and AVIF files) instantly because the picker skips compression, but iOS requires media library permission to access the original file and displays a permission dialog immediately after the user selects a video.
为了在选择后避免显示权限对话框,请在打开选择器之前通过 requestMediaLibraryPermissionsAsync 或 useMediaLibraryPermissions 手动请求媒体库权限。
🌐 To avoid showing permissions dialog after selection, manually request media library permissions before opening the picker via requestMediaLibraryPermissionsAsync or useMediaLibraryPermissions.
使用 AWS S3
🌐 With AWS S3
有关如何使用 AWS 存储的示例可以在 with-aws-storage-upload 中找到。
请参阅 Amplify 文档 指南以正确设置你的项目。
🌐 See Amplify documentation guide to set up your project correctly.
使用 Firebase
🌐 With Firebase
有关如何使用 Firebase 存储的示例可以在 with-firebase-storage-upload 中找到。
请参阅 使用 Firebase 指南,以正确设置你的项目。
🌐 See Using Firebase guide to set up your project correctly.
应用接口
🌐 API
import * as ImagePicker from 'expo-image-picker';
No API data file found, sorry!
权限
🌐 Permissions
安卓
🌐 Android
以下权限会通过库的 AndroidManifest.xml 自动添加。
🌐 The following permissions are added automatically through the library's AndroidManifest.xml.
iOS
该库中的 API 使用以下用法描述键。
🌐 The following usage description keys are used by the APIs in this library.