cordova-plugin-qrscanner 高效条码扫描插件

一款专为 Cordova/PhoneGap 混合移动应用打造的条码与二维码扫描插件，基于原生平台扫描能力开发，支持多码制识别、实时预览、闪光灯控制及本地图片解析等核心功能。具备识别速度快、准确率高、兼容性强、轻量化等特点，可广泛应用于商品溯源、移动支付、资产管理、票务验证等场景。

功能特性

• 多码制全面支持：覆盖常见一维码（如 EAN-13、UPC-A、Code 128）和二维码（如 QR Code、Data Matrix、Aztec），支持自定义启用/禁用特定码制

• 原生扫描引擎：基于 HamonyOS 原生扫描能力开发，识别速度≤300ms，准确率≥98%（清晰条码场景）

• 实时预览与对焦：支持高清实时预览（最高 1080P），支持自动对焦、手动点击对焦及连续对焦模式，适配不同距离扫描需求

• 辅助扫描功能：集成闪光灯控制（明暗环境自适应）、扫描框引导（提高识别效率）、震动/声音反馈（扫描成功提示）

• 本地图片解析：支持从相册选择图片或传入图片路径，解析图片中的条码信息，适配多种图片格式（JPG、PNG、GIF 等）

• 权限智能管理：自动检测并请求相机、相册权限，提供权限申请结果回调，支持权限拒绝后的引导处理

• 离线全功能支持：所有扫描与解析功能均本地完成，无需依赖网络，满足无网环境使用需求

• 连续扫码能力：可实现连续扫码，连续处理业务

• 自定义扫码音效：扫码通知到js后，系统默认不播放音效，js侧实现播放音效

安装方法

确保已创建 Cordova/PhoneGap 项目（若未创建，执行 hcordova create barcodeApp com.example.barcodeapp BarcodeApp 或 phonegap create barcodeApp 创建），进入项目根目录后选择以下方式安装：

1. 基础版安装

适用于大多数场景，直接从 npm 仓库安装稳定版：

# 安装hcordova
npm install -g hcordova

# 安装最新稳定版扫描插件
hcordova plugin add cordova-plugin-qrscanner

# 安装指定版本（示例：1.0.0 版本）
hcordova plugin add [email protected] --platform ohos

2. 从 GitCode 安装开发版

适用于需要体验最新功能的开发者，从 GitHub 仓库直接安装：

# 安装开发版插件
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-qrscanner.git --platform ohos

卸载方法

进入项目根目录，执行以下命令卸载插件，卸载后建议重新构建项目以清理残留文件：

# 卸载扫描插件
hcordova plugin remove cordova-plugin-qrscanner

# 指定HarmonyOS卸载
hcordova plugin remove cordova-plugin-qrscanner --platform ohos

核心概念

1. 插件命名空间

插件通过全局对象 QRScanner 暴露所有 API 方法，所有操作均需通过该命名空间调用，避免与其他插件冲突。

2. 扫描模式

插件支持两种核心扫描模式，可根据业务场景选择：

• 实时扫描模式：打开相机实时预览并识别条码，适用于直接扫描实体条码的场景（如商品扫码、票务验证），支持连续扫描和单次扫描

• 图片解析模式：解析本地图片文件中的条码信息，适用于扫描已保存的条码图片场景（如相册中的电子票、截图中的条码）

3. 对焦模式

为适配不同扫描距离和场景，插件支持三种对焦模式：

• 自动对焦：相机根据画面清晰度自动调整对焦，适用于扫描距离不固定的场景（默认模式）

• 手动对焦：通过点击预览界面指定对焦区域，适用于条码较小或位于画面特定位置的场景

• 连续对焦：相机持续保持对焦状态，适用于连续扫描多个条码的场景（如批量扫码入库）

HarmonyOS权限配置

在主工程的module.json5中添加相机权限

{
    "name": "ohos.permission.CAMERA",
    "reason": "$string:cameraInfo",
    "usedScene": {
        "abilities": [
        "EntryAbility"
        ],
        "when": "always"
    }
}

API 参考

插件所有 API 均为异步执行，通过回调函数处理执行结果，支持 Promise 风格调用（部分方法）。

1. 状态参数

|属性名称（Name）|描述（Description）| |---|---| |authorized|布尔值，仅当用户允许应用访问相机（在对话框中点击“允许”）时为 true | |denied|布尔值，若用户永久拒绝应用访问相机| |restricted|布尔值，若用户因家长控制、组织安全配置文件或类似原因无法授予权限，则为 true。| |prepared|布尔值，若 QRScanner 已准备好捕获视频并将其渲染到视图中，则为 true。| |showing|布尔值，当预览层可见时为 true（且在除“浏览器”外的所有平台上，原生 WebView 背景为透明）。| |scanning|布尔值，若 QRScanner 正在主动扫描二维码，则为 true。| |previewing|布尔值，若 QRScanner 正在显示设备相机的实时预览，则为 true。预览暂停时设为 false。| |lightEnabled|布尔值，若闪光灯已开启，则为 true。| |canOpenSettings|布尔值，仅当用户的操作系统支持 HarmonyOS 永远为 false。| |canEnableLight|布尔值，仅当用户设备当前使用的相机（currentCamera）方向上可开启闪光灯时为 true。| |canChangeCamera|布尔值，仅当当前设备“应”具备前置摄像头时为 true。HarmonyOS永远为false| |currentCamera|表示当前使用相机索引的数字。0 为后置摄像头，1 为前置摄像头。HarmonyOS 永远为1|

