# バーコードスキャナー
テスト環境(バージョン番号): 1.6.1
このプラグインでは、デバイスのカメラでバーコードやQRコード[^1]\[^1]を読み取り、 抽出された文字列を取得します。
{% hint style="info" %}
### 重要なお知らせ（2025年対応）
Google Play によって 2025年11月以降に必須となる **「16 KB ページサイズ要件」** に対応するため、 本プラグインは **バージョン 1.6.1 以降**をご利用ください。
既存のプロジェクトで旧バージョンをご利用中の方は、Monaca クラウド IDE の **「Cordovaプラグインの管理」画面**からバーコードスキャナープラグインを選択し、 バージョンを **1.6.1** に変更して保存 → 再ビルドすることで対応可能です。 特別なコード修正は不要です。
{% endhint %}
## プラグインID
```
@monaca/monaca-plugin-barcode-scanner
```
## プラグインの追加方法
このプラグインを使用する場合には、Monaca クラウド IDE の \[ Cordova プラグインの管理 ] 上で、 `Barcode Scanner` プラグインを[有効](https://ja.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#cordova-puraguin-noinpto)にします。
## 対象プラットフォーム
### ビルド環境
* Cordova 11.0.0 以降
* Android プラットフォーム 10.1.2 以降
* iOS プラットフォーム 6.2.0 以降
{% hint style="info" %}
プラグイン バージョン1.4.0以降で使用する場合、開発環境のXcodeをバージョン14.2.0以降にアップデートしてください。
{% endhint %}
### 動作環境
* Android 5.1以降 (9以降 推奨)
* iOS 11以降 (13以降 推奨)
## 対応するバーコードの種類
* QR\_CODE
* EAN\_8
* EAN\_13
* ITF
* CODE\_128
* CODE\_39
その他...
{% hint style="info" %}
* ver. 1.4.0 では iOS/Android(MLKit) の端末でサポートされている他の形式のバーコードにも対応しました。
* 前述の形式に加えて、以下のようなバーコード形式に対応しています。
* CODE\_93, AZTEC, DATA\_MATRIX, UPC\_E, など
* いくつかの形式は iOS のみ対応しています。
{% endhint %}
バーコード検出についての注意事項は[こちら](#about_detecting_barcode)を参照してください。
{% hint style="info" %}
一部の端末で正常に動作しない場合があります。
対応状況については[こちら](#barcode-detection-problem)を参照してください。
{% endhint %}
## 機能
### スキャンモード
* `Normal` モード(v1.0.0〜) \
検出されたバーコードが示す文字列が画面に表示されます。これをタップすると画面が閉じられて処理を返します。
* `One Shot` モード(v1.1.0〜) \
バーコードが検出されると自動的にスキャナ画面を閉じて処理を返します。
### 検出タイムアウトメッセージ(v1.1.0〜)
検出されない状態で一定時間経過すると、指定したメッセージが表示されます。
### トーチ機能(v1.5.0〜)
スマートフォンのトーチライト(LEDライト)をONにすることができます。
## APIの解説
### monaca.BarcodeScanner.scan()
```javascript
monaca.BarcodeScanner.scan(successCallback, failCallback[, options])
```
* `scan()`を呼び出すとスキャナ画面に遷移します。
* 検出されたバーコードが示す文字列が枠の下に表示されます。(`Normal`モード)
* 文字列をタップすると元の画面に戻り、文字列とバーコードの種類が返されます。
* `One Shot`モードの場合、最初に検出されたバーコードの文字列と種類が返され、自動的にスキャナ画面が閉じられます。
* 文字列を選択していない状態で元の画面に戻ると検出キャンセルとなります。\
iOSの場合は「閉じる」(画面上のX)ボタン、Androidの場合は「戻る」ボタンで元の画面へ遷移します。
#### successCallback
`successCallback(result)`
result: 以下のデータが返されます。
```json
{
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"
},
"torch" : {
"enable" : true,
"defaultOn" : false
},
"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" | 検出タイムアウトメッセージ |
| torch.enable | boolean | false | トーチ機能 有効/無効 |
| torch.defaultOn | boolean | false | 起動時のトーチON/OFF |
| debug.preview
(android only)
| int | 0 | デバッグプレビューモード(Androidのみ)
スキャン画面にバーコード検出直前の画像を表示
0: OFF(default)
1: 検出エリア内部
2: カメラプレビュー全体
|
### 例
```java
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"
},
"torch" : {
"enable" : true,
"defaultOn" : false
}
});
```
## iOS 特有の動作
iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 info.plist にデータにアクセスする説明が必須になります。\
この説明文は、アクセス許可ダイアログに表示されます。
このプラグインでは、次の使用説明が必要になります。
* `NSCameraUsageDescription` ：アプリがユーザーのカメラにアクセスする理由を記述します
設定を info.plist に追加するには、`config.xml` ファイルの `` タグに以下のように設定します。
```html
need camera access to scan barcode
```
## Android 特有の動作
### compileSDKVersion
内部で使用するライブラリ`androidx.camera:camera-view` が`compileSDKVersion>=31`を必要としています。 \
このため、Monaca クラウド IDE の \[ Androidアプリ設定 ] で`ターゲットSDKバージョン`を31以上に設定する必要があります。
### 端末の機種依存に起因するバーコード検出の問題
このプラグインはカメラでキャプチャした画像(ImageProxy)を変換し、バーコード検出ライブラリ(MLKit)に渡すことでバーコードを検出しています。 \
ImageProxyには様々なフォーマットの画像を格納することができ、カメラがどのようなフォーマットでキャプチャするのかは端末に依存しています。 \
一部の端末では、プラグインが対応していない形式でキャプチャされることによりバーコードの検出に失敗する場合があります。
#### **プラグインの対応状況**
| バージョン | 対応フォーマット |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 〜ver.1.2.1 | - JPEG および YUV\_420\_888 フォーマットに対応
- プレーンバッファのrowStride が ImageWidth と同じ場合のみ対応
|
| ver.1.3.0 | - プレーンバッファの`rowStride`が`ImageWidth`と異なる場合に対応 |
#### 対応していない画像形式の確認方法
ver.1.3.0 で追加されたデバッグプレビュー機能を用いることでデバイスの対応状況を確認することができます。
* optionsでデバッグプレビューをONに設定してください。
```javascript
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コードは(株)デンソーウェーブの登録商標です。
[^1]: QRコードは(株)デンソーウェーブの登録商標です。