HTML5-QRCode 二维码和条形码扫描库使用教程

2026-02-06 04:11:55作者：董宙帆

HTML5-QRCode 是一个跨平台的 HTML5 二维码和条形码扫描库，支持在 Web 应用中快速集成二维码、条形码和其他常见代码的扫描功能。

项目概述

HTML5-QRCode 是一个轻量级的 JavaScript 库，具有以下主要特性：

🔲 支持扫描多种类型的条形码和二维码
🖥 支持 Android、iOS、macOS、Windows 和 Linux 等多个平台
🌐 支持 Chrome、Firefox、Safari、Edge、Opera 等多种浏览器
📷 支持使用摄像头扫描和本地文件扫描两种方式
➡️ 提供完整的端到端扫描器 UI 和底层 API

安装和使用

通过 npm 安装

npm install html5-qrcode

通过 CDN 引入

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

基本使用示例

<!DOCTYPE html>
<html>
<head>
    <title>QR Code Scanner</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}`, decodedResult);
            document.getElementById('result').innerText = decodedText;
        }

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

核心 API

Html5QrcodeScanner 类

Html5QrcodeScanner 提供完整的端到端扫描体验，包含用户界面：

const scanner = new Html5QrcodeScanner(
    "reader", // 容器元素的 ID
    {
        fps: 10, // 帧率
        qrbox: { width: 250, height: 250 }, // 扫描框尺寸
        rememberLastUsedCamera: true // 记住上次使用的摄像头
    },
    false // 是否显示详细日志
);

scanner.render(onScanSuccess, onScanFailure);

Html5Qrcode 类

Html5Qrcode 提供底层 API，允许自定义用户界面：

const html5QrCode = new Html5Qrcode("reader");

// 开始扫描
html5QrCode.start(
    cameraId, 
    config, 
    onScanSuccess, 
    onScanFailure
);

// 停止扫描
html5QrCode.stop();

配置选项

扫描配置

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

支持的格式

HTML5-QRCode 支持以下代码格式：

QR Code（二维码）
AZTEC
CODE_39
CODE_93
CODE_128
DATA_MATRIX
ITF
EAN_13
EAN_8
PDF_417
UPC_A
UPC_E

高级用法

只扫描特定格式

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

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

文件扫描

// 选择文件输入
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));
});

项目结构

html5-qrcode/
├── src/                    # 源代码目录
│   ├── camera/            # 摄像头相关功能
│   ├── ui/                # 用户界面组件
│   ├── core.ts            # 核心功能
│   └── html5-qrcode.ts    # 主入口文件
├── examples/              # 示例代码
│   ├── html5/            # 纯 HTML5 示例
│   ├── vuejs/            # Vue.js 示例
│   └── lit/              # Lit 示例
├── tests/                 # 测试文件
├── minified/              # 压缩后的文件
└── third_party/           # 第三方依赖

开发指南

构建项目

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

项目配置

主要的配置文件包括：

package.json - npm 包配置和脚本
tsconfig.json - TypeScript 编译配置
webpack.config.js - Webpack 打包配置

常见问题

权限问题

确保在 HTTPS 环境下使用摄像头功能，大多数浏览器要求安全上下文才能访问摄像头。

移动端适配

在移动设备上，可能需要额外的样式调整来适应不同的屏幕尺寸。

性能优化

对于性能要求较高的场景，可以调整以下参数：

降低帧率（fps）
缩小扫描区域（qrbox）
只启用需要的扫描格式

浏览器兼容性

HTML5-QRCode 支持以下浏览器：

Chrome 60+
Firefox 55+
Safari 11+
Edge 79+

总结

HTML5-QRCode 是一个功能强大且易于使用的二维码和条形码扫描库，适用于各种 Web 应用场景。通过简单的 API 调用，开发者可以快速集成扫描功能到自己的项目中。

该库提供了灵活的配置选项和良好的浏览器兼容性，是开发二维码扫描功能的理想选择。

html5-qrcode

A cross platform HTML5 QR code reader. See end to end implementation at: https://scanapp.org

项目地址：https://gitcode.com/gh_mirrors/ht/html5-qrcode

登录后查看全文

项目优选

收起

本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

468

461

pytorch

Ascend Extension for PyTorch

本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。

CANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。

Python

1.03 K

642