更新记录

2.0.0（2026-06-14） 下载此版本

1.0.5（2025-07-12） 下载此版本

新增 静态销毁方法 // 销毁插件 jzH5ScanCode.destroy();

用于页面左滑返回 监听不了返回的情况 使用方法 import { onLoad, onBackPress } from "@dcloudio/uni-app";

onBackPress(() => { jzH5ScanCode.destroy(); })

1.0.4（2025-07-09） 下载此版本

--修复 在pc 网页中 canvas 画面变形 导致不能识别的问题，采用局部中心canvas 解决 --移除大量不必要的打印日志

平台兼容性

uni-app(4.62)

其他

jz-h5-scanCode

⚠️ 依赖安装说明

本插件依赖第三方解码库 @zxing/browser，使用前请务必在项目根目录安装：

npm install @zxing/browser

如果未安装此依赖，H5 环境下的扫码功能将无法正常工作。

🔍 插件简介

jz-h5-scanCode 是一个专为 H5 环境设计的二维码扫描插件，提供与 uni.scanCode 完全兼容的 API 接口。插件采用 Vue 组件动态挂载架构，调用 API 时自动将扫码组件挂载到页面，用户无需手动引入组件。

✨ 核心特性

🎯 API 兼容性

• 与 uni.scanCode API 完全兼容
• 支持相同的参数配置和回调函数
• 平台自动判断，H5 使用自定义实现，其他平台使用原生 API

📱 用户界面

• 微信风格设计：仿微信扫码界面，用户体验一致
• 全屏沉浸式：黑色背景，突出扫码区域
• 动态扫描线：绿色扫描线上下移动，提供视觉反馈
• 自定义配置：支持 8 种扫描框颜色选择

🔧 技术架构

• Vue 组件动态挂载：参考 Element UI 的 ElMessage 模式，调用 API 时自动挂载/卸载
• @zxing/browser 解码引擎：替代旧版 jsQR + BarcodeDetector，识别率更高、性能更好
• 智能降级：摄像头不可用时自动切换到图片选择模式
• 架构精简：核心功能精简为 3 个文件

📦 安装使用

1. uni-app 项目中使用

// 导入插件
import jzH5ScanCode from '@/uni_modules/jz-h5-scanCode/js/index.js'

// 基础扫码 - 无需引入组件，直接调用
jzH5ScanCode.scanCode({
    success: (res) => {
        console.log('扫码成功:', res.result)
    },
    fail: (res) => {
        console.log('扫码失败:', res.errMsg)
    }
})

2. 普通 H5 项目中使用

// ES6 模块导入
import jzH5ScanCode from './uni_modules/jz-h5-scanCode/js/index.js'

// 或者直接引入
<script type="module">
    import jzH5ScanCode from './uni_modules/jz-h5-scanCode/js/index.js'
    // 使用插件
</script>

🔧 API 文档

scanCode(options)

主要扫码方法，与 uni.scanCode API 完全兼容。

参数说明

回调参数

success 回调参数：

fail 回调参数：

使用示例

// 基础扫码
jzH5ScanCode.scanCode({
    success: (res) => {
        console.log('扫码结果:', res.result)
        console.log('扫码类型:', res.scanType)
        console.log('图像来源:', res.imageChannel)
    },
    fail: (res) => {
        console.log('扫码失败:', res.errMsg)
    },
    complete: () => {
        console.log('扫码完成')
    }
})

// 高级配置
jzH5ScanCode.scanCode({
    scanType: ['qrCode'],
    onlyFromCamera: true,
    scanFrameColor: '#007aff',
    success: (res) => {
        // 处理扫码结果
    }
})

静态方法

isCameraSupported()

检查设备是否支持摄像头。

const supported = await jzH5ScanCode.isCameraSupported()
console.log('摄像头支持:', supported)

isBarcodeDetectorSupported()

检查浏览器是否支持 BarcodeDetector API。

const supported = jzH5ScanCode.isBarcodeDetectorSupported()
console.log('BarcodeDetector 支持:', supported)

getSupportedFormats()

获取支持的条码格式。

const formats = await jzH5ScanCode.getSupportedFormats()
console.log('支持的格式:', formats)

getPluginInfo()

获取插件信息。

const info = jzH5ScanCode.getPluginInfo()
console.log('插件信息:', info)

destroy()

静态销毁方法，用于页面左滑返回等监听不了返回的情况。

import { onBackPress } from "@dcloudio/uni-app"

onBackPress(() => {
    jzH5ScanCode.destroy()
})

