Camera プラグイン

プラグイン

このプラグインでは、グローバルオブジェクト 「 navigator.camera 」 の API を使用し、システム側の画像ライブラリーからの画像の取得、および、写真撮影を行います。

このプラグインの詳細は、こちら ( GitHub ) をご確認ください。

このオブジェクトは、グローバルスコープ ( navigator ) に属しています。 使用できるのは、 deviceready イベントの発火後になります。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.camera);
}

プラグイン ID

cordova-plugin-camera

プラグインの追加方法

このプラグインを使用する場合には、Monaca クラウド IDE の [ Cordova プラグインの管理 ] 上で、Camera プラグインを有効にします。

iOS 特有の動作

iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 info.plist に使用の説明を設定することが必須になります。アクセスを許可するようにシステムに指示すると、この使用の説明はアクセス許可ダイアログボックスの一部として表示されますが、使用の説明を入力しない場合は、ダイアログが表示される前にアプリが強制終了します。また、Apple は個人データにアクセスするアプリをリジェクトしますが、使用の説明は提供していません。

このプラグインでは、次の使用の説明が必要になります。

• NSCameraUsageDescription には、アプリがユーザーのカメラにアクセスする理由を記述します。

• NSPhotoLibraryUsageDescription には、アプリがユーザーの写真ライブラリにアクセスする理由を記述します。

• NSLocationWhenInUseUsageDescription には、アプリがユーザーの位置情報にアクセスする理由を記述します。 (CameraUsesGeolocation が true に設定されている場合に設定します)

• NSPhotoLibraryAddUsageDescription には、アプリがユーザーの写真ライブラリに書き込みアクセスを許可する理由を記述します。

これらの設定を info.plist に追加するには、config.xml ファイルの <edit-config> タグに以下のように設定します。

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

<edit-config target="NSPhotoLibraryAddUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to save pictures there</string>
</edit-config>

API の解説

• Camera

  • .getPicture(successCallback, errorCallback, options)

  • .cleanup()

  • .onError : 関数

  • .onSuccess : 関数

  • .CameraOptions : オブジェクト

• Camera

  • .DestinationType : 列挙型

  • .EncodingType : 列挙型

  • .MediaType : 列挙型

  • .PictureSourceType : 列挙型

  • .PopoverArrowDirection : 列挙型

  • .Direction : 列挙型

• CameraPopoverHandle

• CameraPopoverOptions

Camera

camera.getPicture(successCallback, errorCallback, options)

カメラでの写真撮影、または、端末の画像ギャラリーから、画像を取得します。画像は、Base64 形式の 文字列 として、または、画像ファイルを指す URI として、成功時のコールバック関数に引き渡されます。

camera.getPicture 関数では、端末にインストールされている標準のカメラアプリを起動させます ( Camera.sourceType が Camera.PictureSourceType.CAMERA に設定されている場合の動作 )。写真撮影後は、カメラアプリが終了し、使用していたアプリ ( カメラアプリの起動前になんらかのアプリを使用していた場合 ) が開きます。

Camera.sourceType が Camera.PictureSourceType.PHOTOLIBRARY、または、Camera.PictureSourceType.SAVEDPHOTOALBUM の場合、画像選択用のダイアログが表示され、既存の画像があれば、その中から選択できます。

戻り値は、cameraSuccess コールバック関数に渡されます。戻り値は、 cameraOptions の設定に応じて、次のいずれかの形式で返されます。

• 文字列 : Base64 形式でエンコードされた写真画像

• 文字列 : 画像ファイルの保存場所 ( ローカルのストレージ内、デフォルトはこちら )

上記の値 ( エンコードされた画像、または、URI ) を使用して、次のような、さまざまな処理ができます。

• <img> タグ内への画像のレンダリング ( このページ内にサンプルがあります )

• ローカルへのデータの保存 ( LocalStorageLawnchair など )

• 外部サーバーへのデータの送信

最新の端末で撮影した写真の解像度は高くなります。端末のギャラリーから取得する画像は、 quality パラメーターで画質を指定しても、解像度の低い画像に変換されません。メモリー問題を回避するためには、Camera.destinationType を、 DATA_URL ではなく、 FILE_URI に設定します。

例は こちら。 各 OS 特有の動作は こちら。

