QuaggaJS用法详解

news2025/6/9 20:40:52

QuaggaJS简介

QuaggaJS是一个强大的JavaScript库，专门用于在浏览器环境中进行条形码和二维码识别。它支持多种条形码格式，包括Code 128、Code 39、EAN、QR码等，并且可以直接调用设备摄像头进行实时扫描。

QuaggaJS核心功能与用法

1. 基本配置与初始化

使用QuaggaJS首先需要引入库文件，并进行基本配置：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>QuaggaJS条形码扫描示例</title>
  <!-- 引入QuaggaJS库 -->
  <script src="https://cdn.jsdelivr.net/npm/quagga@0.12.1/dist/quagga.min.js"></script>
</head>
<body>
  <div id="interactive" class="viewport"></div>
  <div id="result"></div>

  <script>
    // 页面加载完成后初始化Quagga
    document.addEventListener('DOMContentLoaded', function() {
      Quagga.init({
        inputStream : {
          name : "Live",
          type : "LiveStream",
          target: document.querySelector('#interactive') // 摄像头视频将显示在这里
        },
        decoder : {
          readers : ["code_128_reader", "ean_reader", "ean_8_reader"] // 配置要识别的条形码类型
        }
      }, function(err) {
        if (err) {
          console.error('初始化Quagga失败:', err);
          return;
        }
        console.log('Quagga初始化成功');
        Quagga.start(); // 开始扫描
      });
    });
  </script>
</body>
</html>

2. 事件监听与结果处理

QuaggaJS提供了多种事件来监听扫描过程和结果：

// 设置检测到条形码时的回调
Quagga.onDetected(function(result) {
  const code = result.codeResult.code;
  const format = result.codeResult.format;
  
  document.getElementById('result').innerHTML = `
    <p>扫描结果: ${code}</p>
    <p>条形码格式: ${format}</p>
  `;
  
  // 可以在这里添加震动或声音反馈
  navigator.vibrate(200);
});

// 设置处理每一帧的回调（用于可视化或调试）
Quagga.onProcessed(function(result) {
  const drawingCtx = Quagga.canvas.ctx.overlay;
  const drawingCanvas = Quagga.canvas.dom.overlay;
  
  if (result) {
    // 绘制检测到的条形码边界框
    if (result.boxes) {
      drawingCtx.clearRect(0, 0, parseInt(drawingCanvas.getAttribute("width")), parseInt(drawingCanvas.getAttribute("height")));
      result.boxes.filter(function (box) {
        return box !== result.box;
      }).forEach(function (box) {
        Quagga.ImageDebug.drawPath(box, {x: 0, y: 1}, drawingCtx, {color: "green", lineWidth: 2});
      });
    }
    
    // 绘制识别到的条形码
    if (result.box) {
      Quagga.ImageDebug.drawPath(result.box, {x: 0, y: 1}, drawingCtx, {color: "#00F", lineWidth: 2});
    }
    
    // 绘制条形码解码位置
    if (result.codeResult && result.codeResult.code) {
      Quagga.ImageDebug.drawPath(result.line, {x: 'x', y: 'y'}, drawingCtx, {color: 'red', lineWidth: 3});
    }
  }
});

3. 配置选项详解

QuaggaJS的初始化配置非常灵活，可以根据需求调整各种参数：

Quagga.init({
  inputStream : {
    name : "Live",
    type : "LiveStream",
    target: document.querySelector('#interactive'),
    constraints: {
      width: 640,
      height: 480,
      facingMode: "environment" // 使用后置摄像头
    },
    area: { // 扫描兴趣区域
      top: "0%",    // 从上到下的百分比
      right: "0%",  // 从右到左的百分比
      left: "0%",   // 从左到右的百分比
      bottom: "0%"  // 从下到上的百分比
    },
    // 控制是否显示视频预览中的缩放控件
    showCanvas: false,
    showPatches: false,
    showFoundPatches: false
  },
  decoder : {
    readers : ["code_128_reader", "ean_reader", "ean_8_reader", "code_39_reader", "code_39_vin_reader", "codabar_reader", "upc_reader", "upc_e_reader"],
    debug: {
      showCanvas: true,
      showPatches: true,
      showFoundPatches: true,
      showSkeleton: true,
      showLabels: true,
      showPatchLabels: true,
      showRemainingPatchLabels: true,
      boxFromPatches: {
        showTransformed: true,
        showTransformedBox: true,
        showBB: true
      }
    }
  },
  locator: {
    patchSize: "medium", // 可以是 'small', 'medium', 'large'
    halfSample: true // 是否使用半采样来提高性能
  },
  numOfWorkers: 4, // 处理线程数
  frequency: 10,   // 每秒处理的帧数
  locate: true     // 是否启用定位（寻找条形码位置）
}, function(err) {
  if (err) {
    console.error('初始化Quagga失败:', err);
    return;
  }
  console.log('Quagga初始化成功');
  Quagga.start();
});

4. 控制扫描过程

你可以在需要时暂停、恢复或完全停止扫描过程：

// 暂停扫描（保持摄像头打开）
function pauseScanning() {
  Quagga.pause();
  console.log('扫描已暂停');
}

// 恢复扫描
function resumeScanning() {
  Quagga.start();
  console.log('扫描已恢复');
}

// 完全停止扫描（关闭摄像头）
function stopScanning() {
  Quagga.stop();
  console.log('扫描已停止，摄像头已关闭');
}

5. 识别静态图片中的条形码

除了实时扫描，QuaggaJS还可以用于识别静态图片中的条形码：

// 从图片文件识别条形码
function recognizeFromImage(file) {
  Quagga.decodeSingle({
    decoder: {
      readers: ["code_128_reader", "ean_reader"] // 要尝试的条形码格式
    },
    locate: true, // 是否尝试定位条形码
    src: URL.createObjectURL(file) // 图片文件对象
  }, function(result) {
    if (result.codeResult) {
      console.log('识别成功:', result.codeResult.code);
    } else {
      console.log('未识别到条形码');
    }
  });
}

// 使用示例
document.getElementById('imageInput').addEventListener('change', function(e) {
  if (e.target.files && e.target.files[0]) {
    recognizeFromImage(e.target.files[0]);
  }
});

QuaggaJS与jsQR对比

QuaggaJS和jsQR是两种常用的浏览器条形码识别库，它们有以下区别：

特性	QuaggaJS	jsQR
支持的条形码格式	多种一维码和二维码	主要支持QR码
性能	相对较慢（尤其是复杂场景）	非常快（针对QR码优化）
配置复杂度	较高（有许多可调整参数）	较低（简单易用）
摄像头支持	优秀（有兴趣区域等高级功能）	基本功能
社区活跃度	中等	高
文件大小	较大（约300KB）	较小（约150KB）

QuaggaJS应用建议

性能优化：
- 限制识别的条形码格式（只启用需要的阅读器）
- 适当调整frequency参数（降低每秒处理的帧数）
- 使用halfSample选项减少处理的数据量
用户体验：
- 添加视觉反馈（如扫描线动画）
- 提供声音或震动反馈
- 清晰指示扫描区域
兼容性：
- 确保在移动设备上有良好表现
- 提供备选方案（如手动输入）
错误处理：
- 处理摄像头访问失败的情况
- 提示用户调整光线或条形码位置