文档

进阶指南

更新时间:

窗口扫码表示在旧的标准 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 以及相关接口,用来替代此前自定义扫码需要使用的 BQCScanCallbackMaScanCallback 等原始接口。相比原始接口,MPScanner 提供了完整的封装性、简洁易懂的 API,以及更多新特性的支持(例如环境亮度不足的回调)。如果您仍然在使用 BQCScanCallbackMaScanCallback 等原始接口,当您从低版本升级时可能需要适配以下变更:

    • 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);