Html5-QRCode 是一个轻量级且跨平台的二维码和条形码扫描库，专为Web应用程序设计。它允许开发者轻松快速地集成二维码、条形码和其他常见代码扫描功能。
项目地址: https://gitcode.com/gh_mirrors/ht/html5-qrcode 项目技术架构
Html5-QRCode 基于 Zxing-js 库构建，提供了两种灵活的API：
Html5QrcodeScanner：提供端到端的扫描器UI，只需不到十行代码即可集成完整扫描功能Html5Qrcode：提供一组强大的底层API，允许开发者自定义UI，无需担心设备设置、权限处理、代码读取等复杂问题
核心特性
跨平台支持
支持 Android、iOS、MacOS、Windows 和 Linux 等主流操作系统，真正实现一次开发，多端运行。
多浏览器兼容
兼容 Chrome、Firefox、Safari、Edge、Opera 等主流浏览器，确保在各种环境下都能正常工作。
多功能扫描能力
支持扫描多种类型的条形码和二维码，包括：
- QR Code、AZTEC、DATA_MATRIX 等二维码格式
- CODE_39、CODE_93、CODE_128 等条形码格式
- EAN_13、EAN_8、UPC_A、UPC_E 等商品条码
灵活的扫描方式
- 设备扫描：直接使用设备进行实时扫描
- 文件扫描：支持选择本地图片文件进行扫描，无需上传到服务器
- 混合模式：可同时支持设备和文件扫描，用户自由选择
丰富的自定义选项
- 光线控制：支持在支持的设备上开启/关闭光线
- 缩放功能：可调整缩放级别
- 扫描区域定制：可设置特定的扫描区域大小和位置
- 帧率控制：可调整扫描帧率以优化性能
快速开始
安装方式
通过 npm 安装：
npm install html5-qrcode
或者使用 CDN：
<script src="https://unpkg.com/html5-qrcode/minified/html5-qrcode.min.js"></script>
基本使用示例
使用 Html5QrcodeScanner（带UI）：
// 创建扫描器实例
const html5QrcodeScanner = new Html5QrcodeScanner(
"reader",
{ fps: 10, qrbox: { width: 250, height: 250 } },
false
);
// 渲染扫描器
html5QrcodeScanner.render((decodedText, decodedResult) => {
console.log(`扫描结果: ${decodedText}`, decodedResult);
});
使用 Html5Qrcode（自定义UI）：
const html5QrCode = new Html5Qrcode("reader");
const qrCodeSuccessCallback = (decodedText, decodedResult) => {
console.log(`扫描结果: ${decodedText}`);
};
// 启动设备扫描
html5QrCode.start(
{ facingMode: "environment" },
{ fps: 10, qrbox: { width: 250, height: 250 } },
qrCodeSuccessCallback
);
高级配置选项
扫描区域设置
const config = {
fps: 10,
qrbox: { width: 300, height: 300 }, // 设置扫描框大小
aspectRatio: 1.777778, // 设置视频比例（16:9）
disableFlip: false, // 是否禁用水平翻转检测
rememberLastUsedCamera: true // 记住上次使用的设备
};
指定支持的扫描格式
const formatsToSupport = [
Html5QrcodeSupportedFormats.QR_CODE,
Html5QrcodeSupportedFormats.CODE_128,
Html5QrcodeSupportedFormats.EAN_13
];
const html5QrCode = new Html5Qrcode(
"reader",
{ formatsToSupport: formatsToSupport }
);
框架集成示例
Vue.js 集成
在 Vue 组件中使用：
import { Html5QrcodeScanner } from 'html5-qrcode';
export default {
mounted() {
this.setupScanner();
},
methods: {
setupScanner() {
const scanner = new Html5QrcodeScanner(
'reader',
{ fps: 10, qrbox: 250 },
false
);
scanner.render(this.onScanSuccess);
},
onScanSuccess(decodedText, decodedResult) {
this.$emit('scan-success', decodedText);
}
}
}
React 集成
使用专门的 React 封装库：
npm install html5-qrcode-react
性能优化建议
- 合理设置帧率：根据实际需求调整 fps 值，平衡性能和扫描速度
- 限制扫描格式：如果只需要特定格式，明确指定以减少不必要的解码尝试
- 使用合适的扫描区域：根据二维码大小设置合适的 qrbox 尺寸
- 及时清理资源：在组件卸载时调用
html5QrCode.stop()释放设备资源
常见问题解决
权限问题
确保网站在安全上下文（HTTPS 或 localhost）中运行，以便正确请求设备权限。
移动端兼容性
iOS 设备需要 iOS 15.1+ 版本才能在其他浏览器中使用设备功能，Safari 浏览器支持更早版本。
设备无法启动
检查浏览器控制台错误信息，常见原因包括：
- 设备被其他应用占用
- 浏览器权限设置阻止设备访问
- 不支持的视频格式
项目结构
html5-qrcode/
├── src/ # 源代码目录
│ ├── camera/ # 设备相关功能
│ ├── ui/ # 用户界面组件
│ └── core.ts # 核心功能实现
├── examples/ # 使用示例
│ ├── html5/ # 纯HTML5示例
│ ├── vuejs/ # Vue.js示例
│ ├── electron/ # Electron示例
│ └── lit/ # Lit示例
├── dist/ # 构建输出
└── tests/ # 测试代码
开发与贡献
项目采用 TypeScript 开发，构建流程简单：
- 安装依赖：
npm install - 构建项目：
npm run build - 运行测试：
npm test
欢迎提交 Issue 和 Pull Request 来帮助改进项目。
应用场景
Html5-QRCode 适用于多种应用场景：
- 电子商务：商品条码扫描、二维码支付
- 门禁系统：二维码门禁、电子票务验证
- 物流管理：包裹追踪、库存管理
- 教育培训：课程签到、资料获取
- 营销活动：活动签到、优惠券兑换
该项目提供了稳定可靠的二维码扫描解决方案，无论您是开发小型项目还是大型企业应用，都能满足您的扫描需求。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
