Mobile Platform as a Service：進階指南

下圖是掃一掃支援的三種 UI 掃碼樣式。

標準 UI 下使用掃一掃

全屏掃碼

如需連續掃碼，即掃碼識別成功後不退出繼續識別，可根據如下代碼來實現。

ScanRequest scanRequest = new ScanRequest();
        MPScan.startMPaasScanFullScreenActivity(this, scanRequest, new MPScanCallbackAdapter() {
            @Override
            public boolean onScanFinish(Context context, MPScanResult mpScanResult, final MPScanStarter mpScanStarter) {
                new android.app.AlertDialog.Builder(context)
                        .setMessage(mpScanResult != null ? mpScanResult.getText() : "沒有識別到碼")
                        .setPositiveButton(R.string.confirm, new DialogInterface.OnClickListener() {
                            @Override
                            public void onClick(DialogInterface dialog, int which) {
                                mpScanStarter.restart();
                            }
                        })
                        .create()
                        .show();
                // 返回 false 表示該回調未消費，下次識別繼續回調
                return false;
            }
        });

重寫 MPScanCallbackAdapter 的其他方法來監聽其他事件：

MPScan.startMPaasScanFullScreenActivity(this, scanRequest, new MPScanCallbackAdapter() {
    @Override
    public boolean onScanFinish(final Context context, MPScanResult mpScanResult, final MPScanStarter mpScanStarter) {
        return true;
    }

    @Override
    public boolean onScanError(Context context, MPScanError error) {
        // 識別錯誤
        return super.onScanError(context, error);
    }

    @Override
    public boolean onScanCancel(Context context) {
        // 識別取消
        return super.onScanCancel(context);
    }
});

在啟動全屏掃碼功能前，可根據如下代碼設定啟動參數。

ScanRequest scanRequest = new ScanRequest();

// 設定提示文字
scanRequest.setViewText("提示文字");

// 設定開啟手電筒提示文字
scanRequest.setOpenTorchText("開啟手電筒");

// 設定關閉手電筒提示文字
scanRequest.setCloseTorchText("關閉手電筒");

// 設定掃碼識別類型
// 該設定僅對直接掃碼生效，對識別相簿圖片無效
scanRequest.setRecognizeType(
    ScanRequest.RecognizeType.QR_CODE,    // 二維碼
    ScanRequest.RecognizeType.BAR_CODE,   // 條碼
    ScanRequest.RecognizeType.DM_CODE,    // DM 碼
    ScanRequest.RecognizeType.PDF417_Code // PDF417 碼
); // 不設定，則預設識別前三種

// 設定隱藏相簿按鈕
scanRequest.setNotSupportAlbum(true);

// 設定多碼標記圖片
scanRequest.setMultiMaMarker(R.drawable.green_arrow);

// 設定多碼提示文字
scanRequest.setMultiMaTipText("點擊綠色箭頭選擇碼");

// 設定選中單個碼後的圓點顏色
scanRequest.setMaTargetColor("#32CD32");

// 開啟 AI 識別小碼並自動放大，僅 10.2.3 及以上基準支援，需接入掃一掃 AI 組件
scanRequest.setEnableAI(true);

// 設定延時提示文案，僅 10.2.3 及以上基準支援
scanRequest.setDelayTipText("延時x秒彈出toast");

// 設定延時提示時間，單位毫秒，僅 10.2.3 及以上基準支援
scanRequest.setDelayTipTime(5000);

視窗掃碼

使用在視窗掃碼功能時，可根據如下代碼設定啟動參數。

ScanRequest scanRequest = new ScanRequest();

// 設定掃碼頁 UI 風格
scanRequest.setScanType(ScanRequest.ScanType.QRCODE);  // 二維碼風格
scanRequest.setScanType(ScanRequest.ScanType.BARCODE); // 條碼風格，預設

// 設定掃碼介面 title
scanRequest.setTitleText("標準掃碼");

// 設定掃碼視窗下提示文字
scanRequest.setViewText("提示文字");

// 設定開啟手電筒提示文字，僅 10.1.60 及以上基準支援
scanRequest.setOpenTorchText("開啟手電筒");

// 設定關閉手電筒提示文字，僅 10.1.60 及以上基準支援
scanRequest.setCloseTorchText("關閉手電筒");

