更新记录

1.0.0（2025-08-01）

原zbar插件地址：https://ext.dcloud.net.cn/plugin?id=1386 现基于此插件库升级为uts插件，并重构插件实现逻辑，添加更多的选项

基于ZBar原生库的高精度二维码扫描插件，当前支持Android平台，ios后续支持

平台兼容性

云端兼容性

uni-app(4.75)

uni-app x(4.75)

多库二维码扫描插件

支持多种扫描库的 uniapp-x 原生二维码扫描插件，支持 Android 和 iOS 平台。

功能特性

• 🚀 多库支持：集成 ZXing、ZBar、ML Kit 三种主流扫描库（目前只支持zBar，后续支持ML Kit）
• 📱 双平台支持：暂时支持 Android，IOS后续加入支持
• 🎨 自定义界面：可配置扫描框颜色、超时时间等参数
• ⚡ 多格式支持：支持 QR Code、Data Matrix、PDF417 等多种格式（目前仅支持二维码，后续加入其他码类型）
• 🔔 震动反馈：支持扫描成功后的震动提示
• ⏰ 超时控制：可设置扫描超时时间
• 🔒 权限管理：自动处理相机权限申请
• 🔄 灵活切换：可通过参数选择使用哪种扫描库

支持的扫描库

安装使用

1. 导入插件

将 zbar-scanner 插件文件夹放入项目的 uni_modules 目录下。

2. 基础用法

（1）uniapp

import { scanQRCode, checkCameraPermission, requestCameraPermission } from '@/uni_modules/zbar-scanner'

export default {
  methods: {
    async startScan() {
      try {
        // 准备扫描参数
        const options : ZbarScannerOptions = {
            timeout: 30000,
            vibrate: true,
            scanColor: '#00FF00',
            scannerType: 'zbar',
            cameraFacing: 'back',
            flashlight: false
        }
        const result = await scanQRCode(options)
        console.log('扫描结果:', result)
        uni.showToast({
          title: '扫描成功',
          icon: 'success'
        })
      } catch (error) {
        console.error('扫描失败:', error)
        uni.showToast({
          title: '扫描失败',
          icon: 'error'
        })
      }
    }
  }
}

（2）uniapp-X

import { scanQRCode, checkCameraPermission, requestCameraPermission, type ZbarScannerOptions, type ScannerType, type CameraFacing } from '@/uni_modules/zbar-scanner'

    // 响应式数据
    const title = ref('开始扫码')

    // 页面加载
    onLoad(() => {
        // 页面初始化逻辑
    })

    // 开始扫描方法
    const startScan = async () => {
        try {
            // 检查相机权限
            console.log('检查相机权限...')
            const hasPermission = await checkCameraPermission()
            if (!hasPermission) {
                console.log('请求相机权限...')
                const granted = await requestCameraPermission()
                if (!granted) { 
                    uni.showToast({
                        title: '需要相机权限才能扫描',
                        icon: 'none'
                    })
                    return
                }
            }

            // 准备扫描参数
            const options : ZbarScannerOptions = {
                timeout: 30000,
                vibrate: true,
                scanColor: '#00FF00',
                scannerType: 'zbar',
                cameraFacing: 'back',
                flashlight: false
            }

            console.log('开始扫描，参数:', options)

            // 开始扫描
            const result = await scanQRCode(options)

            console.log('扫描成功:', result)
            uni.showToast({
                title: `扫描结果:${result}`,
                icon: 'success'
            }) 

        } catch (error : any) {
            console.error('扫描失败:', error)
            uni.showToast({
                title: `扫描失败: ${error.message}`,
                icon: 'error'
            })
        }
    }

3. 选择扫描库

// 使用 ZXing 库扫描（后续加入）
const result = await scanQRCode({
  scannerType: 'zxing',
  timeout: 30000,
  vibrate: true,
  scanColor: '#00FF00',
  cameraFacing: 'back',
  flashlight: false
})

