@material-suite/scanner

一个功能强大的 Vue 3 扫码插件，支持多种扫码策略，包括条形码和二维码扫描。

✨ 特性

• 多策略支持: ML Kit、Capacitor 官方扫码、DataWedge、Web 摄像头四种扫码方式
• Vue 3 组合式 API: 提供 useScanner 可组合函数
• TypeScript 支持: 完整的类型定义和智能提示
• 跨平台兼容: 支持 Web、Android、iOS 等多个平台
• 自动策略选择: 根据运行环境自动选择最佳可用扫码策略
• 嵌入式组件: 支持内嵌式连续扫描和模态式单次扫描

📦 安装

核心安装

npm install @material-suite/scanner

必需依赖

# Vue 3 和 Capacitor 核心库
npm install vue@^3.3.0 @capacitor/core@^5.0.0

可选依赖（按需安装）

根据您的目标平台安装相应的扫码策略依赖：

# Android 平台 ML Kit 扫码（推荐用于 Android）
npm install @capacitor-mlkit/barcode-scanning

# Capacitor 官方扫码插件（跨平台支持）
npm install @capacitor/barcode-scanner

# Zebra 设备 DataWedge 硬件扫码
npm install capacitor-datawedge

# Web 摄像头扫码所需的 WASM 库
npm install @undecaf/zbar-wasm

🚀 快速开始

1. 插件安装

在您的 Vue 应用入口文件中安装扫码插件：

import { createApp } from 'vue'
import App from './App.vue'
import { scannerPlugin } from '@material-suite/scanner'

const app = createApp(App)
app.use(scannerPlugin)
app.mount('#app')

2. 使用组合式 API

在 Vue 组件中使用 useScanner 可组合函数：

<template>
  <div>
    <button @click="startScanning">开始扫码</button>
    <div v-if="scanResult">
      扫描结果: {{ scanResult }}
    </div>
    <div v-if="error" class="error">
      错误: {{ error }}
    </div>
  </div>
</template>

<script setup lang="ts">
import { useScanner } from '@material-suite/scanner'
import { ref } from 'vue'

const { start, onResult } = useScanner()
const scanResult = ref<string>('')
const error = ref<string>('')

// 监听扫码结果
onResult((result) => {
  if (result.success) {
    scanResult.value = result.result || ''
  } else if (result.error) {
    error.value = result.error
  }
})

const startScanning = async () => {
  scanResult.value = ''
  error.value = ''
  await start()
}
</script>

<style scoped>
.error {
  color: red;
}
</style>

3. 使用嵌入式扫描组件

对于需要连续扫描的场景，可以使用嵌入式扫描组件：

🔧 扫码策略详解

1. ML Kit 扫码 (ml-kit)

• 平台: 仅 Android
• 特点: 使用 Google ML Kit，识别速度快，准确率高
• 依赖: @capacitor-mlkit/barcode-scanning
• 优先级: 在 Android 设备上优先使用

2. Capacitor 官方扫码 (capacitor-official)

• 平台: 所有 Capacitor 平台（Android、iOS、Web）
• 特点: 官方维护，稳定性好，功能全面
• 依赖: @capacitor/barcode-scanner
• 优先级: 跨平台首选

3. DataWedge 扫码 (datawedge)

• 平台: Zebra 设备的 Android 系统
• 特点: 使用硬件扫码引擎，性能最优
• 依赖: capacitor-datawedge
• 优先级: Zebra 设备专用

4. Web 摄像头扫码 (web-camera)

• 平台: 浏览器环境
• 特点: 使用 ZBar WASM 库，纯 Web 方案
• 依赖: @undecaf/zbar-wasm
• 优先级: 浏览器环境备用方案

⚙️ 配置选项

插件安装时可以传递配置选项：

