cordova-plugin-camera

このプラグインは、写真を撮ったり、システムの画像ライブラリから画像を選択したりするためのAPIを提供するグローバルな`navigator.camera`オブジェクトを定義します。

オブジェクトはグローバルスコープの`navigator`にアタッチされていますが、`deviceready`イベントが発生するまでは利用できません。

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

インストール

cordova plugin add cordova-plugin-camera

リポジトリURLから直接インストールすることも可能です（不安定）

cordova plugin add https://github.com/apache/cordova-plugin-camera.git

プラグイン変数

このプラグインは、`ANDROIDX_CORE_VERSION`変数を使用して`androidx.core:core`依存関係を設定します。これにより、依存関係がハードコードされている他のプラグインとの競合を回避できます。値が渡されない場合は、デフォルト値として`1.6.+`が使用されます。

変数はインストール時に設定されます

cordova plugin add cordova-plugin-camera --variable ANDROIDX_CORE_VERSION=1.8.0

貢献する方法

貢献者は歓迎です！そして、プロジェクトを進めていくためには、皆さんの貢献が必要です。バグを報告したり、ドキュメントを改善したり、コードを提供したりすることができます。

推奨される特定の貢献者ワークフローがあります。まずはそこから読んでください。詳細については、Wikiをご覧ください。

**解決策がありますか？** プルリクエストを送信してください。

変更を受け入れるには、Apache ICLA（個人貢献者ライセンス契約）に署名して提出する必要があります。その後、あなたの名前は、非コミッターまたはCordovaコミッターによって署名されたCLAのリストに表示されます。

コードのテストとドキュメント化を忘れないでください。

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 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 photo library access to save pictures there</string>
</edit-config>

APIリファレンス

• camera
  • .getPicture(successCallback, errorCallback, options)
  • .cleanup()
  • .onError : `function`
  • .onSuccess : `function`
  • .CameraOptions : `Object`
• カメラ
  • .DestinationType : `enum`
  • .EncodingType : `enum`
  • .MediaType : `enum`
  • .PictureSourceType : `enum`
  • .PopoverArrowDirection : `enum`
  • .Direction : `enum`
• CameraPopoverHandle
• CameraPopoverOptions

camera

camera.getPicture(successCallback, errorCallback, options)

カメラを使用して写真を撮るか、デバイスの画像ギャラリーから写真を取り出します。画像は、Base64エンコードされた`String`として、または画像ファイルのURIとして、成功コールバックに渡されます。

`camera.getPicture`関数は、デフォルトでユーザーが写真を撮ることができるデバイスのデフォルトのカメラアプリケーションを開きます。この動作は、`Camera.sourceType`が`Camera.PictureSourceType.CAMERA`と等しい場合に発生します。ユーザーが写真を撮ると、カメラアプリケーションが閉じ、アプリケーションが復元されます。

`Camera.sourceType`が`Camera.PictureSourceType.PHOTOLIBRARY`または`Camera.PictureSourceType.SAVEDPHOTOALBUM`の場合、ユーザーが既存の画像を選択できるダイアログが表示されます。

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

• Base64エンコードされた写真画像を含む`String`。
• ローカルストレージ上の画像ファイルの場所を表す`String`（デフォルト）。

エンコードされた画像またはURIを使用して、以下の例のように、何でもすることができます。

• 以下の例のように、`<img>`タグで画像をレンダリングします
• データをローカルに保存します（`LocalStorage`、Lawnchairなど）
• データをリモートサーバーに投稿します

**注**：新しいデバイスの写真の解像度は非常に優れています。デバイスのギャラリーから選択した写真は、`quality`パラメータが指定されていても、低品質にダウンスケールされません。一般的なメモリの問題を回避するには、`Camera.destinationType`を`DATA_URL`ではなく`FILE_URI`に設定します。

サポートされているプラットフォーム

• Android
• ブラウザ
• iOS

その他の例はこちら。癖はこちら。

**種類**：`[camera](#module_camera)`の静的メソッド

例

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

camera.cleanup()

`camera.getPicture`を呼び出した後に一時ストレージに保持される中間画像ファイルを削除します。`Camera.sourceType`の値が`Camera.PictureSourceType.CAMERA`と等しく、`Camera.destinationType`が`Camera.DestinationType.FILE_URI`と等しい場合にのみ適用されます。

サポートされているプラットフォーム

• iOS

**種類**：`[camera](#module_camera)`の静的メソッド
例

navigator.camera.cleanup(onSuccess, onFail);

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

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

camera.onError : `function`

エラーメッセージを提供するコールバック関数。

**種類**：`[camera](#module_camera)`の静的typedef

camera.onSuccess : `function`

画像データを提供するコールバック関数。

**種類**：`[camera](#module_camera)`の静的typedef

例

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

camera.CameraOptions : `Object`

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

• 癖

**種類**：`[camera](#module_camera)`の静的typedef
プロパティ

カメラ

Camera.DestinationType : `enum`

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

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

Camera.EncodingType : `enum`

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

Camera.MediaType : `enum`

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

Camera.PictureSourceType : `enum`

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

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

Camera.PopoverArrowDirection : `enum`

ポップオーバーの矢印の位置を指定するために、iOS UIPopoverArrowDirection定数と一致します。

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

Camera.Direction : `enum`

**種類**：`[Camera](#module_Camera)`の静的列挙型プロパティ
プロパティ

