ZXing.js Library 使用指南

ZXing.js Library 是一个基于 TypeScript 的开源项目，它实现了多种格式的 1D/2D 条形码图像处理功能。该项目源自著名的 ZXing（"Zebra Crossing"）Java 库，专为 JavaScript 生态系统设计，使得在浏览器端处理二维码和条形码成为可能。

项目介绍

ZXing.js Library 提供了一套完整的 TypeScript API，允许开发者轻松地集成条形码读取和生成能力到他们的网站或应用中。它支持多种常见的编码类型，包括 QR Code、Data Matrix、Aztec、PDF 417 等 1D 和 2D 条形码格式。

支持的格式

1D 产品条码

• UPC-A
• UPC-E
• EAN-8
• EAN-13

1D 工业条码

• Code 39
• Code 93
• Code 128
• Codabar
• ITF
• RSS-14
• RSS-Expanded（实验性）

2D 条码

• QR Code
• Data Matrix
• Aztec
• PDF 417

快速开始

安装

通过 npm 安装：

npm install @zxing/library --save

或使用 yarn：

yarn add @zxing/library

基本使用示例

// 使用 ES6 模块导入
import { MultiFormatReader, BarcodeFormat, DecodeHintType } from '@zxing/library';

// 配置解码提示
const hints = new Map();
const formats = [BarcodeFormat.QR_CODE, BarcodeFormat.DATA_MATRIX];
hints.set(DecodeHintType.POSSIBLE_FORMATS, formats);

// 创建读取器实例
const reader = new MultiFormatReader();

// 解码图像
const luminanceSource = new RGBLuminanceSource(imgByteArray, imgWidth, imgHeight);
const binaryBitmap = new BinaryBitmap(new HybridBinarizer(luminanceSource));

try {
  const result = reader.decode(binaryBitmap, hints);
  console.log(`解码结果: ${result.text}`);
} catch (error) {
  console.error('解码失败:', error);
}

浏览器端使用

通过 CDN 引入

<script src="https://unpkg.com/@zxing/library@latest"></script>
<script>
  // 使用全局对象访问
  const codeReader = new ZXing.BrowserQRCodeReader();
  
  codeReader.decodeFromImageElement(document.getElementById('qrcode-image'))
    .then(result => {
      console.log(`解析结果: ${result.text}`);
    })
    .catch(err => {
      console.error('解析失败:', err);
    });
</script>

实时摄像头扫码

// 获取摄像头权限并实时解码
navigator.mediaDevices.getUserMedia({ video: true })
  .then(stream => {
    const video = document.createElement('video');
    video.srcObject = stream;
    video.play();

    const codeReader = new ZXing.BrowserQRCodeReader();
    
    const decodeContinuously = () => {
      codeReader.decodeFromVideoDevice(video, 'video-element')
        .subscribe({
          next: result => {
            console.log(`实时解码: ${result.text}`);
            decodeContinuously(); // 继续循环解码
          },
          error: err => console.error('解码错误:', err)
        });
    };

    decodeContinuously();
  })
  .catch(err => {
    console.error('摄像头访问失败:', err);
  });

项目示例

项目提供了丰富的使用示例，位于 docs/examples/ 目录下：

• 二维码图像解码 - docs/examples/qr-image/index.html
• 摄像头实时扫码 - docs/examples/qr-camera/index.html
• 多格式条码支持 - docs/examples/multi-image/index.html
• SVG 二维码生成 - docs/examples/qr-svg-writer/index.html
• Data Matrix 解码 - docs/examples/datamatrix-image/index.html
• PDF417 解码 - docs/examples/pdf417-image/index.html
• Aztec 码支持 - docs/examples/aztec-camera/index.html

最佳实践

性能优化

• 限制解码频率，避免连续高频率调用解码函数
• 使用合适的图像预处理来优化识别率
• 针对移动设备进行性能调优

用户体验

• 提供清晰的扫描指引界面
• 处理各种解码失败场景
• 添加适当的加载和反馈状态

兼容性考虑

• iOS 14.3 以上版本支持第三方浏览器的摄像头访问
• 使用 polyfill 增强老旧浏览器兼容性
• 注意 BigInt 类型在某些浏览器中的支持限制

项目结构

src/
├── browser/           # 浏览器相关实现
├── core/             # 核心解码器实现
│   ├── common/       # 通用工具类
│   ├── datamatrix/   # Data Matrix 支持
│   ├── pdf417/       # PDF417 支持
│   ├── qrcode/       # QR Code 支持
│   └── oned/         # 1D 条码支持
└── test/             # 测试用例

贡献指南

项目采用维护模式，欢迎提交 bug 修复和小幅功能增强。详细的贡献指南请参考 CONTRIBUTING.md。

局限性

• iOS 14.3 以下版本在第三方浏览器中摄像头访问受限
• 需要现代浏览器支持 MediaDevices API
• PDF417 解码依赖 BigInt，部分浏览器需要 polyfill

ZXing.js Library 为 Web 开发者提供了强大的条形码处理能力，无论是扫码支付、物流跟踪还是信息检索，都能轻松集成到各种 Web 应用中。