// 使用 ML Kit 扫描（后续加入）
const result = await scanQRCode({
  scannerType: 'mlkit',
  timeout: 15000,
  vibrate: true,
  scanColor: '#FF0000',
  cameraFacing: 'back',
  flashlight: false
})

// 使用 ZBar 库扫描（推荐）
const result = await scanQRCode({
  scannerType: 'zbar',
  timeout: 20000,
  vibrate: false,
  scanColor: '#0000FF',
  cameraFacing: 'back',
  flashlight: false
})

// 使用模拟扫描（测试用）
const result = await scanQRCode({
  scannerType: 'simulate',
  timeout: 3000,
  vibrate: true,
  scanColor: '#FFFF00',
  cameraFacing: 'back',
  flashlight: false
})

4. 完整配置示例

const options = {
  scannerType: 'zxing',    // 扫描库类型：'zxing' | 'mlkit' | 'zbar' | 'simulate'
  timeout: 30000,          // 扫描超时时间（毫秒）
  vibrate: true,           // 是否启用震动反馈
  scanColor: '#00FF00'     // 扫描框颜色
  cameraFacing: 'back',   // 前置 front/后置 back
  flashlight: false        // true 开启闪光灯 false 禁用闪光灯  
}

const result = await scanQRCode(options)

4. 权限检查

// 检查相机权限
const hasPermission = await checkCameraPermission()
if (!hasPermission) {
  // 请求相机权限
  const granted = await requestCameraPermission()
  if (!granted) {
    uni.showToast({
      title: '需要相机权限才能扫描',
      icon: 'none'
    })
    return
  }
}

5、重要说明

由于插件使用了第三方依赖，在插件市场导入后必须打包自定义基座后方可正常运行。

API 文档

scanQRCode(options?)

开始扫描二维码

参数：

• options (可选): 扫描配置选项
  • scannerType: 'zxing' | 'mlkit' | 'zbar' | 'simulate' - 扫描库类型，默认 'zxing'
  • timeout: number - 扫描超时时间，默认 30000 毫秒
  • vibrate: boolean - 是否启用震动反馈，默认 true
  • scanColor: string - 扫描框颜色，默认 '#00FF00'
  • cameraFacing: string - 前置摄像头和后置摄像头，前置：frnot 后置：back， 默认 'back'
  • flashlight: boolean - 是否开启闪光灯功能，默认 false

返回值：

• Promise<string> - 扫描结果字符串

扫描库说明：

• zxing: 使用 ZXing 库，成熟稳定，识别率高
• mlkit: 使用 Google ML Kit，AI 驱动，精度高
• zbar: 使用 ZBar 库，轻量级，速度快
• simulate: 模拟扫描，用于测试和演示

checkCameraPermission()

检查相机权限状态

返回值：

• Promise<boolean> - 是否有相机权限

requestCameraPermission()

请求相机权限

返回值：

• Promise<boolean> - 是否授权成功

支持的二维码格式

• QR Code
• Data Matrix
• PDF417
• Code 128
• Code 39
• Code 93
• EAN-8
• EAN-13
• UPC-E
• Aztec

平台兼容性

注意事项

1. 权限配置：插件会自动处理相机权限申请，但需要确保 manifest.json 中已配置相机权限。

2. Android 依赖：Android 平台依赖 ZBar 原生库，首次编译时会自动下载。

3. iOS 配置：iOS 平台需要在 Info.plist 中配置相机使用说明。

4. 性能优化：扫描过程中会占用较多 CPU 资源，建议在扫描完成后及时释放资源。

常见问题

Q: 扫描速度慢怎么办？

A: 可以尝试调整扫描超时时间，或确保扫描环境光线充足。

Q: 无法识别某些二维码？

A: 请确保二维码清晰完整，避免反光或模糊。

Q: Android 编译失败？

A: 请检查网络连接，确保能正常下载 ZBar 依赖库。

更新日志

v1.0.0

• 初始版本发布
• 支持基础二维码扫描功能
• 支持 Android

许可证

MIT License