CameraPopoverOptions

iPadのライブラリまたはアルバムから画像を選択するときの、ポップオーバーのアンカー要素の位置と矢印の方向を指定するiOSのみのパラメータ。ポップオーバーのサイズは、矢印の方向と画面の向きに合わせて変更される場合があります。アンカー要素の位置を指定するときは、向きの変更を考慮してください。

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, 300, 600)
});

// 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, 400, 500);
    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エンコードされた画像として取得する

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

設定（iOS）

• CameraUsesGeolocation（ブール値、デフォルトはfalse）。JPEGをキャプチャする場合、EXIFヘッダーにジオロケーションデータを取得するにはtrueに設定します。trueに設定すると、ジオロケーションの許可が要求されます。

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

Androidの癖

Androidはインテントを使用してデバイスのカメラアクティビティを起動して画像をキャプチャしますが、メモリが少ない電話では、Cordovaアクティビティが強制終了される場合があります。このシナリオでは、プラグイン呼び出しの結果は再開イベントを介して配信されます。詳細については、Androidライフサイクルガイドを参照してください。 pendingResult.resultの値には、コールバックに渡される値（URI / URLまたはエラーメッセージ）が含まれます。呼び出しが成功したかどうかを確認するには、pendingResult.pluginStatusを確認してください。

ブラウザの癖

写真はBase64エンコードされた画像としてのみ返すことができます。

iOSの癖

いずれかのコールバック関数にJavaScriptのalert()を含めると、問題が発生する可能性があります。アラートがiOSイメージピッカーまたはポップオーバーが完全に閉じるまで表示されないように、setTimeout()内にアラートをラップします。

setTimeout(function() {
    // do your thing here!
}, 0);

CameraOptions エラータ

Androidの癖

• どのcameraDirection値でも、背面向きの写真が生成されます。（=背面カメラのみ使用できます）

• allowEditはAndroidでは予測不可能なため、使用しないでください！ このプラグインのAndroid実装は、画像のトリミングを行うためにユーザーのデバイス上のアプリケーションを見つけようとして使用します。プラグインは、ユーザーが画像のトリミングを実行するために選択したアプリケーションを制御できず、ユーザーが互換性のないオプションを選択してプラグインが失敗する可能性があります。ほとんどのデバイスには、このプラグイン（Googleフォト）と互換性のある方法でトリミングを処理するアプリケーションが付属しているため、これは機能することがありますが、そうであることに頼るのは賢明ではありません。画像編集がアプリケーションに不可欠な場合は、より堅牢なソリューションのために、独自の画像編集ユーティリティを提供するサードパーティのライブラリまたはプラグインを探すことを検討してください。

• Camera.PictureSourceType.PHOTOLIBRARYとCamera.PictureSourceType.SAVEDPHOTOALBUMはどちらも同じフォトアルバムを表示します。

• 画像が編集されていない場合（つまり、qualityが100、correctOrientationがfalse、targetHeightまたはtargetWidthが指定されていない場合）、encodingTypeパラメータは無視されます。 CAMERAソースは常にネイティブカメラによって提供されたJPEGファイルを返し、PHOTOLIBRARYおよびSAVEDPHOTOALBUMソースは選択されたファイルを既存のエンコーディングで返します。

iOSの癖

• destinationType.FILE_URIを使用する場合、写真はアプリケーションの一時ディレクトリに保存されます。アプリケーションの一時ディレクトリのコンテンツは、アプリケーションの終了時に削除されます。

サンプル：写真の撮影、ピクチャライブラリからの写真の選択、サムネイルの取得

カメラプラグインを使用すると、デバイスのカメラアプリを開いて写真を撮ったり、ファイルピッカーを開いてファイルを選択したりするなどの操作を実行できます。このセクションのコードスニペットは、次のようないくつかの異なるタスクを示しています。

• カメラアプリを開いて写真を撮る
• 写真を撮ってサムネイルを返す（サイズ変更された写真）
• 写真を撮って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
    }
    return options;
}

通常、ほとんどのメモリの問題を回避するために、DATA_URLではなくFILE_URIを使用します。JPEGは、Androidに推奨されるエンコードタイプです。

3番目の引数としてCameraOptionsオブジェクトを受け取る`getPicture`にオプションオブジェクトを渡すことで写真を撮ります。 `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;
}

写真を撮ってサムネイルを返す（写真のサイズ変更）

より小さい画像を取得するには、CameraOptionsオブジェクトに`targetHeight`と`targetWidth`の両方の値を渡すことで、サイズ変更された画像を返すことができます。この例では、返された画像のサイズを100px 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`に設定します。ファイルピッカーを開くには、前の例で行ったように、CameraOptionsオブジェクトとともに成功コールバックとエラーコールバックを渡して`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オブジェクトを取得する必要があります。そのためには、カメラアプリから返されたファイルURIで`window.resolveLocalFileSystemURL`を呼び出します。FileEntryオブジェクトを使用する必要がある場合は、CameraOptionsオブジェクトで`destinationType`を`Camera.DestinationType.FILE_URI`に設定します（これもデフォルト値です）。

*注* `window.resolveLocalFileSystemURL`を呼び出すには、ファイルプラグインが必要です。

`window.resolveLocalFileSystemURL`の呼び出しは次のとおりです。画像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`関数を呼び出します。カメラアプリから返された画像URIは、有効な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);
}