本頁面由 Cloud Translation API 翻譯而成。

在 Android 上使用機器學習套件掃描條碼

您可以使用 ML Kit 來辨識及解碼條碼。

功能	未組合	組合
實作中	模型會透過 Google Play 服務動態下載。	模型會在建構期間以靜態方式連結至應用程式。
應用程式大小	大約大小為 200 KB。	大小上限為 2.4 MB。
初始化時間	可能必須先等待模型下載才能使用。	可立即使用型號。

立即體驗

如要查看此 API 的範例，請搭配範例應用程式。
如需這個 API 的端對端實作方式，請參閱質感設計展示應用程式。

事前準備

這個 API 需要 Android API 級別 19 以上的版本。請確認應用程式的建構檔案使用 19 以上的 minSdkVersion 值。

在專案層級的 build.gradle 檔案中，請務必將 Google 的 Maven 存放區加進 buildscript 和 allprojects 區段。

將 ML Kit Android 程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案 (通常是 app/build.gradle)。您可以根據需求選擇下列其中一種依附元件：

綁定模型與應用程式的影響：

dependencies {
  // ...
  // Use this dependency to bundle the model with your app
  implementation 'com.google.mlkit:barcode-scanning:17.2.0'
}

在 Google Play 服務中使用模型：

dependencies {
  // ...
  // Use this dependency to use the dynamically downloaded model in Google Play Services
  implementation 'com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.0'
}

如果您選擇在 Google Play 服務中使用該模型，您可以設定應用程式，讓應用程式從 Play 商店安裝後自動下載至裝置。如要這麼做，請在應用程式的 AndroidManifest.xml 檔案中新增以下宣告：
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="barcode" >
      