🎨 界面配置

扫描框颜色

插件支持 8 种预设颜色：

• #00ff00 - 绿色（默认）
• #007aff - 蓝色
• #ff3b30 - 红色
• #ff9500 - 橙色
• #ffcc00 - 黄色
• #34c759 - 青绿色
• #af52de - 紫色
• #ffffff - 白色

jzH5ScanCode.scanCode({
    scanFrameColor: '#007aff', // 蓝色扫描框
    success: (res) => {
        // 处理结果
    }
})

🏗️ 技术架构

核心模块

1. index.js - 主入口

• API 兼容性处理
• 平台判断逻辑
• Vue 组件动态挂载/卸载管理

2. scanner.js - 解码核心

• @zxing/browser 集成
• 摄像头流管理
• 图片解码功能
• 闪光灯控制

3. jz-h5-scanCode.vue - UI 组件

• 微信风格扫码界面
• 扫描动画效果
• 用户交互处理
• 响应式布局

识别流程

用户调用 jzH5ScanCode.scanCode(options)
    │
    ├─ 非 H5 环境 → uni.scanCode(options) → 结束
    │
    └─ H5 环境
        │
        ├─ 检查 isScanning → 是 → 返回 fail:busy
        │
        ├─ 创建 DOM 容器 → createApp(scanCodeVue) → mount
        │
        └─ Vue 组件 mounted
            │
            ├─ scanner.checkSupport() → 不支持 → emit('error')
            │
            ├─ scanner.startScan(video, canvas, options)
            │   │
            │   ├─ 成功识别 → emit('success', result)
            │   │
            │   └─ 摄像头失败 → 降级到图片选择
            │       │
            │       ├─ scanner.chooseImage()
            │       │
            │       └─ scanner.decodeImage() → emit('success'/'error')
            │
            └─ 用户点击返回 → emit('close')

🔍 识别引擎

@zxing/browser

• 优先级：唯一引擎
• 支持浏览器：所有现代浏览器
• 特点：纯 JavaScript 实现，兼容性好，识别率高
• 优势：无需 Worker 辅助，性能优于 jsQR

📱 浏览器兼容性

🛠️ 开发指南

本地开发

1. 环境要求

   • 现代浏览器
   • HTTPS 或 localhost 环境
   • HTTP 服务器（不能直接打开 HTML 文件）

2. 调试模式

   // 获取详细的调试信息
   const info = jzH5ScanCode.getPluginInfo()
   console.log('插件版本:', info.version)
   console.log('浏览器支持:', info.cameraSupported)
   console.log('识别引擎:', info.engine)

3. 常见问题

   • 摄像头权限：确保使用 HTTPS 或 localhost
   • 识别失败：检查二维码清晰度和光线条件
   • 界面异常：检查 CSS 样式冲突

依赖安装

npm install @zxing/browser

📊 性能优化

识别性能

• @zxing/browser 引擎：识别率高于 jsQR
• 智能采样：减少不必要的计算
• 扫描区域裁剪：仅识别扫描框内区域

内存管理

• 及时清理：组件卸载时自动释放摄像头资源
• Vue 组件卸载：app.unmount() + removeChild 完整清理
• 防重复调用：isScanning 状态锁控制

用户体验

• 快速响应：扫码成功立即返回
• 流畅动画：CSS 动画扫描线
• 错误提示：友好的错误信息

🔧 故障排除

常见问题

1. 摄像头无法启动

   • 检查是否使用 HTTPS 协议
   • 确认浏览器摄像头权限
   • 尝试刷新页面重新授权

2. 二维码识别失败

   • 确保二维码清晰可见
   • 调整光线条件
   • 尝试不同角度和距离

3. 界面显示异常

   • 检查 CSS 样式冲突
   • 确认 z-index 设置
   • 验证 DOM 结构完整性

4. 页面返回时界面未关闭

   • 使用 destroy() 方法手动关闭
   • 在 onBackPress 中调用 jzH5ScanCode.destroy()

调试信息

// 获取详细的调试信息
const info = jzH5ScanCode.getPluginInfo()
console.log('插件版本:', info.version)
console.log('浏览器支持:', info.cameraSupported)
console.log('识别引擎:', info.engine)
console.log('BarcodeDetector:', info.barcodeDetectorSupported)

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请通过以下方式联系：

• 提交 Issue
• 邮箱：[your-email@example.com]
• 文档：查看项目 README

版本: 2.0.0
更新时间: 2025年
作者: JZ