H5 Scanner

基于zbar的高性能H5二维码扫描器，同时支持zxing识别引擎。

功能介绍

• 高性能H5二维码扫描器
• 针对反光、低质量图像进行了专门优化
• 支持摄像头设备列表获取
• 支持摄像头状态查询
• 支持闪光灯切换
• 支持扫码错误回调
• 支持扫码成功回调
• 支持扫码性能指标回调

快速开始

1. 添加依赖

# npm yarn pnpm
npm install h5-scanner
yarn add h5-scanner
pnpm install h5-scanner
# 安装peerDependencies 需要的依赖
pnpm install @undecaf/zbar-wasm @zxing/library

2. 函数式调用

• 默认使用zbar扫码引擎，支持zxing引擎。
• 若使用zxing引擎，则需要使用 ZXingScanner。

import { bootstrap, error, destroy } from 'h5-scanner'

3. 开始扫码

// 第一步，获取Video元素
const videoElement = document.getElementById('video') as HTMLVideoElement
//或者在MVVM框架中获取，例如Vue3
const videoRef = ref<HTMLVideoElement>(null)
// Vue3新语法
const videoRef = useTemplateRef<HTMLVideoElement>('videoRef')

// 第二步，启动扫码器
// 扫码成功回调
const callback = (result: string, codeType: BarcodeFormat) => {
    console.log('扫码结果', result, '码类型', codeType)
}
// 扫码设备信息回调，可不传
const deviceCallback = (deviceInfo: DeviceInfo) => {
    console.log('设备信息', deviceInfo)
}
// 以Vue3为例，扫码器启动
bootstrap(videoRef.value, callback, deviceCallback)

// 扫码器异常监听，错误类型：ScannerErrorCode
error((err：ScannerError) => {
    console.error('扫码异常', err)
})

// 第三步，销毁扫码器
// 在正常从开发中，例如Vue3中，我们通常在onUnmounted中调用destroy()
destroy()

// 其他方法

其他方法

import { getCameraDevices, getCameraStatus, isCameraActive, switchCamera, toggleFlash } from 'h5-scanner'
// 获取摄像头设备列表
// 类型 () => Promise<MediaDeviceInfo[]>
getCameraDevices()
// 获取摄像头状态
// 类型 () => {
//     isActive: boolean
//     hasPermission: boolean
//     currentDeviceId: string | null
//     deviceCount: number
// }
getCameraStatus()
// 获取摄像头是否处于活跃状态`
// 类型 () => boolean
isCameraActive()
// 切换摄像头
// 类型 () => Promise<void>
switchCamera()
// 切换闪光灯
// 类型 () => Promise<void>
toggleFlash()

类型说明

// QR_CODE 二维码 
// CODE_128 128码
// CODE_39 39码
// EAN_13 13位EAN码
// EAN_8 8位EAN码
// UPC_A UPC-A码
// UPC_E UPC-E码
// DATA_MATRIX 数据矩阵码
// PDF_417 PDF417码
export type BarcodeFormat =
  | 'QR_CODE'
  | 'CODE_128'
  | 'CODE_39'
  | 'EAN_13'
  | 'EAN_8'
  | 'UPC_A'
  | 'UPC_E'
  | 'DATA_MATRIX'
  | 'PDF_417'

export type DeviceInfo = {
  hasCameraPermission: boolean
  hasFlash: boolean
  devices: MediaDeviceInfo[]
}

export type ScannerError = {
  code: ScannerErrorCode
  message: string
}
// 扫码器错误码
// NO_CAMERA_PERMISSION 无摄像头权限
// NO_CAMERA_DEVICE 无摄像头设备
// NO_MULTIPLE_CAMERA 无多摄像头设备
// NO_FLASH_SUPPORT 无闪光灯支持
// TOGGLE_FLASH_FAILED 切换闪光灯失败
// NO_VIDEO_ELEMENT 无Video元素
// NO_CALLBACK 无回调函数
// NO_IS_SECURE_CONNECTION 非安全连接
// VIDEO_DECODE_FAILED 视频解码失败
// CAMERA_ALREADY_ACTIVE 摄像头已激活
// ZBAR_INIT_FAILED ZBar初始化失败
// VIDEO_STREAM_FAILED 视频流失败
export enum ScannerErrorCode {
  NO_CAMERA_PERMISSION = 1001,
  NO_CAMERA_DEVICE = 1002,
  NO_MULTIPLE_CAMERA = 1003,
  NO_FLASH_SUPPORT = 1004,
  TOGGLE_FLASH_FAILED = 1005,
  NO_VIDEO_ELEMENT = 1006,
  NO_CALLBACK = 1007,
  NO_IS_SECURE_CONNECTION = 1008,
  VIDEO_DECODE_FAILED = 1009,
  CAMERA_ALREADY_ACTIVE = 1010,
  ZBAR_INIT_FAILED = 1011,
  VIDEO_STREAM_FAILED = 1012,
}

使用类方法

1. 使用Scanner类

import { Scanner } from 'h5-scanner'

// 启动扫码器，方法参照bootstrap方法，以Vue3为例
Scanner.bootstrap(videoRef.value, callback, deviceCallback)
// 扫码器异常监听，错误类型：ScannerErrorCode
Scanner.error((err：ScannerError) => {
    console.error('扫码异常', err)
})
// 销毁扫码器，方法参照destroy方法，以Vue3为例
onUnmounted(() => {
    Scanner.destroy()
})
// 获取摄像头设备列表
// 类型 () => Promise<MediaDeviceInfo[]>
Scanner.getCameraDevices()
// 获取摄像头状态
// 类型 () => {
//     isActive: boolean
//     hasPermission: boolean
//     currentDeviceId: string | null
//     deviceCount: number
// }
Scanner.getCameraStatus()
// 获取摄像头是否处于活跃状态`
// 类型 () => boolean
Scanner.isCameraActive()
// 切换摄像头
// 类型 () => Promise<void>
Scanner.switchCamera()
// 切换闪光灯
// 类型 () => Promise<void>
Scanner.toggleFlash()

2. 使用ZXingScanner类创建扫描器实例（zbar扫码能力要强过zxing的3倍以上）：

// ZXingScanner不提供函数式操作，只能通过类静态方法操作
import { ZXingScanner } from 'h5-scanner'
// 启动扫码器
ZXingScanner.bootstrap(videoRef.value, callback, deviceCallback)
// 扫码器异常监听，错误类型：ScannerErrorCode
ZXingScanner.error((err：ScannerError) => {
    console.error('扫码异常', err)
})
// 销毁扫码器，方法参照destroy方法，以Vue3为例
onUnmounted(() => {
    ZXingScanner.destroy()
})
// 获取摄像头设备列表
// 类型 () => Promise<MediaDeviceInfo[]>
ZXingScanner.getCameraDevices()
// 获取摄像头状态
// 类型 () => {
//     isActive: boolean
//     hasPermission: boolean
//     currentDeviceId: string | null
//     deviceCount: number
// }
ZXingScanner.getCameraStatus()
// 获取摄像头是否处于活跃状态`
// 类型 () => boolean
ZXingScanner.isCameraActive()
// 切换摄像头
// 类型 () => Promise<void>
ZXingScanner.switchCamera()
// 切换闪光灯
// 类型 () => Promise<void>
ZXingScanner.toggleFlash()