</application>
```
您也可以透過 Google Play 服務 ModuleInstallClient API 明確檢查模型可用性及要求下載。

如果不啟用安裝時模型下載或要求明確下載，系統會在您首次執行掃描器時下載模型。在下載完成之前提出的要求不會產生任何結果。

輸入圖片規範

為讓 ML Kit 準確讀取條碼，輸入圖片必須包含足夠的像素資料所代表的條碼。

特定像素資料要求取決於條碼類型及其編碼的資料量，因為許多條碼都支援變數大小酬載。一般而言，條碼最小且最小單位為寬度 2 像素，如果是 2 維代碼，寬度則為 2 像素。

舉例來說，EAN-13 條碼是由 1、2、3 或 4 寬的長條組成，因此最適合使用 EAN-13 條碼圖片，且寬度至少 2、4、6 和 8 像素。由於 EAN-13 條碼的總寬度是 95 個單位，因此條碼的寬度必須至少為 190 像素。

PDF 檔案等密度格式需要更多像素尺寸，才能穩定讀取。舉例來說，PDF417 程式碼最多可以在一個列中使用 34 個 17 單位寬的「字詞」，寬度至少 1156 像素。
圖片品質不佳時會影響掃描的準確度。如果您的應用程式無法取得可接受的結果，請要求使用者重新拍攝圖片。
如果是一般的應用程式，建議您提供解析度較高的圖片，例如 1280x720 或 1920x1080，使得條碼可從相機遠距離掃描。

但是，對於延遲程度重要的應用程式，您可以降低解析度以擷取圖片，但要求條碼佔據大部分的圖片。另請參閱「改善即時效能的提示」。

1. 設定條碼掃描器

如果您知道應該讀取哪些條碼格式，可以將條碼偵測器設為僅偵測這些格式，藉此提升速度。

舉例來說，如要只偵測 Aztec 程式碼和 QR 圖碼，請建立 BarcodeScannerOptions 物件，詳情請參閱以下範例：

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(
                Barcode.FORMAT_QR_CODE,
                Barcode.FORMAT_AZTEC)
        .build()BarcodeScanningActivity.kt

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(
                Barcode.FORMAT_QR_CODE,
                Barcode.FORMAT_AZTEC)
        .build();BarcodeScanningActivity.java

支援的格式如下：

代碼 128 (FORMAT_CODE_128)
代碼 39 (FORMAT_CODE_39)
代碼 93 (FORMAT_CODE_93)
Codabar (FORMAT_CODABAR 個)
EAN-13 (FORMAT_EAN_13)
EAN-8 (FORMAT_EAN_8)
ITF (FORMAT_ITF)
通用產品代碼 (A) (FORMAT_UPC_A)
UPC-E (FORMAT_UPC_E)
QR 圖碼 (FORMAT_QR_CODE)
PDF417 (FORMAT_PDF417)
阿茲提克 (FORMAT_AZTEC)
資料矩陣 (FORMAT_DATA_MATRIX)

自套裝組合模型 17.1.0 和未組合模型 18.2.0 起，即使呼叫無法解碼，也可以呼叫 enableAllPotentialBarcodes() 以傳回所有可能的條碼。這可以用來進一步偵測，例如在縮放相機中放大鏡頭，從傳回的定界框中取得任何條碼的影像。

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .enableAllPotentialBarcodes() // Optional
        .build()

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .enableAllPotentialBarcodes() // Optional
        .build();

Further on, starting from bundled library 17.2.0 and unbundled library 18.3.0, a new feature called auto-zoom has been introduced to further enhance the barcode scanning experience. With this feature enabled, the app is notified when all barcodes within the view are too distant for decoding. As a result, the app can effortlessly adjust the camera's zoom ratio to the recommended setting provided by the library, ensuring optimal focus and readability. This feature will significantly enhance the accuracy and success rate of barcode scanning, making it easier for apps to capture information precisely.

To enable auto-zooming and customize the experience, you can utilize the setZoomSuggestionOptions() method along with your own ZoomCallback handler and desired maximum zoom ratio, as demonstrated in the code below.

Kotlin

val options = BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .setZoomSuggestionOptions(
            new ZoomSuggestionOptions.Builder(zoomCallback)
                .setMaxSupportedZoomRatio(maxSupportedZoomRatio)
                .build()) // Optional
        .build()

Java

BarcodeScannerOptions options =
        new BarcodeScannerOptions.Builder()
        .setBarcodeFormats(...)
        .setZoomSuggestionOptions(
            new ZoomSuggestionOptions.Builder(zoomCallback)
                .setMaxSupportedZoomRatio(maxSupportedZoomRatio)
                .build()) // Optional
        .build();

zoomCallback is required to be provided to handle whenever the library suggests a zoom should be performed and this callback will always be called on the main thread.

The following code snippet shows an example of defining a simple callback.

Kotlin

fun setZoom(ZoomRatio: Float): Boolean {
    if (camera.isClosed()) return false
    camera.getCameraControl().setZoomRatio(zoomRatio)
    return true
}

Java

boolean setZoom(float zoomRatio) {
    if (camera.isClosed()) {
        return false;
    }
    camera.getCameraControl().setZoomRatio(zoomRatio);
    return true;
}

maxSupportedZoomRatio is related to the camera hardware, and different camera libraries have different ways to fetch it (see the javadoc of the setter method). In case this is not provided, an unbounded zoom ratio might be produced by the library which might not be supported. Refer to the setMaxSupportedZoomRatio() method introduction to see how to get the max supported zoom ratio with different Camera libraries.

When auto-zooming is enabled and no barcodes are successfully decoded within the view, BarcodeScanner triggers your zoomCallback with the requested zoomRatio. If the callback correctly adjusts the camera to this zoomRatio, it is highly probable that the most centered potential barcode will be decoded and returned.

A barcode may remain undecodable even after a successful zoom-in. In such cases, BarcodeScanner may either invoke the callback for another round of zoom-in until the maxSupportedZoomRatio is reached, or provide an empty list (or a list containing potential barcodes that were not decoded, if enableAllPotentialBarcodes() was called) to the OnSuccessListener (which will be defined in step 4. Process the image).

2. Prepare the input image

To recognize barcodes in an image, create an InputImage object from either a Bitmap, media.Image, ByteBuffer, byte array, or a file on the device. Then, pass the InputImage object to the BarcodeScanner's process method.

You can create an InputImage object from different sources, each is explained below.

Using a `media.Image`

To create an InputImage object from a media.Image object, such as when you capture an image from a device's camera, pass the media.Image object and the image's rotation to InputImage.fromMediaImage().

If you use the CameraX library, the OnImageCapturedListener and ImageAnalysis.Analyzer classes calculate the rotation value for you.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

如果未使用相機提供圖片旋轉角度的相機，則可以從裝置的旋轉角度和裝置相機感應器的方向進行計算：

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

然後將 media.Image 物件和旋轉角度值傳遞至 InputImage.fromMediaImage()：

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

使用檔案 URI

如要從檔案 URI 建立 InputImage 物件，請將應用程式結構定義和檔案 URI 傳遞至 InputImage.fromFilePath()。如果您使用 ACTION_GET_CONTENT 意圖提示使用者從圖片庫應用程式中選取圖片，這個方法就非常實用。

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

使用 `ByteBuffer` 或 `ByteArray`

如要從 ByteBuffer 或 ByteArray 建立 InputImage 物件，請先按照之前的 media.Image 輸入值計算圖片旋轉角度。接著，使用緩衝區或陣列建立 InputImage 物件，以及圖片的高度、寬度、顏色編碼格式和旋轉角度：

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);MLKitVisionImage.java

使用 `Bitmap`

如要從 Bitmap 物件建立 InputImage 物件，請進行以下宣告：

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);MLKitVisionImage.java

圖片會以 Bitmap 物件搭配旋轉角度表示。

3. 取得 BarcodeScanner 的執行個體

Kotlin

val scanner = BarcodeScanning.getClient()
// Or, to specify the formats to recognize:
// val scanner = BarcodeScanning.getClient(options)BarcodeScanningActivity.kt

Java

BarcodeScanner scanner = BarcodeScanning.getClient();
// Or, to specify the formats to recognize:
// BarcodeScanner scanner = BarcodeScanning.getClient(options);BarcodeScanningActivity.java

4. 處理圖片

將圖片傳遞至 process 方法：

Kotlin

val result = scanner.process(image)
        .addOnSuccessListener { barcodes ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener {
            // Task failed with an exception
            // ...
        }BarcodeScanningActivity.kt

Java

Task<List<Barcode>> result = scanner.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<Barcode>>() {
            @Override
            public void onSuccess(List<Barcode> barcodes) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });BarcodeScanningActivity.java

注意：如果您使用的是 CameraX API，請務必在使用完成後關閉 ImageProxy，例如，將 OnCompleteListener 新增至 process 方法傳回的 Task 中。如需查看範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。

5. 從條碼取得資訊

如果條碼辨識作業成功，系統會將 Barcode 物件清單傳遞給成功事件監聽器。每個 Barcode 物件都代表了我們在圖片中偵測到的條碼。對於每個條碼，您都可以在輸入圖片中取得其繫結座標，以及透過條碼編碼的原始資料。此外，如果條碼掃描器能夠判別條碼編碼的資料類型，您可以取得包含剖析資料的物件。

例如：

Kotlin

for (barcode in barcodes) {
    val bounds = barcode.boundingBox
    val corners = barcode.cornerPoints

    val rawValue = barcode.rawValue

    val valueType = barcode.valueType
    // See API reference for complete list of supported types
    when (valueType) {
        Barcode.TYPE_WIFI -> {
            val ssid = barcode.wifi!!.ssid
            val password = barcode.wifi!!.password
            val type = barcode.wifi!!.encryptionType
        }
        Barcode.TYPE_URL -> {
            val title = barcode.url!!.title
            val url = barcode.url!!.url
        }
    }
}BarcodeScanningActivity.kt

Java

for (Barcode barcode: barcodes) {
    Rect bounds = barcode.getBoundingBox();
    Point[] corners = barcode.getCornerPoints();

    String rawValue = barcode.getRawValue();

    int valueType = barcode.getValueType();
    // See API reference for complete list of supported types
    switch (valueType) {
        case Barcode.TYPE_WIFI:
            String ssid = barcode.getWifi().getSsid();
            String password = barcode.getWifi().getPassword();
            int type = barcode.getWifi().getEncryptionType();
            break;
        case Barcode.TYPE_URL:
            String title = barcode.getUrl().getTitle();
            String url = barcode.getUrl().getUrl();
            break;
    }
}BarcodeScanningActivity.java

改善即時效能的提示

如要在即時應用程式中掃描條碼，請遵循下列指南以達到最佳影格速率：

請勿從相機的原生解析度擷取輸入內容。在某些裝置上，以原生解析度擷取輸入內容會產生超大型 (1000 萬像素) 的圖片，造成延遲時間極短，而且沒有準確性。請改為要求相機偵測條碼所需的大小，通常不超過 200 萬像素。

如果掃描速度非常重要，您可以進一步降低圖片的解析度。不過，請留意上述的基本條碼大小規定。

在透過串流影片畫面序列您應該等到連續取得相同值序列，才能確保結果傳回良好結果。

ITF 和 CODE-39 不支援總和檢查碼。
如果使用 Camera 或 camera2 API，請將呼叫傳送至偵測工具。偵測器執行時，如果偵測到新的影片畫面，請捨棄影格。如需範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。
如果您使用 CameraX API，請務必將背壓策略設為預設值 ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST。這只會傳送一張圖片進行分析。如果分析器忙碌時產生的更多圖片，系統會自動捨棄圖片，且不會排入佇列進行傳送。呼叫 ImageProxy.close() 關閉分析的圖片後，就會傳送下一張最新圖片。
如果您使用偵測工具的輸出內容在輸入圖片上疊加圖片，請先透過 ML Kit 取得結果，然後在單一步驟中顯示圖片和疊加層。每個輸入影格只會轉譯到一次顯示途徑。如需範例，請參閱快速入門導覽課程範例應用程式中的 CameraSourcePreview 和 GraphicOverlay 類別。
如果您使用 Camera2 API，請擷取 ImageFormat.YUV_420_888 格式的圖片。如果您使用舊版 Camera API，請擷取 ImageFormat.NV21 格式的圖片。

在 Android 上使用機器學習套件掃描條碼

立即體驗

事前準備

輸入圖片規範

1. 設定條碼掃描器

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

2. Prepare the input image

Using a media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

3. 取得 BarcodeScanner 的執行個體

Kotlin

Java

4. 處理圖片

Kotlin

Java

5. 從條碼取得資訊

Kotlin

Java

改善即時效能的提示

Using a `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`