パラメーター	型	解説
successCallback	関数	onSuccess
errorCallback	関数	onError
options	JSON オブジェクト	CameraOptions

例

navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);

camera.cleanup()

camera.getPicture を呼び出した後に取得し、一時的なストレージに保存されている処理前の画像ファイルを削除します。Camera.sourceType の値と Camera.PictureSourceType.CAMERA が等しく、また、 Camera.destinationType が Camera.DestinationType.FILE_URI と等しい場合のみ有効です。

対象プラットフォーム

• iOS

例

navigator.camera.cleanup(onSuccess, onFail);

function onSuccess() {
    console.log("Camera cleanup success.")
}

function onFail(message) {
    alert('Failed because: ' + message);
}

camera.onError

エラーメッセージを出力するコールバック関数です。

パラメーター	型	解説
message	文字列	端末のネイティブコード側で message が出力され、送られてきます。

camera.onSuccess

画像データを返すコールバック関数です。

パラメーター	型	解説
imageData	文字列	画像データは Base64 エンコード形式です。または、画像ファイルを指し示す File URL が使用されます。どちらになるかは、 cameraOptions の設定次第です。

例

// Show image
function cameraCallback(imageData) {
   var image = document.getElementById('myImage');
   image.src = "data:image/jpeg;base64," + imageData;
}

camera.CameraOptions

カメラの設定をカスタマイズするオプションのパラメーターです。

• 各 OS 特有の動作

プロパティ

名前	型	デフォルト値	解説
quality	数値	50	保存時の画像の画質です。0 から 100 の間で設定します。100 に設定した場合、フル解像度 ( ファイル圧縮によるロスはなし ) となります。なお、カメラ側の解像度に関する情報は取得できません。
destinationType	DestinationType	FILE_URI	戻り値の形式を選択します。
sourceType	PictureSourceType	CAMERA	画像の取得先を設定します。
allowEdit	真偽値	true	画像の選択前に、簡単な編集を許可します。
encodingType	EncodingType	JPEG	返される画像ファイルのエンコード方式を選択します。
targetWidth	数値		画像を拡大・縮小するための幅を、ピクセルで指定します。 targetHeight と共に使用します。アスペクト比は、一定に保持されます。
targetHeight	数値		画像を拡大・縮小するための縦の長さを、ピクセルで指定します。 targetWidth と共に使用します。アスペクト比は、一定に保持されます。
mediaType	MediaType	PICTURE	画像の取得元のメディアの種類を指定します。 PictureSourceType に PHOTOLIBRARY または SAVEDPHOTOALBUM が指定されている場合のみ、この設定が有効です。
correctOrientation	真偽値		キャプチャー時の端末の向きになるように、画像を回転させます。
saveToPhotoAlbum	真偽値		キャプチャー後、端末のフォトアルバムに、画像を保存します。
popoverOptions	CameraPopoverOptions		iOS 専用のオプションです。iPad でのポップオーバー ( popover ) の位置を指定します。
cameraDirection	Direction	BACK	使用するカメラを選択します ( 前面または背面のカメラ )

Camera

Camera.DestinationType

Camera.getPicture の出力形式を定義します。

iOSでは、 DestinationType.NATIVE_URI と PictureSourceType.PHOTOLIBRARY または PictureSourceType.SAVEDPHOTOALBUM を渡した場合、仕様により画像の変更（サイズ変更、品質の変更、切り取りなど）が無効になります。

プロパテ

