scanonweb/README.md

ScanOnWeb - 扫描控件 JavaScript SDK，用于与本地扫描服务程序通信

# ScanOnWeb

ScanOnWeb 是一个用于与本地扫描服务程序通信的 JavaScript SDK。它通过 WebSocket 连接与本地扫描托盘程序进行通信，提供完整的扫描功能。

## 特性

- 🔌 WebSocket 通信，支持多端口自动连接
- 📄 支持多种扫描模式（彩色、黑白、灰度）
- 🖼️ 支持图像处理（旋转、编辑、删除）
- 📤 支持多种上传格式（PDF、TIFF、JPG）
- 🔧 支持双面扫描、自动进纸等高级功能
- 📱 支持多种模块格式（UMD、ESM、CJS）
- 🎯 TypeScript 支持

## 安装

```bash
npm install scanonweb
```

## 使用方法

### ES6 模块

```javascript
import ScanOnWeb from 'scanonweb';

const scanner = new ScanOnWeb();

// 设置事件回调
scanner.onGetDevicesListEvent = (msg) => {
  console.log('扫描设备列表:', msg);
};

scanner.onScanFinishedEvent = (msg) => {
  console.log('扫描完成:', msg);
};

// 开始扫描
scanner.startScan();
```

### CommonJS

```javascript
const ScanOnWeb = require('scanonweb');

const scanner = new ScanOnWeb();
// ... 使用方法同上
```

### 浏览器 UMD

```html
<script src="node_modules/scanonweb/dist/scanonweb.umd.min.js"></script>
<script>
  const scanner = new ScanOnWeb();
  
  scanner.onScanFinishedEvent = function(msg) {
    console.log('扫描完成:', msg);
  };
  
  scanner.startScan();
</script>
```

### Vue 3 使用示例

```vue
<template>
  <div>
    <button @click="startScan">开始扫描</button>
    <button @click="getDevices">获取设备列表</button>
  </div>
</template>

<script setup>
import { onMounted, ref } from 'vue';
import ScanOnWeb from 'scanonweb';

const scanner = ref(null);

onMounted(() => {
  scanner.value = new ScanOnWeb();
  
  // 设置回调函数
  scanner.value.onGetDevicesListEvent = (msg) => {
    console.log('设备列表:', msg);
  };
  
  scanner.value.onScanFinishedEvent = (msg) => {
    console.log('扫描完成:', msg);
  };
});

const startScan = () => {
  scanner.value?.startScan();
};

const getDevices = () => {
  scanner.value?.loadDevices();
};
</script>
```

## API 文档

### 构造函数

```javascript
const scanner = new ScanOnWeb();
```

### 配置参数

扫描配置参数可以通过 `scanner.scaner_work_config` 访问和修改：

```javascript
scanner.scaner_work_config = {
  showUI: false,           // 是否显示扫描控件工作界面
  dpi_x: 300,             // DPI 分辨率 X
  dpi_y: 300,             // DPI 分辨率 Y
  deviceIndex: 0,         // 选中的扫描仪设备索引
  showDialog: false,      // 是否显示设备内置对话框
  autoFeedEnable: true,   // 是否使用自动进纸器
  autoFeed: false,        // 是否自动装填纸张
  dupxMode: false,        // 是否使用双面扫描模式
  autoDeskew: false,      // 是否使用自动纠偏模式
  autoBorderDetection: false, // 是否使用自动边框检测
  colorMode: 'RGB',       // 色彩模式: 'RGB', 'BW', 'GRAY'
  transMode: 'memory'     // 数据传输模式: 'memory', 'file', 'native'
};
```

### 主要方法

#### 设备管理
- `loadDevices()` - 加载所有可用的扫描设备
- `selectScanDevice(deviceIndex)` - 选择扫描设备

#### 扫描操作
- `startScan()` - 开始扫描
- `clearAll()` - 清除全部扫描结果

#### 图像操作
- `getImageCount()` - 获取图像总数
- `getAllImage()` - 获取所有图像
- `getImageById(index)` - 获取指定索引的图像
- `rotateImage(index, angle)` - 旋转图像
- `deleteImageByIndex(index)` - 删除指定图像

#### 上传功能
- `uploadAllImageAsPdfToUrl(url, id, desc)` - 以PDF格式上传所有图像
- `uploadAllImageAsTiffToUrl(url, id, desc)` - 以TIFF格式上传所有图像
- `uploadJpgImageByIndex(url, id, desc, index)` - 以JPG格式上传指定图像

### 事件回调

设置事件回调函数来处理扫描过程中的各种事件：

```javascript
// 获取设备列表回调
scanner.onGetDevicesListEvent = (msg) => {
  console.log('设备列表:', msg);
};

// 扫描完成回调
scanner.onScanFinishedEvent = (msg) => {
  console.log('扫描完成，图像数量:', msg.imageCount);
};

// 选择设备回调
scanner.onSelectScanDeviceEvent = (msg) => {
  console.log('设备选择完成:', msg);
};

// 获取图像回调
scanner.onGetImageByIdEvent = (msg) => {
  console.log('获取图像:', msg);
};
```

## 系统要求

- 需要安装对应的扫描托盘服务程序
- 支持的浏览器：Chrome、Firefox、Safari、Edge
- Node.js >= 14.0.0（用于服务端）

## 许可证

MIT License

## 技术支持

如需更多文档帮助请访问官网：https://www.brainysoft.cn

## 更新日志

### 1.0.1
- 初始版本发布
- 支持基本扫描功能
- 支持多种输出格式
- 添加 TypeScript 支持