You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 22, 2023. It is now read-only.
Copy file name to clipboardExpand all lines: packages/image_picker/image_picker/README.md
+24-60Lines changed: 24 additions & 60 deletions
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ First, add `image_picker` as a [dependency in your pubspec.yaml file](https://fl
12
12
### iOS
13
13
14
14
Starting with version **0.8.1** the iOS implementation uses PHPicker to pick (multiple) images on iOS 14 or higher.
15
-
As a result of implementing PHPicker it becomes impossible to pick HEIC images on the iOS simulator in iOS 14+. This is a known issue. Please test this on a real device, or test with non-HEIC images until Apple solves this issue.[63426347 - Apple known issue](https://www.google.com/search?q=63426347+apple&sxsrf=ALeKk01YnTMid5S0PYvhL8GbgXJ40ZS[…]t=gws-wiz&ved=0ahUKEwjKh8XH_5HwAhWL_rsIHUmHDN8Q4dUDCA8&uact=5)
15
+
As a result of implementing PHPicker it becomes impossible to pick HEIC images on the iOS simulator in iOS 14+. This is a known issue. Please test this on a real device, or test with non-HEIC images until Apple solves this issue.[63426347 - Apple known issue](https://www.google.com/search?q=63426347+apple&sxsrf=ALeKk01YnTMid5S0PYvhL8GbgXJ40ZS[…]t=gws-wiz&ved=0ahUKEwjKh8XH_5HwAhWL_rsIHUmHDN8Q4dUDCA8&uact=5)
16
16
17
17
Add the following keys to your _Info.plist_ file, located in `<project root>/ios/Runner/Info.plist`:
18
18
@@ -37,7 +37,19 @@ If you require your picked image to be stored permanently, it is your responsibi
37
37
import 'package:image_picker/image_picker.dart';
38
38
39
39
...
40
-
final PickedFile? pickedFile = await picker.getImage(source: ImageSource.camera);
40
+
final ImagePicker _picker = ImagePicker();
41
+
// Pick an image
42
+
final XFile? image = await _picker.pickImage(source: ImageSource.gallery);
43
+
// Capture a photo
44
+
final XFile? photo = await _picker.pickImage(source: ImageSource.camera);
45
+
// Pick a video
46
+
final XFile? image = await _picker.pickVideo(source: ImageSource.gallery);
47
+
// Capture a video
48
+
final XFile? photo = await _picker.pickVideo(source: ImageSource.camera);
49
+
// Pick multiple images
50
+
final List<XFile>? images = await _picker.pickMultiImage(source: ImageSource.gallery);
51
+
// Pick multiple photos
52
+
final List<XFile>? photos = await _picker.pickMultiImage(source: ImageSource.camera);
Android system -- although very rarely -- sometimes kills the MainActivity after the image_picker finishes. When this happens, we lost the data selected from the image_picker. You can use `retrieveLostData` to retrieve the lost data in this situation. For example:
There's no way to detect when this happens, so calling this method at the right place is essential. We recommend to wire this into some kind of start up check. Please refer to the example app to see how we used it.
70
82
71
-
On Android, `getLostData` will only get the last picked image when picking multiple images, see: [#84634](https://github.com/flutter/flutter/issues/84634).
83
+
On Android, `retrieveLostData` will only get the last picked image when picking multiple images, see: [#84634](https://github.com/flutter/flutter/issues/84634).
72
84
73
-
## Deprecation warnings in `pickImage`, `pickVideo` and `LostDataResponse`
85
+
## Migrating to 0.8.2+
74
86
75
-
Starting with version **0.6.7** of the image_picker plugin, the API of the plugin changed slightly to allow for web implementations to exist.
76
-
77
-
The **old methods that returned `dart:io` File objects were marked as deprecated**, and a new set of methods that return [`PickedFile` objects](https://pub.dev/documentation/image_picker_platform_interface/latest/image_picker_platform_interface/PickedFile-class.html) were introduced.
78
-
79
-
### How to migrate from to ^0.6.7
80
-
81
-
#### Instantiate the `ImagePicker`
82
-
83
-
The new ImagePicker API does not rely in static methods anymore, so the first thing you'll need to do is to create a new instance of the plugin where you need it:
84
-
85
-
```dart
86
-
final _picker = ImagePicker();
87
-
```
87
+
Starting with version **0.8.2** of the image_picker plugin, new methods have been added for picking files that return `XFile` instances (from the [cross_file](https://pub.dev/packages/cross_file) package) rather than the plugin's own `PickedFile` instances. While the previous methods still exist, it is already recommended to start migrating over to their new equivalents. Eventually, `PickedFile` and the methods that return instances of it will be deprecated and removed.
88
88
89
89
#### Call the new methods
90
90
91
-
The new methods **receive the same parameters as before**, but they **return a `PickedFile`, instead of a `File`**. The `LostDataResponse` class has been replaced by the [`LostData` class](https://pub.dev/documentation/image_picker_platform_interface/latest/image_picker_platform_interface/LostData-class.html).
/// * [LostData], for what's included in the response.
162
163
/// * [Android Activity Lifecycle](https://developer.android.com/reference/android/app/Activity.html), for more information on MainActivity destruction.
164
+
@Deprecated('Switch to using retrieveLostData instead')
163
165
Future<LostData> getLostData() {
164
166
return platform.retrieveLostData();
165
167
}
168
+
169
+
/// Returns an [XFile] object wrapping the image that was picked.
170
+
///
171
+
/// The returned [XFile] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
172
+
///
173
+
/// The `source` argument controls where the image comes from. This can
174
+
/// be either [ImageSource.camera] or [ImageSource.gallery].
175
+
///
176
+
/// Where iOS supports HEIC images, Android 8 and below doesn't. Android 9 and above only support HEIC images if used
177
+
/// in addition to a size modification, of which the usage is explained below.
178
+
///
179
+
/// If specified, the image will be at most `maxWidth` wide and
180
+
/// `maxHeight` tall. Otherwise the image will be returned at it's
181
+
/// original width and height.
182
+
/// The `imageQuality` argument modifies the quality of the image, ranging from 0-100
183
+
/// where 100 is the original/max quality. If `imageQuality` is null, the image with
184
+
/// the original quality will be returned. Compression is only supported for certain
185
+
/// image types such as JPEG and on Android PNG and WebP, too. If compression is not supported for the image that is picked,
186
+
/// a warning message will be logged.
187
+
///
188
+
/// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
189
+
/// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
190
+
/// Defaults to [CameraDevice.rear]. Note that Android has no documented parameter for an intent to specify if
191
+
/// the front or rear camera should be opened, this function is not guaranteed
192
+
/// to work on an Android device.
193
+
///
194
+
/// In Android, the MainActivity can be destroyed for various reasons. If that happens, the result will be lost
195
+
/// in this call. You can then call [retrieveLostData] when your app relaunches to retrieve the lost data.
196
+
///
197
+
/// See also [pickMultiImage] to allow users to select multiple images at once.
198
+
///
199
+
/// The method could throw [PlatformException] if the app does not have permission to access
200
+
/// the camera or photos gallery, no camera is available, plugin is already in use,
201
+
/// temporary file could not be created (iOS only), plugin activity could not
202
+
/// be allocated (Android only) or due to an unknown error.
/// Returns a [List<XFile>] object wrapping the images that were picked.
220
+
///
221
+
/// The returned [List<XFile>] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
222
+
///
223
+
/// Where iOS supports HEIC images, Android 8 and below doesn't. Android 9 and above only support HEIC images if used
224
+
/// in addition to a size modification, of which the usage is explained below.
225
+
///
226
+
/// This method is not supported in iOS versions lower than 14.
227
+
///
228
+
/// If specified, the images will be at most `maxWidth` wide and
229
+
/// `maxHeight` tall. Otherwise the images will be returned at it's
230
+
/// original width and height.
231
+
/// The `imageQuality` argument modifies the quality of the images, ranging from 0-100
232
+
/// where 100 is the original/max quality. If `imageQuality` is null, the images with
233
+
/// the original quality will be returned. Compression is only supported for certain
234
+
/// image types such as JPEG and on Android PNG and WebP, too. If compression is not supported for the image that is picked,
235
+
/// a warning message will be logged.
236
+
///
237
+
/// The method could throw [PlatformException] if the app does not have permission to access
238
+
/// the camera or photos gallery, no camera is available, plugin is already in use,
239
+
/// temporary file could not be created (iOS only), plugin activity could not
240
+
/// be allocated (Android only) or due to an unknown error.
241
+
///
242
+
/// See also [pickImage] to allow users to only pick a single image.
243
+
Future<List<XFile>?> pickMultiImage({
244
+
double? maxWidth,
245
+
double? maxHeight,
246
+
int? imageQuality,
247
+
}) {
248
+
return platform.getMultiImage(
249
+
maxWidth: maxWidth,
250
+
maxHeight: maxHeight,
251
+
imageQuality: imageQuality,
252
+
);
253
+
}
254
+
255
+
/// Returns an [XFile] object wrapping the video that was picked.
256
+
///
257
+
/// The returned [XFile] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
258
+
///
259
+
/// The [source] argument controls where the video comes from. This can
260
+
/// be either [ImageSource.camera] or [ImageSource.gallery].
261
+
///
262
+
/// The [maxDuration] argument specifies the maximum duration of the captured video. If no [maxDuration] is specified,
263
+
/// the maximum duration will be infinite.
264
+
///
265
+
/// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
266
+
/// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
267
+
/// Defaults to [CameraDevice.rear].
268
+
///
269
+
/// In Android, the MainActivity can be destroyed for various fo reasons. If that happens, the result will be lost
270
+
/// in this call. You can then call [retrieveLostData] when your app relaunches to retrieve the lost data.
271
+
///
272
+
/// The method could throw [PlatformException] if the app does not have permission to access
273
+
/// the camera or photos gallery, no camera is available, plugin is already in use,
274
+
/// temporary file could not be created and video could not be cached (iOS only),
275
+
/// plugin activity could not be allocated (Android only) or due to an unknown error.
/// Retrieve the lost [XFile] when [pickImage], [pickMultiImage] or [pickVideo] failed because the MainActivity
290
+
/// is destroyed. (Android only)
291
+
///
292
+
/// Image or video can be lost if the MainActivity is destroyed. And there is no guarantee that the MainActivity is always alive.
293
+
/// Call this method to retrieve the lost data and process the data according to your APP's business logic.
294
+
///
295
+
/// Returns a [LostDataResponse] object if successfully retrieved the lost data. The [LostDataResponse] object can \
296
+
/// represent either a successful image/video selection, or a failure.
297
+
///
298
+
/// Calling this on a non-Android platform will throw [UnimplementedError] exception.
299
+
///
300
+
/// See also:
301
+
/// * [LostDataResponse], for what's included in the response.
302
+
/// * [Android Activity Lifecycle](https://developer.android.com/reference/android/app/Activity.html), for more information on MainActivity destruction.
0 commit comments