名前	型	デフォルト	解説
DATA_URL	数値	0	base64でエンコードされた文字列を返します。 DATA_URL は、多くのメモリを消費するため、アプリがクラッシュしたり、メモリ不足の原因となる可能性があります。 可能であれば、FILE_URI または NATIVE_URI を使用します。
FILE_URI	数値	1	File URI を返します ( Android では、 content://media/external/images/media/2 )
NATIVE_URI	数値	2	ネイティブ側を指す URI を返します ( iOS では、 asset-library:// )

Camera.EncodingType

プロパティ

名前	型	デフォルト	解説
JPEG	数値	0	JPEG 形式の画像を返します。
PNG	数値	1	PNG 形式の画像を返します。

Camera.MediaType

プロパティ

名前	型	デフォルト	解説
PICTURE	数値	0	静止画を選択できます。こちらがデフォルト設定となります。戻り値は、 DestinationType で設定されている形式です。
VIDEO	数値	1	ビデオを選択できます。戻り値は、URL です。
ALLMEDIA	数値	2	メディアの種類を選択できます。

Camera.PictureSourceType

Camera.getPicture の出力形式を定義します。

iOSでは、DestinationType.NATIVE_URI と PictureSourceType.PHOTOLIBRARY または PictureSourceType.SAVEDPHOTOALBUM を渡した場合、仕様により画像の変更（サイズ変更、品質の変更、切り取りなど）が無効になります。

プロパティ

名前	型	デフォルト	解説
PHOTOLIBRARY	数値	0	写真のライブラリーから画像を選択できます ( Android の SAVEDPHOTOALBUM に相当 )。
CAMERA	数値	1	カメラから写真を取得します。
SAVEDPHOTOALBUM	数値	2	カメラロールからのみ画像を選択します（ Android の PHOTOLIBRARY に相当 ）。

Camera.PopoverArrowDirection

iOS の UIPopoverArrowDirection に相当します。ポップオーバーの矢印の位置を指定します。

プロパティ

名前	型	デフォルト
ARROW_UP	数値	1
ARROW_DOWN	数値	2
ARROW_LEFT	数値	4
ARROW_RIGHT	数値	8
ARROW_ANY	数値	15

Camera.Direction

プロパティ

名前	型	デフォルト	解説
BACK	数値	0	背面のカメラを使用します。
FRONT	数値	1	前面のカメラを使用します。

CameraPopoverOptions

iOS 専用のパラメーターです。iPad のライブラリまたはフォトアルバムから、画像を選択するときのポップオーバー ( popover ) の位置とその矢印の方向を指定するときに使用します。

画面のオリエンテーション ( および、矢印の表示位置 ) に合うように、ポップオーバーの大きさが修正される場合もあります。「 オリエンテーションは移り変わること 」 を念頭に置いて、矢印の位置を設定することを推奨します。

パラメーター	型	デフォルト	解説
[x]	数値	0	ポップオーバーを置く画面構成要素上の ｘ 座標です ( ピクセル単位 )。
[y]	数値	32	ポップオーバーを置く画面構成要素上の y 座標です ( ピクセル単位 )。
[width]	数値	320	ポップオーバーを置く画面構成要素の幅です ( ピクセル単位 )。
[height]	数値	480	ポップオーバーを置く画面構成要素の高さです ( ピクセル単位 )。
[arrowDir]	PopoverArrowDirection	ARROW_ANY	ポップオーバーに付く矢印の向きです。

CameraPopoverHandle

画像選択用のポップオーバーの処理に使用します。

対象プラットフォーム

• iOS

例

navigator.camera.getPicture(onSuccess, onFail,
{
    destinationType: Camera.DestinationType.FILE_URI,
    sourceType: Camera.PictureSourceType.PHOTOLIBRARY,
    popoverOptions: new CameraPopoverOptions(300, 300, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY)
});

// Reposition the popover if the orientation changes.
window.onorientationchange = function() {
    var cameraPopoverHandle = new CameraPopoverHandle();
    var cameraPopoverOptions = new CameraPopoverOptions(0, 0, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY);
    cameraPopoverHandle.setPosition(cameraPopoverOptions);
}

camera.getPicture の補足

例

写真撮影および画像ファイルの保存場所を取得します。

navigator.camera.getPicture(onSuccess, onFail, { quality: 50,
    destinationType: Camera.DestinationType.FILE_URI });

function onSuccess(imageURI) {
    var image = document.getElementById('myImage');
    image.src = imageURI;
}

function onFail(message) {
    alert('Failed because: ' + message);
}

写真の撮影時、および、写真 ( Base64 エンコード形式の画像 ) の取得時に使用します。

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 onFail(message) {
    alert('Failed because: ' + message);
}

Camera Plugin 8.0.0以後は、`img.src`に代入するときの `data:image/jpeg:base64,`が不要となります。（必ず外してください）

navigator.camera.getPicture(onSuccess, onFail, { quality: 25,
    destinationType: Camera.DestinationType.DATA_URL
});

function onSuccess(imageData) {
    var image = document.getElementById('myImage');
    image.src = imageData;
}

function onFail(message) {
    alert('Failed because: ' + message);
}

Preference ( iOS が対象 )

CameraUsesGeolocation ( 真偽値、デフォルトは、false )。JPEG 形式の画像をキャプチャーする場合、この値を true に設定すると、EXIF ヘッダー内の位置情報を取得できるようになります。

<preference name="CameraUsesGeolocation" value="false" />

CameraOptions の補足

Android 特有の動作

• cameraDirection にどんな値を設定しても、背面のカメラを使用した撮影になります。

• allowEdit の使用時、Android は想定していた動作をしないことがあります。このため、この設定は使用しないでください。 このプラグインを Android へ実装させた場合には、画像のトリミング処理 ( cropping ) は、端末側のアプリを使用して行う仕組みになっています。ただし、プラグイン側では、ユーザーが選択する編集用アプリに関しては、なんら制御ができないため、このプラグインと相性の悪いアプリをユーザーが選択してしまう場合もあり、このような場合、不具合が生じます。もちろん、端末側のアプリとこのプラグインの相性が合うことも場合によってはありますが ( たとえば、Google Photos )、ごくまれなケースです。もし、画像の編集が必須なアプリを開発している場合、画像編集機能を独自に提供している、サードパーティー製のライブラリー・プラグインを使用することも代替案としてご検討ください。

• Camera.PictureSourceType.PHOTOLIBRARY と Camera.PictureSourceType.SAVEDPHOTOALBUM では、どちらの場合でも、同一のフォトアルバムを表示します。

• quality を 100 に設定、correctOrientation を false に設定、加えて、targetHeight または targetWidth を未設定にした場合、encodingType パラメーターは無視されます。画像の取得先が CAMERA の場合、JPEG ファイル ( システム側のカメラが提供 ) を常に返します。また、PHOTOLIBRARY または SAVEDPHOTOALBUM の場合には、選択されたファイル ( 現状の形式のまま ) が返されます。

iOS 特有の動作

• destinationType.FILE_URI に設定している場合、写真はアプリの temporary/tmp ディレクトリーに保存されます。なお、このディレクトリーのコンテンツは、アプリが終了したときに削除されます。

• destinationType.NATIVE_URI と sourceType.CAMERA に設定している場合、 saveToPhotoAlbum パラメーターに関わらず、写真は、フォトアルバムに保存されます。

• destinationType.NATIVE_URI と sourceType.PHOTOLIBRARY または sourceType.SAVEDPHOTOALBUM を使用すると、すべての編集オプションは無視され、リンクは元の画像に戻されます。

サンプルコード

カメラ操作プラグインでは、端末搭載のカメラアプリを使用した写真撮影の起動、画像選択用ダイアログの表示と画像の選択などを行えます。次の処理を行うコードのサンプルを、下に示します。

• カメラアプリの起動と 写真撮影

• 写真撮影と サムネイル ( 縮小した写真 ) の取得

• 写真撮影と FileEntry オブジェクトの作成

• 写真のライブラリーから ファイルを選択

• 画像 ( JPEG 形式 ) の選択と サムネイル ( 縮小した写真 ) の取得

• 画像の選択と FileEntry オブジェクトの作成

写真の撮影

写真撮影の処理を行う前に、カメラ操作プラグインの getPicture 関数に渡すオプションをいくつか設定します。次のサンプルコード内に推奨のオプションを記述しています。この例では、オプション用に使用するオブジェクトを作成しています。なお、カメラアプリと画像選択用のダイアログの両方をサポートできるように、sourceType は、「 動的 」 に設定することにします。

function setOptions(srcType) {
    var options = {
        // Some common settings are 20, 50, and 100
        quality: 50,
        destinationType: Camera.DestinationType.FILE_URI,
        // In this app, dynamically set the picture source, Camera or photo gallery
        sourceType: srcType,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        allowEdit: true,
        correctOrientation: true  //Corrects Android orientation quirks
    }
    return options;
}

メモリーに起因する問題を避けるため、DATA_URL ではなく、FILE_URI を使用します。なお、Android では、エンコード形式として JPEG を推奨します。

写真撮影時、getPicture の第三引数に、オプション用のオブジェクト ( CameraOptions ) を渡します。また、setOptions の呼び出し時に、写真の取得先を指定する Camera.PictureSourceType.CAMERA を渡します。

function openCamera(selection) {

    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        displayImage(imageUri);
        // You may choose to copy the picture, save it somewhere, or upload.
        func(imageUri);

    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

写真の撮影後は、写真の表示などを含む、さまざまな処理を行えます。この例では、上述のコードの displayImage 内の処理を記述しています。

function displayImage(imgUri) {
    var elem = document.getElementById('imageFile');
    elem.src = imgUri;
}

いくつかのプラットフォームでは、画像を表示する場合、Content-Security-Policy の <meta> 要素に、URI を設定する必要があります。以下は、例になります。

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">

写真の撮影とサムネイル ( 縮小した写真 ) の取得

縮小された画像を取得したい場合には、CameraOptions オブジェクトの targetWidth と targetHeight に、希望するサイズの値を入れて渡します。ここでは、100 x 100px のボックスに収まる画像が返ってくるように設定します ( アスペクト比は保持されるので、ソースの縦または横のどちらか大きい方に 100px が適用されます)。

function openCamera(selection) {
    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    if (selection == "camera-thmb") {
        options.targetHeight = 100;
        options.targetWidth = 100;
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // Do something
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}

写真のライブラリーからファイルを選択

画像選択用のダイアログからファイルを選択する場合、CameraOptions オブジェクトを使用して、ダイアログを表示するよう設定します ( sourceType を Camera.PictureSourceType.SAVEDPHOTOALBUM に設定します )。実際にダイアログを表示させるときには、左記のオプションを指定したオブジェクトを使用して、getPicture を呼び出します。

function openFilePicker(selection) {
    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // Do something
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}

画像の選択とサムネイル ( 縮小した写真 ) の取得

画像選択用のダイアログで選択したファイルを縮小する場合には、上述の方法と同じように、targetHeight と targetWidth を適宜設定します。

function openFilePicker(selection) {
    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    if (selection == "picker-thmb") {
        // To downscale a selected image,
        // Camera.EncodingType (e.g., JPEG) must match the selected image type.
        options.targetHeight = 100;
        options.targetWidth = 100;
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // Do something with image
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

写真の撮影と FileEntry オブジェクトの取得

別の場所への画像のコピー、画像のアップロード ( ファイル転送プラグイン/FileTransfer プラグイン の使用 ) などを行う場合、カメラアプリから返された写真に紐づけされている FileEntry オブジェクトを使用します。オブジェクトを取得する場合には、カメラアプリが返す file URI を使用して、 window.resolveLocalFileSystemURL を呼び出します ( CameraOptions オブジェクト内で、 destinationType を Camera.DestinationType.FILE_URI に設定する必要があります。通常、デフォルトで、この設定になっています )。

window.resolveLocalFileSystemURL を呼ぶためには、 ファイル操作プラグイン ( File プラグイン ) が必要です。

window.resolveLocalFileSystemURL の実行例を次に記します。この関数で使用している image URI は、getPicture の成功時のコールバックから渡されたものです。resolveLocalFileSystemURL の成功時のハンドラーに FileEntry オブジェクトが渡されます。

function getFileEntry(imgUri) {
    window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) {

        // 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");

    }, function () {
      // If don't get the FileEntry (which may happen when testing
      // on some emulators), copy to a new FileEntry.
        createNewFileEntry(imgUri);
    });
}

上記の例では、有効な FileEntry オブジェクトを取得できなかった場合、アプリ側の createNewFileEntry を呼び出しています。カメラアプリが返した image URL を使用すれば、有効な FileEntry を取得できるはずですが、エミュレーターによっては、プラットフォームの動作が異なり、画像選択用のダイアログが返すファイル情報も異なってきます。

FileEntry への書き込み方法は、ファイル操作プラグインの README をご確認ください。

次のコードでは、アプリのキャッシュ用ディレクトリー ( サンドボックス内のストレージ ) 内に、 tempFile.jpeg と名付けたファイルを作成しています。新たな FileEntry オブジェクトを使用すれば、さまざまな処理 ( 画像のコピー、アップデートなど ) を行えます。

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);
}