全部产品
Search

搜索本产品

    移动开发平台mPaaS：进阶指南

    文档中心

    移动开发平台mPaaS：进阶指南

    更新时间：Oct 25, 2023

    窗口扫码表示在旧的标准 UI 下使用扫码功能。若需使用支持多码识别的全屏扫码功能，请将 mPaaS 基线版本升级至 10.1.68.33 及以上。

    下图是扫一扫支持的三种 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);