// 設定掃碼識別類型，僅 10.1.60.6+ 和 10.1.68.2+ 基準支援
// 該設定僅對直接掃碼生效，對識別相簿圖片無效
scanRequest.setRecognizeType(
    ScanRequest.RecognizeType.QR_CODE,    // 二維碼
    ScanRequest.RecognizeType.BAR_CODE,   // 條碼
    ScanRequest.RecognizeType.DM_CODE,    // DM 碼
    ScanRequest.RecognizeType.PDF417_Code // PDF417 碼
); // 不設定，則預設識別前三種

// 設定透明狀態列（在 Android 4.4+ 系統上生效），僅 10.1.68.15+ 基準支援
scanRequest.setTranslucentStatusBar(true);

// 設定隱藏相簿按鈕，僅 10.1.68.22+ 基準支援
scanRequest.setNotSupportAlbum(true);

自訂 UI 下使用掃一掃

請參考 程式碼範例。

自訂 UI 升級適配

• 自 10.2.3.35 起，掃一掃 SDK 新增了 MPCustomScanView 類以及相關介面，以代替此前使用的 MPScanner 來實現自訂 UI。相比 MPScanner，使用 MPCustomScanView 的方案封裝了相機管理、碼識別、多碼識別、畫面放大與縮小、碼結果解析等掃一掃服務核心流程，您在開發時無需關注相關操作，只需專註於在 MPCustomScanView 中實現您自訂的 UI。您仍然可以繼續使用 MPScanner，但該方案將不再維護，無法在後續的升級中獲得和全屏 UI 一致的特性更新（例如多碼識別）。推薦您在合適的時機改用 MPCustomScanView 方案來實現自訂 UI，該方案會在後續的特性升級中和全屏 UI 保持一致。

• 自 10.1.68.5 和 10.1.60.11 起，掃一掃 SDK 新增了類 MPScanner 以及相關介面，用來替代此前自訂掃碼需要使用的 BQCScanCallback、MaScanCallback 等原始介面。相比原始介面，MPScanner 提供了完整的封裝性、簡潔易懂的 API，以及更多新特性的支援（例如環境亮度不足的回調）。如果您仍然在使用 BQCScanCallback、MaScanCallback 等原始介面，當您從低版本升級時可能需要適配以下變更：

  • 10.1.68.22 版本：MaScanCallback 類、BQCScanCallback 類、IOnMaSDKDecodeInfo 類新增部分介面，您只需空實現這些介面即可，其中 MaScanCallback.onMaCodeInterceptor 方法返回 false 。

  • 10.1.60.6 版本：BQCScanCallback 類新增部分介面，您只需空實現這些介面即可。

  • 10.1.60 版本：BQCScanCallback 類新增部分介面，您只需空實現這些介面即可。

  • 10.1.20 版本：MaScanCallback 類介面變更如下：void onResultMa(MaScanResult maScanResult) 變更為 void onResultMa(MultiMaScanResult multiMaScanResult) 您可以按照以下方式擷取 MaScanResult：

    MaScanResult maScanResult = multiMaScanResult.maScanResults[0];

自訂 UI API 說明

MPCustomScanView

使用MPCustomScanView，需要讓您的 Activity 繼承 MPaasToolsCaptureActivity，並實現 getCustomScanView 方法並返回自訂的 MPCustomScanView。

public class MyScanActivity extends MPaasToolsCaptureActivity {

    private MyScanView myScanView;

    @Override
    protected MPCustomScanView getCustomScanView() {
        myScanView = new MyScanView(this);
        // 具體可參考 github 程式碼範例
        return myScanView;
    }
  
}

在 MPCustomScanView 中您可以實現或調用以下方法：

/**
 * 掃描開始的回調
 */
public void onStartScan();

/**
 * 相機首幀顯示的回調
 * 
 * 本方法和掃描開始的回調，無法保證哪個會先執行
 */
public void onPreviewShow();

/**
 * 掃描結束的回調
 */
public void onStopScan();

/**
 * 相機幀的灰階值回調
 * 掃描過程中每一幀都會回調一次
 * 
 * @param gray 平均灰階值，可用來衡量環境亮度
 */
public void onGetAvgGray(int gray);

/**
 * 掃描成功的回調（識別到碼）
 * 
 * @param context 當前上下文
 * @param list 識別的碼結果
 */
