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

登录后查看全文

项目优选

收起

kernel

deepin linux kernel

docs

OpenHarmony documentation | OpenHarmony开发者文档

🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

Java

gitea

喝着茶写代码！最易用的自托管一站式代码托管平台，包含Git托管，代码审查，团队协作，软件包和CI/CD。

ops-math

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

🎉 基于Spring Boot、Spring Cloud & Alibaba、Vue3 & Vite、Element Plus的分布式前后端分离微服务架构权限管理系统