HTML5-QRCode 二维码扫描库完整使用指南

2026-02-07 05:18:35作者：凤尚柏Louis

HTML5-QRCode 是一个跨平台的 HTML5 二维码和条形码扫描库，支持在 Web 应用中快速集成多种代码的扫描功能。该库采用纯 JavaScript 实现，无需额外依赖，能够在主流浏览器和移动设备上稳定运行。

为什么选择 HTML5-QRCode？

在当今数字化时代，二维码和条形码已成为连接物理世界与数字世界的重要桥梁。HTML5-QRCode 库提供了完整的解决方案，具有以下核心优势：

🚀 快速集成 - 只需几行代码即可实现完整的扫描功能
📱 跨平台兼容 - 支持 Android、iOS、Windows、macOS 和 Linux
🌐 浏览器支持广泛 - 兼容 Chrome、Firefox、Safari、Edge、Opera 等主流浏览器
🔧 灵活配置 - 提供底层 API 和完整 UI 两种使用方式
🔒 隐私安全 - 所有扫描处理都在本地完成，无需上传服务器

快速开始

安装方式

通过 npm 安装：

npm install html5-qrcode

通过 CDN 引入：

<script src="https://unpkg.com/html5-qrcode/minified/html5-qrcode.min.js"></script>

基础使用示例

下面是一个完整的扫描器实现示例：

<!DOCTYPE html>
<html>
<head>
    <title>二维码扫描器</title>
</head>
<body>
    <div id="reader" style="width: 600px"></div>
    <div id="result"></div>

    <script src="html5-qrcode.min.js"></script>
    <script>
        function onScanSuccess(decodedText, decodedResult) {
            console.log(`扫描结果: ${decodedText}`);
            document.getElementById('result').innerText = decodedText;
        }

        const html5QrcodeScanner = new Html5QrcodeScanner(
            "reader", 
            { fps: 10, qrbox: { width: 250, height: 250 } },
            false
        );
        html5QrcodeScanner.render(onScanSuccess);
    </script>
</body>
</html>

核心功能详解

两种使用模式

HTML5-QRCode 提供了两种不同级别的 API，满足不同场景的需求：

1. 简单模式 - Html5QrcodeScanner 完整的端到端扫描器，包含预设的用户界面，适合快速集成。

2. 专业模式 - Html5Qrcode 底层 API 接口，允许完全自定义用户界面，适合有特殊需求的开发者。

扫描配置选项

扫描器支持丰富的配置选项，让您能够根据具体需求进行优化：

const config = {
    fps: 10,                    // 每秒扫描帧数
    qrbox: {                    // 扫描区域设置
        width: 250, 
        height: 250 
    },
    aspectRatio: 1.777778,       // 视频宽高比（16:9）
    disableFlip: false,          // 是否禁用镜像扫描
    rememberLastUsedCamera: true // 记住上次使用的摄像头
};

支持的代码格式

该库支持扫描多种常见的二维码和条形码格式：

二维码类：QR Code、AZTEC、DATA_MATRIX
条形码类：CODE_39、CODE_93、CODE_128、ITF
商品码类：EAN_13、EAN_8、PDF_417、UPC_A、UPC_E

实际应用场景

移动端扫描应用

在移动设备上，HTML5-QRCode 能够充分利用设备的摄像头功能，提供流畅的扫描体验。特别适合：

电商应用 - 扫描商品条形码获取产品信息
票务系统 - 扫描电子票二维码验证入场
支付应用 - 扫描支付二维码完成交易
身份验证 - 扫描身份二维码进行登录验证

文件扫描功能

除了摄像头扫描，还支持从本地文件读取二维码：

const fileInput = document.getElementById('file-input');
fileInput.addEventListener('change', e => {
    const file = e.target.files[0];
    html5QrCode.scanFile(file, true)
        .then(result => console.log(result))
        .catch(err => console.error(err));
});

性能优化建议

为了在不同设备上获得最佳的扫描性能，建议：

调整帧率 - 在性能较差的设备上降低 fps 值
优化扫描区域 - 根据实际需求设置合适的 qrbox 尺寸
限制扫描格式 - 只启用需要的代码格式

只扫描特定格式示例

const formatsToSupport = [
    Html5QrcodeSupportedFormats.QR_CODE,
    Html5QrcodeSupportedFormats.CODE_128
];

const html5QrCode = new Html5Qrcode(
    "reader", 
    { formatsToSupport: formatsToSupport }
);

项目开发指南

本地开发环境搭建

如果您想要参与项目开发或进行自定义修改：

# 克隆项目
git clone https://gitcode.com/gh_mirrors/ht/html5-qrcode

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

项目结构概览

html5-qrcode/
├── src/                    # 源代码目录
│   ├── camera/            # 摄像头管理模块
│   ├── ui/                # 用户界面组件
│   ├── core.ts            # 核心扫描逻辑
│   └── html5-qrcode.ts    # 主入口文件
├── examples/              # 示例代码目录
│   ├── html5/            # 纯 HTML5 示例
│   ├── vuejs/            # Vue.js 集成示例
│   └── lit/              # Lit 框架示例
├── tests/                 # 测试用例目录
└── minified/              # 压缩后的发布文件