app.use(scannerPlugin, {
  // 是否启用调试日志
  debug: process.env.NODE_ENV === 'development',
  
  // 默认首选策略（按模式）
  preferredStrategies: {
    single: 'web', 
  },
  
  // Web 摄像头策略配置
  webCamera: {
    // WASM 文件路径配置
    wasmPath: '/zbar/',
    
    // 摄像头约束
    constraints: {
      width: { ideal: 1280 },
      height: { ideal: 720 },
      facingMode: { ideal: 'environment' }
    }
  }
})

📁 WASM 文件配置

Web 摄像头策略需要使用 ZBar WASM 文件，请按以下方式配置：

方案一：本地部署（推荐）

1. 安装 WASM 库：

   npm install @undecaf/zbar-wasm

2. 复制 WASM 文件到公共目录：

   # 创建目标目录
   mkdir -p public/zbar/
      
   # 复制 WASM 文件
   cp node_modules/@undecaf/zbar-wasm/dist/*.wasm public/zbar/

3. 确保服务器正确配置 WASM MIME 类型。

方案二：CDN 部署

如果您使用 CDN，可以修改 WASM 文件路径：

// 在应用启动时配置
if (typeof window !== 'undefined') {
  (window as any).ZBarWASM = (window as any).ZBarWASM || {};
  (window as any).ZBarWASM.locateFile = (filename: string) => {
    return `https://cdn.your-domain.com/zbar/${filename}`;
  };
}

🛠️ 构建和发布

开发构建

# 进入包目录
cd packages/scanner

# 安装依赖
npm install

# 开发模式构建（监听文件变化）
npm run dev

生产构建

# 生产构建
npm run build

# 构建后会生成 dist 目录，包含：
# - index.js (UMD 格式)
# - index.esm.js (ES 模块格式)
# - index.d.ts (类型声明文件)

发布到 npm

# 首先登录 npm
npm login

# 发布包
npm publish

# 如果使用组织范围包，确保 package.json 中的 name 正确
# "name": "@material-suite/scanner"

❓ 常见问题

Q1: 扫码策略如何选择？

A: 插件会自动根据环境选择最佳策略，优先级为：DataWedge > ML Kit > Capacitor Official > Web Camera。您也可以通过配置指定首选策略。

Q2: Web 摄像头扫码不工作？

A: 请检查：

1. WASM 文件是否正确部署
2. 浏览器是否支持摄像头访问
3. 是否使用了 HTTPS（本地开发除外）

Q3: Android 上无法使用 ML Kit？

A: 请确保：

1. 已安装 @capacitor-mlkit/barcode-scanning
2. 在 Android 设备上运行
3. 已处理摄像头权限

Q4: 如何自定义扫码界面？

A: 可以通过获取扫描组件来自定义：

const { getScannerComponent } = useScanner()
const scannerComponent = getScannerComponent('web-camera')

🐛 故障排除

构建错误

如果遇到构建错误，请检查：

1. 所有依赖是否正确安装
2. TypeScript 配置是否正确
3. 是否有缺失的类型定义

运行时错误

常见运行时错误及解决方案：

1. WASM 文件加载失败: 检查 WASM 文件路径配置
2. 摄像头权限拒绝: 确保用户授权摄像头访问
3. 策略不支持: 当前环境没有可用的扫码策略

📄 API 参考

scannerPlugin

Vue 插件安装函数，用于全局安装扫码功能。

useScanner()

返回扫码相关的函数和方法：

• start(): 开始单次扫码
• onResult(): 监听扫码结果
• getScannerComponent(): 获取嵌入式扫描组件

scannerManager

扫码策略管理器，用于高级配置：

• getSupportedStrategies(): 获取支持的策略列表
• getBestStrategy(): 获取最佳策略
• setPreferredStrategy(): 设置首选策略

📝 更新日志

v0.0.1

• 初始版本发布
• 支持四种扫码策略
• 提供组合式 API 和插件安装方式
• 完整的 TypeScript 支持

🔗 相关链接

• Vue 3 文档
• Capacitor 文档
• ZBar WASM 库

📜 许可证

MIT License - 详见 LICENSE 文件