Call the SuperApp:Camera JavaScript API to take, select, and upload photos - SuperApp:Camera - Alibaba Cloud - SuperApp

Documents the JavaScript APIs (JSAPIs) for the WVCamera class, which lets you add camera features — including taking photos, selecting photos from the album, and multiple photo selection — to H5 applications and mini programs.

WVCamera.takePhoto

WVCamera.takePhoto prompts the user to take a photo with the camera or select one from the album. Use the returned photo path to implement an upload feature in your mini program.

Important

On iOS 11 and later, add the NSPhotoLibraryAddUsageDescription permission to your client before accessing the album.

The following example shows a basic call using the default mode:

var photoLocalPath; // Stores the local file path.
var params = {
        mode: 'both',
};
window.WindVane.call('WVCamera', 'takePhoto', params, function(e) {
     var uploadParams = {
              // The path of the photo to be uploaded
              path: e.localPath
      };
      // Implement your own logic to send the formData to a backend service for file storage.
      ...
      ...
}, function(e) {
        alert('takePhoto failure: ' + JSON.stringify(e));
});

Input parameters

[string] mode: Optional. Specifies the photo source. 'camera' opens the device camera only. 'photo' opens the album only. The default, 'both', lets the user choose between the camera and the album.
[boolean] compatible: Optional. Set to true when calling this method after presenting a mini program.

Callback parameters

The success callback runs when a photo is obtained. The failure callback runs when the operation fails or the user cancels.

Success callback parameters:

[string] url: A preview URL for the photo. Assign it to the src attribute of an img element to display the photo.

Important
This is not a real Content Delivery Network (CDN) URL and cannot be accessed directly from a browser.
[string] localPath: The local file path of the photo. Use this path for upload — for example, with WVCamera.confirmUploadPhoto.
[string] identifier: The photo identifier. Returned when uploading via Mtop (v = '2.0'), echoing the identifier from the input parameters.
[string] base64Data: The Base64-encoded image data. Returned only when needBase64 = true is set. Prepend data:image/png;base64, before using the value. Requires VER.WindVane 8.0.0 or later.

Failure callback parameters:

[string] errorType: The error type.
[string] errorCode: The error code.
[string] errorMsg: The error message.
[string] identifier: The photo identifier. Returned when uploading via Mtop (v = '2.0'), echoing the identifier from the input parameters.

Note

If the user cancels, the failure callback runs with {ret:'HY_RET_PHOTO_CANCLE'} on iOS and {ret:'HY_FAILED'} on Android — no other parameters are returned. If the app lacks permission to access the camera or album, the failure callback also runs and the returned parameters include {msg:'NO_PERMISSION'}.

Event listeners

WVPhoto.Event.takePhotoSuccess

Fires after a photo is obtained and before it is uploaded. JavaScript can preview the photo on the page at this point.

Event parameters:

[string] url: A preview URL for the photo. Assign it to the src attribute of an img element to display the photo.

Important
This is not a real CDN URL and cannot be accessed directly from a browser.
[string] localPath: The local file path. Use this path for the upload.

Multiple selection mode

Note

For WindVane on iOS only.

Multiple selection mode lets users pick and upload several photos at once from the album. It is available only for WindVane on iOS. If the user switches to the camera source, the API falls back to single-photo mode. Pass mode: 'photo' to go directly to the album and keep multiple selection behavior.

Input parameters

[string] mutipleSelection: Optional. Enables multiple selection mode. '1' enables it; '0' disables it. Default: '0'.
[int] maxSelect: Optional. Maximum number of photos the user can select. Default: 9.

Callback parameters

The success callback runs when photos are obtained. The failure callback runs when the operation fails or the user cancels.

Success callback parameters:

[array] images: An array of the selected photos. Each item contains:
- [string] url: A preview URL for the photo. Assign it to the src attribute of an img element to display the photo.
  
  Important
  This is not a real CDN URL and cannot be accessed directly from a browser.
- [string] localPath: The local file path of the photo. Use this path for a subsequent upload, such as with WVCamera.confirmUploadPhoto.

Failure callback parameters:

[string] errorType: The error type.
[string] errorCode: The error code.
[string] errorMsg: The error message.
[string] identifier: The photo identifier. Returned when uploading via Mtop (v = '2.0'), echoing the identifier from the input parameters.

Important

Event listeners

WVPhoto.Event.takePhotoSuccess: Fires after photos are obtained and before they are uploaded. JavaScript can preview each photo on the page at this point.

Event parameters:

[string] url: A preview URL for the photo. Assign it to the src attribute of an img element to display the photo.

Important
This is not a real CDN URL and cannot be accessed directly from a browser.
[string] localPath: The local file path. Use this path for the upload (WindVane on Android only).

The following two events fire only during immediate uploads triggered right after photo selection:

WVPhoto.Event.uploadPhotoSuccess: Fires each time a photo is successfully uploaded.

Event parameters:

[string] url: A preview URL for the photo. Assign it to the src attribute of an img element to display the photo.

Important
This is not a real CDN URL and cannot be accessed directly from a browser.
[string] localPath: The local file path of the photo. Use this path to get file data for later uploads.
[string] identifier: The photo identifier. Returned when uploading via Mtop (v = '2.0'), echoing the identifier from the input parameters.

WVPhoto.Event.uploadPhotoFailed: Fires each time a photo fails to upload.

Event parameters:

[string] errorType: The error type.
[string] errorCode: The error code.
[string] errorMsg: The error message.
[string] identifier: The photo identifier. Returned when uploading via Mtop (v = '2.0'), echoing the identifier from the input parameters.

document.addEventListener('WVPhoto.Event.uploadPhotoSuccess', function (e) {
        alert('event uploadPhotoSuccess: ' + JSON.stringify(e.param));
});
document.addEventListener('WVPhoto.Event.uploadPhotoFailed', function (e) {
        alert('event uploadPhotoFailed: ' + JSON.stringify(e.param));
});

var params = {
        // Specifies whether to automatically upload photos after selection.
        type: '1',
        // Specifies if the source is limited to the camera or the album.
        mode: 'photo',
        // The upload method.
        v: '2.0',
        // Specifies whether to use multiple selection mode.
        mutipleSelection: '1',
        // Maximum number of photos for multiple selection mode.
        maxSelect: 6
};
window.WindVane.call('WVCamera', 'takePhoto', params, function(e) {
        alert('takePhoto success: ' + JSON.stringify(e));
}, function(e) {
        alert('takePhoto failure: ' + JSON.stringify(e));
});