Monaca Docs
質問…
K

バーコードスキャナー

テスト環境(バージョン番号): 1.4.0
このプラグインでは、デバイスのカメラでバーコードやQRコード[^1]を読み取り、 抽出された文字列を取得します。

プラグインID

@monaca/monaca-plugin-scan-barcode

プラグインの追加方法

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

対象プラットフォーム

ビルド環境

  • Cordova 11.0.0 以降
  • Android プラットフォーム 10.1.2 以降
  • iOS プラットフォーム 6.2.0 以降

動作環境

  • Android 5.1以降 (9以降 推奨)
  • iOS 11以降 (13以降 推奨)

対応するバーコードの種類

  • QR_CODE
  • EAN_8
  • EAN_13
  • ITF
  • CODE_128
  • CODE_39
その他...
  • ver. 1.4.0 では iOS/Android(MLKit) の端末でサポートされている他の形式のバーコードにも対応しました。
  • 前述の形式に加えて、以下のようなバーコード形式に対応しています。
    • CODE_93, AZTEC, DATA_MATRIX, UPC_E, など
  • いくつかの形式は iOS のみ対応しています。
バーコード検出についての注意事項はこちらを参照してください。
一部の端末で正常に動作しない場合があります。
対応状況についてはこちらを参照してください。

機能

スキャンモード

  • Normal モード(v1.0.0〜) 検出されたバーコードが示す文字列が画面に表示されます。これをタップすると画面が閉じられて処理を返します。
  • One Shot モード(v1.1.0〜) バーコードが検出されると自動的にスキャナ画面を閉じて処理を返します。

検出タイムアウトメッセージ(v1.1.0〜)

検出されない状態で一定時間経過すると、指定したメッセージが表示されます。

APIの解説

monaca.BarcodeScanner.scan()

monaca.BarcodeScanner.scan(successCallback, failCallback[, options])
  • scan()を呼び出すとスキャナ画面に遷移します。
  • 検出されたバーコードが示す文字列が枠の下に表示されます。(Normalモード)
  • 文字列をタップすると元の画面に戻り、文字列とバーコードの種類が返されます。
  • One Shotモードの場合、最初に検出されたバーコードの文字列と種類が返され、自動的にスキャナ画面が閉じられます。
  • 文字列を選択していない状態で元の画面に戻ると検出キャンセルとなります。 iOSの場合は「閉じる」(画面上のX)ボタン、Androidの場合は「戻る」ボタンで元の画面へ遷移します。

successCallback

successCallback(result)
result: 以下のデータが返されます。
{
data: {
"text": "xxxxxxxx" // 検出された文字列
"format": "QR_CODE" // バーコードの種類
},
cancelled: false // 検出がキャンセルされたかどうか
}

failCallback

failCallback(error)
error: エラーメッセージ(文字列)
message
description
permission denied
camera permission is not granted.

options

{
"oneShot" : true,
"timeoutPrompt" : {
"show" : true,
"timeout" : 5,
"prompt" : "Not detected"
},
"debug" : {
"preview" : 0
}
}
parameter
type
default value
description
oneShot
boolean
false
One Shot モード有効/無効
timeoutPrompt.show
boolean
false
検出タイムアウトメッセージ 表示/非表示
timeoutPrompt.timeout
int
-
メッセージが表示されるまでの時間(秒)
timeoutPrompt.prompt
string
"Barcode not detected"
検出タイムアウトメッセージ
debug.preview (android only)
int
0
デバッグプレビューモード(Androidのみ) スキャン画面にバーコード検出直前の画像を表示 0: OFF(default) 1: 検出エリア内部 2: カメラプレビュー全体

monaca.BarcodeScanner.scan((result) => {
if (result.cancelled) {
// scan cancelled
} else {
// scan
const detected_text = result.data.text;
const detected_format = result.data.format;
}
}, (error) => {
// permission error
const error_message = error;
}, {
"oneShot" : true,
"timeoutPrompt" : {
"show" : true,
"timeout" : 5,
"prompt" : "Not detected"
}
});

iOS 特有の動作

iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 info.plist にデータにアクセスする説明が必須になります。 この説明文は、アクセス許可ダイアログに表示されます。
このプラグインでは、次の使用説明が必要になります。
  • NSCameraUsageDescription :アプリがユーザーのカメラにアクセスする理由を記述します
設定を info.plist に追加するには、config.xml ファイルの <edit-config> タグに以下のように設定します。
<platform name="ios">
<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
<string>need camera access to scan barcode</string>
</edit-config>
</platform>

Android 特有の動作

compileSDKVersion

内部で使用するライブラリandroidx.camera:camera-viewcompileSDKVersion>=31を必要としています。 このため、Monaca クラウド IDE の [ Androidアプリ設定 ] でターゲットSDKバージョンを31以上に設定する必要があります。

端末の機種依存に起因するバーコード検出の問題

このプラグインはカメラでキャプチャした画像(ImageProxy)を変換し、バーコード検出ライブラリ(MLKit)に渡すことでバーコードを検出しています。 ImageProxyには様々なフォーマットの画像を格納することができ、カメラがどのようなフォーマットでキャプチャするのかは端末に依存しています。 一部の端末では、プラグインが対応していない形式でキャプチャされることによりバーコードの検出に失敗する場合があります。

プラグインの対応状況

バージョン
対応フォーマット
〜ver.1.2.1
- JPEG および YUV_420_888 フォーマットに対応 - プレーンバッファのrowStrideImageWidth と同じ場合のみ対応
ver.1.3.0
- プレーンバッファのrowStrideImageWidthと異なる場合に対応

対応していない画像形式の確認方法

ver.1.3.0 で追加されたデバッグプレビュー機能を用いることでデバイスの対応状況を確認することができます。
  • optionsでデバッグプレビューをONに設定してください。
monaca.BarcodeScanner.scan((result) => {
if (result.cancelled) {
// scan cancelled
} else {
// scan
}
}, (error) => {
// permission error
const error_message = error;
}, {
"debug" : {
"preview" : 1
}
});
  • スキャン画面に、バーコード検出直前の画像がサムネイル表示されます。
このサムネイル画像が乱れて表示されている場合は対応していないデバイスとなります。

バーコード検出について

ITFコード (ver.1.2.0〜)

  • ver. 1.2.0
    • iOSでは14桁のITF-14のみ検出することができます。
    • Android では様々な桁数のITFコードが検出されます。
  • ver. 1.4.0
    • iOSでも14桁以外のITFコードに対応しました。

その他のバーコード

  • いくつかのバーコードは「桁落ち(誤検出)」の発生しやすい規格のため、バーコードを枠内に正確に収めてスキャンして頂く必要があります。

[^1]: QRコードは(株)デンソーウェーブの登録商標です。