public abstract void onScanFinished(Context context, List<MPScanResult> list);

/**
 * 掃描失敗的回調
 * 
 * @param context 當前上下文
 * @param list 失敗原因
 */
public abstract void onScanFailed(Context context, MPScanError error);

/**
 * 開啟相機失敗的回調
 */
public void onCameraOpenFailed();

/**
 * 開啟或關閉閃光燈
 * 
 * @return 調用完該方法後閃光燈的狀態
 */
public boolean switchTorch();

/**
 * 從檔案中識別碼
 * 
 * @param path 檔案路徑
 * @return 識別的碼結果
 */
public List<MPScanResult> scanFromPath(String path);

MPScanResult

/**
 * 識別結果字串
 */
private String text;

/**
 * 識別的碼類型
 */
private MPRecognizeType mpRecognizeType;

/**
 * 識別的碼的中心點座標
 */
private Point centerPoint;

MPScanner（廢棄）

自訂 UI 相關的設定內容如下：

/**
 * 設定顯示相機內容的 View
 * 推薦在 {@link MPScanListener} 的 onConfiguration 方法中調用
 *
 * @param textureView 自訂掃碼頁中的 TextureView
 */
public void setDisplayView(TextureView textureView);

/**
 * 設定掃描識別的地區
 * 
 * @param rect 識別的地區
 */
public void setScanRegion(Rect rect);

/**
 * 設定掃描監聽器
 */
public void setMPScanListener(MPScanListener mpScanListener);

/**
 * 設定識別映像灰階值監聽器
 */
public void setMPImageGrayListener(MPImageGrayListener mpImageGrayListener);

/**
 * 擷取 Camera 對象
 * 
 * @return Camera 對象
 */
public Camera getCamera();

/**
 * 設定識別的碼類型
 * 僅對直接掃碼生效，對從 bitmap 中識別碼無效
 *
 *
 * @param recognizeTypes BAR_CODE 條碼；
 *                       QR_CODE 二維碼；
 *                       DM_CODE DM 碼；
 *                       PDF417_CODE PDF417 碼；
 *                       不設定則預設識別前三種
 */
public void setRecognizeType(MPRecognizeType... recognizeTypes);

自訂 UI 相關的掃描內容如下：

/**
 * 開啟相機並開始掃描
 * 
 * 首次進入頁面時或相機關閉狀態下調用
 */
public void openCameraAndStartScan();

/**
 * 關閉相機並停止掃描
 */
public void closeCameraAndStopScan();

/**
 * 開始掃描
 * 
 * 不會更改相機狀態，需在相機開啟的狀態下調用才會生效
 */
public void startScan();

/**
 * 停止掃描
 *
 * 不會更改相機狀態
 */
public void stopScan();

/**
 * 從 bitmap 中識別碼
 *
 * @param bitmap 需要識別的 bitmap
 * @return 識別結果
 */
public MPScanResult scanFromBitmap(Bitmap bitmap);

其他：

/**
 * 開啟或關閉手電筒
 *
 * @return 調用方法後，手電筒是否開啟
 */
public boolean switchTorch();

/**
 * 開啟手電筒
 */
public void openTorch();

/**
 * 關閉手電筒
 */
public void closeTorch();

/**
 * 播放預設的“嗶嗶”聲
 */
public void beep();

/**
 * 釋放資源
 * 
 * 請在 onDestroy 中調用
 */
public void release();

MPScanListener（廢棄）

/**
 * 掃描參數配置完成
 */
void onConfiguration();

/**
 * 掃描識別開始
 */
void onStart();

/**
 * 識別成功
 *
 * @param result 識別結果
 */
void onSuccess(MPScanResult result);

/**
 * 識別錯誤
 *
 * @param error 錯誤
 */
void onError(MPScanError error);

MPImageGrayListener（廢棄）

/**
 * 擷取識別映像的平均灰階值
 *
 * 正常範圍大約在 50-140 之間，
 * 當灰階值低於或高於正常範圍時，通常意味著環境亮度過低或過高，可以提示使用者開啟或關閉手電筒
 * 注意：該方法在識別過程中會不斷被調用
 *
 * @param gray 映像的平均灰階值
 */
void onGetImageGray(int gray);