npm package: @material-suite/scanner
Description: A versatile Vue 3 scanner plugin with multiple scanning strategies
Latest version: 0.0.3

# @material-suite/scanner

一个功能强大的 Vue 3 扫码插件，支持多种扫码策略，包括条形码和二维码扫描。

## ✨ 特性

- **多策略支持**: ML Kit、Capacitor 官方扫码、DataWedge、Web 摄像头四种扫码方式
- **Vue 3 组合式 API**: 提供 [`useScanner`](packages/scanner/useScanner.ts:12) 可组合函数
- **TypeScript 支持**: 完整的类型定义和智能提示
- **跨平台兼容**: 支持 Web、Android、iOS 等多个平台
- **自动策略选择**: 根据运行环境自动选择最佳可用扫码策略
- **嵌入式组件**: 支持内嵌式连续扫描和模态式单次扫描

## 📦 安装

### 核心安装

```bash
npm install @material-suite/scanner
```

### 必需依赖

```bash
# Vue 3 和 Capacitor 核心库
npm install vue@^3.3.0 @capacitor/core@^5.0.0
```

### 可选依赖（按需安装）

根据您的目标平台安装相应的扫码策略依赖：

```bash
# 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 应用入口文件中安装扫码插件：

```typescript
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`](packages/scanner/useScanner.ts:12) 可组合函数：

```vue
<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`
- **优先级**: 浏览器环境备用方案

## ⚙️ 配置选项

插件安装时可以传递配置选项：

```typescript
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 库：
   ```bash
   npm install @undecaf/zbar-wasm
   ```

2. 复制 WASM 文件到公共目录：
   ```bash
   # 创建目标目录
   mkdir -p public/zbar/
   
   # 复制 WASM 文件
   cp node_modules/@undecaf/zbar-wasm/dist/*.wasm public/zbar/
   ```

3. 确保服务器正确配置 WASM MIME 类型。

### 方案二：CDN 部署

如果您使用 CDN，可以修改 WASM 文件路径：

```typescript
// 在应用启动时配置
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}`;
  };
}
```

## 🛠️ 构建和发布

### 开发构建

```bash
# 进入包目录
cd packages/scanner

# 安装依赖
npm install

# 开发模式构建（监听文件变化）
npm run dev
```

### 生产构建

```bash
# 生产构建
npm run build

# 构建后会生成 dist 目录，包含：
# - index.js (UMD 格式)
# - index.esm.js (ES 模块格式)
# - index.d.ts (类型声明文件)
```

### 发布到 npm

```bash
# 首先登录 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: 可以通过获取扫描组件来自定义：
```typescript
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 文档](https://v3.vuejs.org/)
- [Capacitor 文档](https://capacitorjs.com/)
- [ZBar WASM 库](https://github.com/undecaf/zbar-wasm)

## 📜 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件