scanonweb/README.md

ScanOnWeb - 扫描控件 JavaScript SDK，支持 v2 协议、scanSource 和增量图像事件

# ScanOnWeb

`scanonweb` 是一个通过 WebSocket 与本地 ScanOnWeb 托盘程序通信的 JavaScript SDK。

`2.0.0` 新协议：

- 所有命令默认发送 `protocolVersion: 2`
- 扫描来源改为 `scanSource: "flatbed" | "adf"`
- 支持增量图像事件：`scanPageAdded`、`imageEdited`、`imageMoved`、`imageDeleted`、`imagesCleared`
- 支持全量快照事件：`imageListSnapshot`、`imageSnapshot`
- 仍兼容旧服务端消息和旧回调名

## 安装

```bash
npm install scanonweb
```

## 快速开始

### ES Module

```js
import ScanOnWeb from "scanonweb";

const scanner = new ScanOnWeb();

scanner.scaner_work_config.scanSource = "adf";
scanner.scaner_work_config.autoFeed = true;
scanner.scaner_work_config.dupxMode = true;

scanner.onGetDevicesListEvent = (msg) => {
  console.log("devices:", msg.devices);
};

scanner.onScanPageAddedEvent = (msg) => {
  console.log("page added:", msg.imageId, msg.index);
};

scanner.onScanFinishedEvent = (msg) => {
  console.log("scan finished:", msg.loadedCount, msg.imageAfterCount);
};

scanner.startScan();
```

### CommonJS

```js
const ScanOnWeb = require("scanonweb");

const scanner = new ScanOnWeb();
scanner.startScan();
```

### Browser UMD

```html
<script src="node_modules/scanonweb/dist/scanonweb.umd.min.js"></script>
<script>
  const scanner = new ScanOnWeb();
  scanner.onImageListSnapshotEvent = (msg) => console.log(msg.imageInfos);
</script>
```

## 扫描配置

通过 `scanner.scaner_work_config` 修改默认扫描参数：

```js
scanner.scaner_work_config = {
  showUI: false,
  dpi_x: 300,
  dpi_y: 300,
  deviceIndex: 0,
  showDialog: false,
  scanSource: "flatbed",
  autoFeed: false,
  dupxMode: false,
  autoDeskew: false,
  autoBorderDetection: false,
  colorMode: "RGB",
  transMode: "memory",
};
```

### 关于 2.0 版本中的`scanSource`属性

- `scanSource: "flatbed"` 表示平板
- `scanSource: "adf"` 表示自动进纸器
- `autoFeedEnable` 只作为兼容旧版本服务端的遗留字段保留，不建议继续作为主配置使用，建议在代码中移除对autoFeedEnable属性的使用

## 推荐事件模型

建议按“增量事件 + 可选全量刷新”接入：

- `onScanPageAddedEvent`
  - 扫描过程中每新增一页就推送一页
- `onImageEditedEvent`
  - 托盘端编辑某一页后推送更新
- `onImageMovedEvent`
  - 托盘端或前端调整顺序后推送顺序变化
- `onImageDeletedEvent`
  - 删除单页
- `onImagesClearedEvent`
  - 清空全部结果
- `onImageListSnapshotEvent`
  - 主动调用 `getAllImage()` 后返回完整快照
- `onImageSnapshotEvent`
  - 主动调用 `getImageById(indexOrImageId)` 后返回单页快照

## 兼容性说明

- SDK 会把旧服务端返回的 `getAllImage` 自动归一化为 `imageListSnapshot`
- SDK 会把旧服务端返回的 `getImageById` 自动归一化为 `imageSnapshot`
- SDK 会把旧服务端返回的 `imageDrap` 自动归一化为 `imageMoved`
- 旧回调仍然会继续触发：
  - `onGetAllImageEvent`
  - `onGetImageByIdEvent`
  - `onImageDrapEvent`

## 常用 API

### 设备

- `loadDevices()`
- `selectScanDevice(deviceIndex)`

