Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
cordova-plugin-camera
Advanced tools
cordova-plugin-camera - npm Package Compare versions
Comparing version 7.0.0 to 8.0.0
| { | ||
| "name": "cordova-plugin-camera", | ||
| "version": "7.0.0", | ||
| "version": "8.0.0", | ||
| "description": "Cordova Camera Plugin", | ||
@@ -60,2 +60,7 @@ "types": "./types/index.d.ts", | ||
| "8.0.0": { | ||
| "cordova-android": ">=12.0.0", | ||
| "cordova-ios": ">=5.1.0", | ||
| "cordova": ">=9.0.0" | ||
| }, | ||
| "9.0.0": { | ||
| "cordova": ">100" | ||
@@ -66,4 +71,4 @@ } | ||
| "devDependencies": { | ||
| "@cordova/eslint-config": "^5.0.0" | ||
| "@cordova/eslint-config": "^5.1.0" | ||
| } | ||
| } |
216
README.md
@@ -138,5 +138,28 @@ --- | ||
| Takes a photo using the camera, or retrieves a photo from the device's | ||
| image gallery. The image is passed to the success callback as a | ||
| Base64-encoded `String`, or as the URI for the image file. | ||
| image gallery. The result is provided in the first parameter of the `successCallback` as a string. | ||
| As of v8.0.0, the result is formatted as URIs. The scheme will vary depending on settings and platform. | ||
| |Platform|Destination Type|Format| | ||
| |---|---|---| | ||
| |Android|FILE_URI|An URI scheme such as `file://...` or `content://...`| | ||
| ||DATA_URL|Base 64 encoded with the proper data URI header| | ||
| |iOS|FILE_URI|`file://` schemed paths| | ||
| ||DATA_URL|Base 64 encoded with the proper data URI header| | ||
| |Browser|FILE_URI|Not supported| | ||
| ||DATA_URL|Base 64 encoded with the proper data URI header| | ||
| v7 and earlier versions, the return format is as follows: | ||
| |Platform|Destination Type|Format| | ||
| |---|---|---| | ||
| |Android|FILE_URI|Raw file path (unprefixed)| | ||
| ||DATA_URL|Base 64 encoded, without the `data:` prefix | ||
| |iOS|FILE_URI|`file://` schemed paths| | ||
| ||DATA_URL|Base 64 encoded, without the `data:` prefix | ||
| |Browser|FILE_URI|Not supported| | ||
| ||DATA_URL|Base 64 encoded, without the `data:` prefix| | ||
| For this reason, upgrading to v8 is strongly recommended as it greatly streamlines the return data. | ||
| The `camera.getPicture` function opens the device's default camera | ||
@@ -153,12 +176,6 @@ application that allows users to snap pictures by default - this behavior occurs, | ||
| one of the following formats, depending on the specified | ||
| `cameraOptions`: | ||
| `cameraOptions`. You can do whatever you want with content: | ||
| - A `String` containing the Base64-encoded photo image. | ||
| - A `String` representing the image file location on local storage (default). | ||
| You can do whatever you want with the encoded image or URI, for | ||
| example: | ||
| - Render the image in an `<img>` tag, as in the example below | ||
| - Save the data locally (`LocalStorage`, [Lawnchair](http://brianleroux.github.com/lawnchair/), etc.) | ||
| - Render the content in an `<img>` or `<video>` tag | ||
| - Copy the data to a persistent location | ||
| - Post the data to a remote server | ||
@@ -172,2 +189,28 @@ | ||
| __NOTE__: To use `saveToPhotoAlbum` option on Android 9 (API 28) and lower, the `WRITE_EXTERNAL_STORAGE` permission must be declared. | ||
| To do this, add the following in your `config.xml`: | ||
| ```xml | ||
| <config-file target="AndroidManifest.xml" parent="/*" xmlns:android="http://schemas.android.com/apk/res/android"> | ||
| <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" /> | ||
| </config-file> | ||
| ``` | ||
| Android 10 (API 29) and later devices does not require `WRITE_EXTERNAL_STORAGE` permission. If your application only supports Android 10 or later, then this step is not necessary. | ||
| #### FILE_URI Usage | ||
| When `FILE_URI` is used, the returned path is not directly usable. The file path needs to be resolved into | ||
| a DOM-usable URL using the [Cordova File Plugin](https://github.com/apache/cordova-plugin-file). | ||
| Additionally, the file URIs returned is a temporary read access grant. The OS reserves the right to revoke permission to access the resource, which typically occurs after the app has been closed. For images captured using the camera, the image is stored in a temporary location which can be cleared at any time, usually after the app exits. It's the application's decision to decide how the content should be used depending on their use cases. | ||
| For persistent access to the content, the resource should be copied to your app's storage container. An example use case is an app allowing an user to select a profile picture from their gallery or camera. The application will need | ||
| consistent access to that resource, so it's not suitable to retain the temporary access path. So the appplication should copy the resource to a persistent location. | ||
| For use cases that involve temporary use, it is valid and safe to use the temporary file path to display the content. An example of this could be an image editing application, rendering the data into a canvas. | ||
| __NOTE__: The returned schemes is an implementation detail. Do not assume that it will always be a `file://` URI. | ||
| __Supported Platforms__ | ||
@@ -238,11 +281,18 @@ | ||
| | --- | --- | --- | | ||
| | imageData | <code>string</code> | Base64 encoding of the image data, _or_ the image file URI, depending on [`cameraOptions`](#module_camera.CameraOptions) in effect. | | ||
| | imageData | <code>string</code> | Data URI, _or_ the image file URI, depending on [`cameraOptions`](#module_camera.CameraOptions) in effect. | | ||
| **Example** | ||
| ```js | ||
| // Show image | ||
| // | ||
| // Show image captured with FILE_URI | ||
| function cameraCallback(imageData) { | ||
| window.resolveLocalFileSystemURL(uri, (entry) => { | ||
| let image = document.getElementById('myImage'); | ||
| image.src = entry.toURL(); | ||
| }, onError); | ||
| } | ||
| // Show image captured with DATA_URL | ||
| function cameraCallback(imageData) { | ||
| var image = document.getElementById('myImage'); | ||
| image.src = "data:image/jpeg;base64," + imageData; | ||
| image.src = imageData; | ||
| } | ||
@@ -264,3 +314,3 @@ ``` | ||
| | sourceType | <code>[PictureSourceType](#module_Camera.PictureSourceType)</code> | <code>CAMERA</code> | Set the source of the picture. | | ||
| | allowEdit | <code>Boolean</code> | <code>false</code> | Allow simple editing of image before selection. | | ||
| | ~~allowEdit~~ | <code>Boolean</code> | <code>false</code> | **Deprecated**. Allow simple editing of image before selection. | | ||
| | encodingType | <code>[EncodingType](#module_Camera.EncodingType)</code> | <code>JPEG</code> | Choose the returned image file's encoding. | | ||
@@ -271,3 +321,3 @@ | targetWidth | <code>number</code> | | Width in pixels to scale image. Must be used with `targetHeight`. Aspect ratio remains constant. | | ||
| | correctOrientation | <code>Boolean</code> | | Rotate the image to correct for the orientation of the device during capture. | | ||
| | saveToPhotoAlbum | <code>Boolean</code> | | Save the image to the photo album on the device after capture. | | ||
| | saveToPhotoAlbum | <code>Boolean</code> | | Save the image to the photo album on the device after capture.<br />See [Android Quirks](#cameragetpicturesuccesscallback-errorcallback-options). | | ||
| | popoverOptions | <code>[CameraPopoverOptions](#module_CameraPopoverOptions)</code> | | iOS-only options that specify popover location in iPad. | | ||
@@ -291,3 +341,3 @@ | cameraDirection | <code>[Direction](#module_Camera.Direction)</code> | <code>BACK</code> | Choose the camera to use (front- or back-facing). | | ||
| | --- | --- | --- | --- | | ||
| | DATA_URL | <code>number</code> | <code>0</code> | Return base64 encoded string. DATA_URL can be very memory intensive and cause app crashes or out of memory errors. Use FILE_URI if possible | | ||
| | DATA_URL | <code>number</code> | <code>0</code> | Return data uri. DATA_URL can be very memory intensive and cause app crashes or out of memory errors. Use FILE_URI if possible | | ||
| | FILE_URI | <code>number</code> | <code>1</code> | Return file uri (content://media/external/images/media/2 for Android) | | ||
@@ -419,34 +469,42 @@ | ||
| navigator.camera.getPicture(onSuccess, onFail, { quality: 50, | ||
| destinationType: Camera.DestinationType.FILE_URI }); | ||
| ```javascript | ||
| // Don't forget to install cordova-plugin-file for resolveLocalFileSystemURL! | ||
| function onSuccess(imageURI) { | ||
| var image = document.getElementById('myImage'); | ||
| image.src = imageURI; | ||
| } | ||
| navigator.camera.getPicture(onSuccess, onFail, { quality: 50, | ||
| destinationType: Camera.DestinationType.FILE_URI }); | ||
| function onFail(message) { | ||
| alert('Failed because: ' + message); | ||
| } | ||
| function onSuccess(imageURI) { | ||
| window.resolveLocalFileSystemURL(uri, (entry) => { | ||
| let img = document.getElementById('image'); | ||
| img.src = entry.toURL(); | ||
| }, onFail); | ||
| } | ||
| function onFail(message) { | ||
| alert('Failed because: ' + message); | ||
| } | ||
| ``` | ||
| Take a photo and retrieve it as a Base64-encoded image: | ||
| /** | ||
| * Warning: Using DATA_URL is not recommended! The DATA_URL destination | ||
| * type is very memory intensive, even with a low quality setting. Using it | ||
| * can result in out of memory errors and application crashes. Use FILE_URI | ||
| * instead. | ||
| */ | ||
| navigator.camera.getPicture(onSuccess, onFail, { quality: 25, | ||
| destinationType: Camera.DestinationType.DATA_URL | ||
| }); | ||
| ```javascript | ||
| /** | ||
| * Warning: Using DATA_URL is not recommended! The DATA_URL destination | ||
| * type is very memory intensive, even with a low quality setting. Using it | ||
| * can result in out of memory errors and application crashes. Use FILE_URI | ||
| * instead. | ||
| */ | ||
| navigator.camera.getPicture(onSuccess, onFail, { quality: 25, | ||
| destinationType: Camera.DestinationType.DATA_URL | ||
| }); | ||
| function onSuccess(imageData) { | ||
| var image = document.getElementById('myImage'); | ||
| image.src = "data:image/jpeg;base64," + imageData; | ||
| } | ||
| function onSuccess(imageData) { | ||
| var image = document.getElementById('myImage'); | ||
| image.src = imageData; | ||
| } | ||
| function onFail(message) { | ||
| alert('Failed because: ' + message); | ||
| } | ||
| function onFail(message) { | ||
| alert('Failed because: ' + message); | ||
| } | ||
| ``` | ||
@@ -472,3 +530,3 @@ #### Preferences (iOS) | ||
| Can only return photos as Base64-encoded image. | ||
| Can only return photos as data URI image. | ||
@@ -482,5 +540,7 @@ #### iOS Quirks | ||
| setTimeout(function() { | ||
| // do your thing here! | ||
| }, 0); | ||
| ```javascript | ||
| setTimeout(function() { | ||
| // do your thing here! | ||
| }, 0); | ||
| ``` | ||
@@ -499,7 +559,2 @@ ## `CameraOptions` Errata <a name="CameraOptions-quirks"></a> | ||
| #### iOS Quirks | ||
| - When using `destinationType.FILE_URI`, photos are saved in the application's temporary directory. The contents of the application's temporary directory is deleted when the application ends. | ||
| [android_lifecycle]: http://cordova.apache.org/docs/en/dev/guide/platforms/android/lifecycle.html | ||
@@ -653,5 +708,5 @@ | ||
| If you want to do something like copy the image to another location, or upload it somewhere using the FileTransfer plugin, you need to get a FileEntry object for the returned picture. To do that, call `window.resolveLocalFileSystemURL` on the file URI returned by the Camera app. If you need to use a FileEntry object, set the `destinationType` to `Camera.DestinationType.FILE_URI` in your CameraOptions object (this is also the default value). | ||
| If you want to do something like copy the image to another location, or upload it somewhere, an `FileEntry` is needed for the returned picture. To do this, call `window.resolveLocalFileSystemURL` on the file URI returned by the Camera app. If you need to use a FileEntry object, set the `destinationType` to `Camera.DestinationType.FILE_URI` in your CameraOptions object (this is also the default value). | ||
| >*Note* You need the [File plugin](https://www.npmjs.com/package/cordova-plugin-file) to call `window.resolveLocalFileSystemURL`. | ||
| __NOTE:__ You need the [File plugin](https://www.npmjs.com/package/cordova-plugin-file) to call `window.resolveLocalFileSystemURL`. | ||
@@ -664,37 +719,24 @@ Here is the call to `window.resolveLocalFileSystemURL`. The image URI is passed to this function from the success callback of `getPicture`. The success handler of `resolveLocalFileSystemURL` receives the FileEntry object. | ||
| // Do something with the FileEntry object, like write to it, upload it, etc. | ||
| // writeFile(fileEntry, imgUri); | ||
| console.log("got file: " + fileEntry.fullPath); | ||
| // displayFileData(fileEntry.nativeURL, "Native URL"); | ||
| // Example 1: Copy to app data directory | ||
| window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dataDirectoryEntry) { | ||
| fileEntry.copyTo(dataDirectoryEntry, "profilePic", onSuccess, onError); | ||
| }, onError); | ||
| // Example 2: Upload it! | ||
| fileEntry.file(function (file) { | ||
| var reader = new FileReader(); | ||
| reader.onloadend = function() { | ||
| var xhr = new XMLHttpRequest(); | ||
| xhr.open('POST', 'https://myserver.com/upload'); | ||
| xhr.onload = function () { | ||
| // All done! | ||
| }; | ||
| xhr.send(this.result); | ||
| }; | ||
| }, function () { | ||
| // If don't get the FileEntry (which may happen when testing | ||
| // on some emulators), copy to a new FileEntry. | ||
| createNewFileEntry(imgUri); | ||
| }); | ||
| reader.readAsArrayBuffer(file); | ||
| }, onError); | ||
| }, onError); | ||
| } | ||
| ``` | ||
| In the example shown in the preceding code, you call the app's `createNewFileEntry` function if you don't get a valid FileEntry object. The image URI returned from the Camera app should result in a valid FileEntry, but platform behavior on some emulators may be different for files returned from the file picker. | ||
| >*Note* To see an example of writing to a FileEntry, see the [File plugin README](https://www.npmjs.com/package/cordova-plugin-file). | ||
| The code shown here creates a file in your app's cache (in sandboxed storage) named `tempFile.jpeg`. With the new FileEntry object, you can copy the image to the file or do something else like upload it. | ||
| ```js | ||
| function createNewFileEntry(imgUri) { | ||
| window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) { | ||
| // JPEG file | ||
| dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) { | ||
| // Do something with it, like write to it, upload it, etc. | ||
| // writeFile(fileEntry, imgUri); | ||
| console.log("got file: " + fileEntry.fullPath); | ||
| // displayFileData(fileEntry.fullPath, "File copied to"); | ||
| }, onErrorCreateFile); | ||
| }, onErrorResolveUrl); | ||
| } | ||
| ``` |
@@ -23,2 +23,37 @@ <!-- | ||
| ### 8.0.0 (Oct 30, 2024) | ||
| **Breaking Changes:** | ||
| * [GH-889](https://github.com/apache/cordova-plugin-camera/pull/889) fix(android): Remove media permissions to make complaint with **Android** 14 requirements (#889) | ||
| * [GH-902](https://github.com/apache/cordova-plugin-camera/pull/902) fix(android): return content uris when possible when selecting from gallery (#902) | ||
| * [GH-909](https://github.com/apache/cordova-plugin-camera/pull/909) refactor(android): Make WRITE_EXTERNAL_STORAGE optional (#909) | ||
| * [GH-910](https://github.com/apache/cordova-plugin-camera/pull/910) fix(android): Return data uris as an URI (#910) | ||
| * [GH-911](https://github.com/apache/cordova-plugin-camera/pull/911) fix(ios): Sync camera API return to match **Android** changes (#911) | ||
| * [GH-912](https://github.com/apache/cordova-plugin-camera/pull/912) fix(browser): Make data uri be returned as actual URI strings (#912) | ||
| **Fixes**: | ||
| * [GH-901](https://github.com/apache/cordova-plugin-camera/pull/901) fix(android): Isolate provider access to a subdirectory (#901) | ||
| * [GH-915](https://github.com/apache/cordova-plugin-camera/pull/903) fix(android): Improper serialization of image uri in save instance state (#903) | ||
| * [GH-904](https://github.com/apache/cordova-plugin-camera/pull/904) fix(android): Use VERSION_CODES instead of hard-coded API literals (#904) | ||
| * [GH-915](https://github.com/apache/cordova-plugin-camera/pull/905) fix(android): improper cache path construction during image manipulation (#905) | ||
| * [GH-906](https://github.com/apache/cordova-plugin-camera/pull/906) refactor(android): replace image path usage with image uris (#906) | ||
| * [GH-915](https://github.com/apache/cordova-plugin-camera/pull/907) refactor(android): remove query img usage (#907) | ||
| * [GH-915](https://github.com/apache/cordova-plugin-camera/pull/915) fix!: Remove WRITE_EXTERNAL_PERMISSION (#915) | ||
| **CI**: | ||
| * [GH-890](https://github.com/apache/cordova-plugin-camera/pull/890) ci(android): Update **Android** CI to be compatible with `cordova-android`@13 (#890) | ||
| * [GH-895](https://github.com/apache/cordova-plugin-camera/pull/895) ci: sync workflow with paramedic (#895) | ||
| **Documentation**: | ||
| * [GH-913](https://github.com/apache/cordova-plugin-camera/pull/913) docs: Revisions for v8 public API changes with the return string formats of getPicture (#913) | ||
| **Other**: | ||
| * [GH-898](https://github.com/apache/cordova-plugin-camera/pull/898) chore: Update eslint config to 5.1.0 (#898) | ||
| * [GH-914](https://github.com/apache/cordova-plugin-camera/pull/914) deprecation: allowEdit (#914) | ||
| ### 7.0.0 (Sep 06, 2023) | ||
@@ -25,0 +60,0 @@ |
@@ -42,3 +42,3 @@ /* | ||
| return success(imageData.substr(imageData.indexOf(',') + 1)); | ||
| return success(imageData); | ||
| }; | ||
@@ -82,4 +82,3 @@ | ||
| // convert image stored in canvas to base64 encoded image | ||
| let imageData = canvas.toDataURL('image/png'); | ||
| imageData = imageData.replace('data:image/png;base64,', ''); | ||
| const imageData = canvas.toDataURL('image/png'); | ||
@@ -86,0 +85,0 @@ // stop video stream, remove video and button. |
@@ -146,2 +146,6 @@ /* | ||
| if (allowEdit) { | ||
| console.warn('allowEdit is deprecated. It does not work reliably on all platforms. Utilise a dedicated image editing library instead. allowEdit functionality is scheduled to be removed in a future release.'); | ||
| } | ||
| const args = [quality, destinationType, sourceType, targetWidth, targetHeight, encodingType, | ||
@@ -148,0 +152,0 @@ mediaType, allowEdit, correctOrientation, saveToPhotoAlbum, popoverOptions, cameraDirection]; |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by1.44%
297227
- Lines of code
- increased by0.29%
683
- Number of lines in readme file
- increased by6.1%
730
Worsened metrics
- Number of medium supply chain risk alerts
- increased byInfinity%
1
No dependency changes