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

登录后查看全文

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

项目概述

安装和使用

通过 npm 安装

通过 CDN 引入

基本使用示例

核心 API

Html5QrcodeScanner 类

Html5Qrcode 类

配置选项

扫描配置

支持的格式

高级用法

只扫描特定格式

文件扫描

项目结构

开发指南

构建项目

项目配置

常见问题

权限问题

移动端适配

性能优化

浏览器兼容性

总结

热门内容推荐

最新内容推荐

项目优选

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

项目概述

安装和使用

通过 npm 安装

通过 CDN 引入

基本使用示例

核心 API

Html5QrcodeScanner 类

Html5Qrcode 类

配置选项

扫描配置

支持的格式

高级用法

只扫描特定格式

文件扫描

项目结构

开发指南

构建项目

项目配置

常见问题

权限问题

移动端适配

性能优化

浏览器兼容性

总结

相关内容推荐

热门内容推荐

最新内容推荐

项目优选