### 扫描

- `startScan()`
- `clearAll()`

### 图像

- `getImageCount()`
- `getAllImage()`
- `getImageById(indexOrImageId)`
- `rotateImage(index, angle)`
- `deleteImageByIndex(index, imageId?)`
- `moveImage(oldIndex, newIndex)`

### 上传

- `setUploadRequestHeaders(headers)`
- `uploadAllImageAsPdfToUrl(url, id, desc)`
- `uploadAllImageAsTiffToUrl(url, id, desc)`
- `uploadJpgImageByIndex(url, id, desc, index)`

上传请求头为当前 WebSocket 连接级别配置，设置一次后，后续上传命令会自动带上这些 HTTP header。常见场景是给本地托盘程序补充 `Authorization`、`Cookie`、`X-Token` 等认证信息。

```js
scanner.setUploadRequestHeaders({
  Authorization: "Bearer your-token",
  "X-Tenant": "tenant-a",
});

scanner.uploadAllImageAsPdfToUrl(
  "https://example.com/api/upload",
  "doc-001",
  "示例文档"
);

// 清空当前连接已设置的上传 header
scanner.setUploadRequestHeaders(null);
```

`setUploadRequestHeaders(headers)` 支持两种传法：

- 对象：`{ Authorization: "Bearer xxx", Cookie: "sid=abc" }`
- 数组：`[{ name: "Authorization", value: "Bearer xxx" }]`

上传相关回调（`onUploadAllImageAsPdfToUrlEvent` / `onUploadAllImageAsTiffToUrlEvent` / `onUploadJpgImageByIndexEvent`）中，SDK 会自动补齐这些标准化字段：

- `uploadResultJson`
  - 优先使用服务端返回的结构化结果；如果旧服务端只返回字符串，会自动尝试解析或回退生成对象
- `uploadSucceeded`
  - 归一化后的上传成功状态
- `uploadMessage`
  - 归一化后的上传提示信息

因此业务侧优先读取 `msg.uploadResultJson` 和 `msg.uploadMessage` 即可，不需要每个项目自己重复写 `JSON.parse(msg.uploadResult)`。

`setUploadRequestHeaders` 的响应会触发 `onSetUploadRequestHeadersEvent`，其中可读取：

- `uploadHeaderCount`
- `uploadHeaderNames`
- `headersCleared`

### 扩展加载能力

- `loadImageFromUrl(url, type?)`
- `loadImageFromBase64(base64Data, format?)`
- `loadMultipleImagesFromBase64(base64Images)`
- `loadImageFromCanvas(canvas, format?, quality?)`
- `loadImageFromFileInput(fileInput)`
- `openClientLocalMultipageFile()`

`openClientLocalMultipageFile()` 会调用本地托盘程序弹出文件选择框，支持导入本地多页 PDF/TIFF。完成后会触发 `onOpenClientLocalMultipageFileEvent` 回调，返回例如：

- `loadedCount`
- `sourcePageCount`
- `imageCount`
- `canceled`

## 更新日志

### 2.0.1
- 增加了打开本地多页图像文件的支持
- 新增了设置上传图像自定义http 请求头方法setUploadRequestHeaders

### 2.0.0

- 升级为 v2 协议
- 新增 `protocolVersion` 和 `serverProtocolVersion`
- 用 `scanSource` 取代歧义更大的 `autoFeedEnable` 作为主配置
- 新增快照/增量图像事件回调
- `getImageById` 支持传 `imageId`
- `deleteImageByIndex` 支持同时传 `imageId`
- 修复发布包缺少 `dist/index.d.ts`

### 1.0.3

- 添加 `moveImage`，支持前端调整扫描结果图像顺序

### 1.0.2

- 添加加载 Base64 图像支持
- `loadImageFromUrl` 支持常见图像格式

## 系统要求

- 需要本地安装并启动 ScanOnWeb 托盘服务程序
- 支持现代浏览器
- Node.js >= 14

## 许可证

MIT