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

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

2026-02-06 04:11:55作者：董宙帆
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

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
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
28
16
atomcodeatomcode
Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started
Rust
566
98
docsdocs
暂无描述
Dockerfile
708
4.51 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
413
339
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
958
955
pytorchpytorch
Ascend Extension for PyTorch
Python
572
694
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.6 K
940
cherry-studiocherry-studio
🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端
TypeScript
1.42 K
116
ppt-masterppt-master
AI 将任意文档转换为精美可编辑的 PPTX 演示文稿 — 无需设计基础 | 包含 15 个案例、229 页内容
Python
80
5
flutter_flutterflutter_flutter
暂无简介
Dart
951
235