2. 准备扫码

HarmonyOS不需要预先准备扫码，可以直接调用show函数，但是鸿蒙兼容准备扫码函数

var done = function(err, status){
  if(err){
    console.error(err._message);
  } else {
    console.log('QRScanner is initialized. Status:');
    console.log(status);
  }
};
 
QRScanner.prepare(done);

3. 显示摄像头

QRScanner.show(function(status){
  console.log(status);
});

4. 获取当前状态

QRScanner.getStatus(function(status){
  console.log(status);
});

5. 设置窗口位置

QRScanner.setWindowRect(function(result){
    console.log("result:"+result);
},{x:0,y:0,height:'100%',width:'100%'});

6. 开始扫码

QRScanner.scan(function(error, result){
    if(error) {
        console.log(error);
    } else {
        //扫码结束重新扫码,实现连续扫码
        console.log(result); //获取扫码结果，处理业务，然后重新开始扫描
        setTimeout(function(){
            QRScanner.resumePreview(function(status){
                console.log(status);
            })
        }, 1000);
    }
})

6. 重新扫描

QRScanner.resumePreview(function(status){
    console.log(status);
})

7. 暂停扫码

//cancelScan和pausePreview实现相同效果
//暂停扫码后，调用resumePreview可以继续扫码
QRScanner.cancelScan(function(status){
  console.log(status);
})

QRScanner.pausePreview(function(status){
  console.log(status);
})

8. 释放相机

//hide和destroy实现相同效果，js可以不调用
//扫码全屏模式下，原生功能也实现了释放相机功能，直接点击左上角按钮关闭相机即可
QRScanner.hide(function(status){
    console.log(status);
});

QRScanner.destroy(function(status){
    console.log(status);
});

9. 打开闪光灯

//扫码全屏模式下，原生功能也实现了闪光灯功能，js可以不调用
QRScanner.enableLight(function(err, status){
    err && console.error(err);
    console.log(status);
});

10. 关闭闪光灯

//扫码全屏模式下，原生功能也实现了闪光灯功能，js可以不调用
QRScanner.disableLight(function(err, status){
    err && console.error(err);
    console.log(status);
});

使用示例

//扫码后自动播放音效
var myAudio = new Audio();
myAudio.preload = true;
myAudio.controls = true;

function playAudio() {
    myAudio.src = "../default.mp3";
    myAudio.loop = false;
    myAudio.defaultPlaybackRate=1;
    myAudio.play();
}

//设置全屏
function QRScannerSetRect() {
    QRScanner.setWindowRect(function(result){
        console.log("result:"+result);
    }, {x:0,y:0,height:'100%',width:'100%'});
}

function QRScannerShow() {
    QRScanner.setWindowRect(function(status){
        console.log("result:"+status);
        QRScanner.show(function(status){
            document.getElementById("barcode").innerHTML = JSON.stringify(status);
            QRScanner.getStatus(function(status){
                document.getElementById("barcode").innerHTML = JSON.stringify(status);
                QRScanner.prepare(function(error, status){
                    document.getElementById("barcode").innerHTML = JSON.stringify(status);
                    if(error) {
                        document.getElementById("barcode").innerHTML = error;
                    }
                    if(status.authorized) {
                        QRScanner.scan(function(error, result){
                            document.getElementById("barcode").innerHTML = result;
                            if(error) {
                                document.getElementById("barcode").innerHTML = error;
                            } else {
                                playAudio();
                                document.getElementById("barcode").innerHTML = result;
                                //扫码结束重新扫码
                                setTimeout(function(){
                                    QRScanner.resumePreview(function(status){
                                        console.log(status);
                                    })
                                }, 1000);
                            }
                        })
                    }
                });
            });
        });
    },{x:0,y:0,height:'70%',width:'100%'});
}

//打开和关闭闪光灯
var isLight = 0;
function QRScannerOpenLight() {
    if(isLight == 0) {
        QRScanner.enableLight(function(err, status){
            err && console.error(err);
            console.log(status);
            isLight = 1;
        });
    } else {
        QRScanner.disableLight(function(err, status){
            err && console.error(err);
            console.log(status);
            isLight = 0;
        });
    }

}

//关闭摄像头
function QRScannerClose() {
    QRScanner.destroy(function(status){
        console.log(status);
    });
/*和destroy实现相同功能
    QRScanner.hide(function(status){
        console.log(status);
    });
*/
}

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

参考资源

• Android和iOS：cordova-plugin-qrscanner 官方指南

• GitCode 仓库：OpenHarmony-Cordova/cordova-plugin-qrscanner