scanonweb 1.0.3 → 2.0.0

package/README.md

@@ -1,16 +1,14 @@
 # ScanOnWeb
 
-ScanOnWeb 是一个用于与本地扫描服务程序通信的 JavaScript SDK。它通过 WebSocket 连接与本地扫描托盘程序进行通信，提供完整的扫描功能。
+`scanonweb` 是一个通过 WebSocket 与本地 ScanOnWeb 托盘程序通信的 JavaScript SDK。
 
-## 特性
+`2.0.0` 新协议：
 
-- 🔌 WebSocket 通信，支持多端口自动连接
-- 📄 支持多种扫描模式（彩色、黑白、灰度）
-- 🖼️ 支持图像处理（旋转、编辑、删除）
-- 📤 支持多种上传格式（PDF、TIFF、JPG）
-- 🔧 支持双面扫描、自动进纸等高级功能
-- 📱 支持多种模块格式（UMD、ESM、CJS）
-- 🎯 TypeScript 支持
+- 所有命令默认发送 `protocolVersion: 2`
+- 扫描来源改为 `scanSource: "flatbed" | "adf"`
+- 支持增量图像事件：`scanPageAdded`、`imageEdited`、`imageMoved`、`imageDeleted`、`imagesCleared`
+- 支持全量快照事件：`imageListSnapshot`、`imageSnapshot`
+- 仍兼容旧服务端消息和旧回调名
 
 ## 安装
 
@@ -18,195 +16,171 @@ ScanOnWeb 是一个用于与本地扫描服务程序通信的 JavaScript SDK。
 npm install scanonweb
 ```
 
-## 使用方法
+## 快速开始
 
-### ES6 模块
+### ES Module
 
-```javascript
-import ScanOnWeb from 'scanonweb';
+```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('扫描设备列表:', msg);
+  console.log("devices:", msg.devices);
+};
+
+scanner.onScanPageAddedEvent = (msg) => {
+  console.log("page added:", msg.imageId, msg.index);
 };
 
 scanner.onScanFinishedEvent = (msg) => {
-  console.log('扫描完成:', msg);
+  console.log("scan finished:", msg.loadedCount, msg.imageAfterCount);
 };
 
-// 开始扫描
 scanner.startScan();
 ```
 
 ### CommonJS
 
-```javascript
-const ScanOnWeb = require('scanonweb');
+```js
+const ScanOnWeb = require("scanonweb");
 
 const scanner = new ScanOnWeb();
-// ... 使用方法同上
+scanner.startScan();
 ```
 
-### 浏览器 UMD
+### Browser 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();
+  scanner.onImageListSnapshotEvent = (msg) => console.log(msg.imageInfos);
 </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();
-};
+## 扫描配置
+
+通过 `scanner.scaner_work_config` 修改默认扫描参数：
 
-const getDevices = () => {
-  scanner.value?.loadDevices();
+```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",
 };
-</script>
 ```
 
-## API 文档
+### 关于 2.0 版本中的`scanSource`属性
 
-### 构造函数
+- `scanSource: "flatbed"` 表示平板
+- `scanSource: "adf"` 表示自动进纸器
+- `autoFeedEnable` 只作为兼容旧版本服务端的遗留字段保留，不建议继续作为主配置使用，建议在代码中移除对autoFeedEnable属性的使用
 
-```javascript
-const scanner = new ScanOnWeb();
-```
+## 推荐事件模型
 
-### 配置参数
+建议按“增量事件 + 可选全量刷新”接入：
 
-扫描配置参数可以通过 `scanner.scaner_work_config` 访问和修改：
+- `onScanPageAddedEvent`
+  - 扫描过程中每新增一页就推送一页
+- `onImageEditedEvent`
+  - 托盘端编辑某一页后推送更新
+- `onImageMovedEvent`
+  - 托盘端或前端调整顺序后推送顺序变化
+- `onImageDeletedEvent`
+  - 删除单页
+- `onImagesClearedEvent`
+  - 清空全部结果
+- `onImageListSnapshotEvent`
+  - 主动调用 `getAllImage()` 后返回完整快照
+- `onImageSnapshotEvent`
+  - 主动调用 `getImageById(indexOrImageId)` 后返回单页快照
 
-```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'
-};
-```
+## 兼容性说明
 
-### 主要方法
+- SDK 会把旧服务端返回的 `getAllImage` 自动归一化为 `imageListSnapshot`
+- SDK 会把旧服务端返回的 `getImageById` 自动归一化为 `imageSnapshot`
+- SDK 会把旧服务端返回的 `imageDrap` 自动归一化为 `imageMoved`
+- 旧回调仍然会继续触发：
+  - `onGetAllImageEvent`
+  - `onGetImageByIdEvent`
+  - `onImageDrapEvent`
 
-#### 设备管理
-- `loadDevices()` - 加载所有可用的扫描设备
-- `selectScanDevice(deviceIndex)` - 选择扫描设备
+## 常用 API
 
-#### 扫描操作
-- `startScan()` - 开始扫描
-- `clearAll()` - 清除全部扫描结果
+### 设备
 
-#### 图像操作
-- `getImageCount()` - 获取图像总数
-- `getAllImage()` - 获取所有图像
-- `getImageById(index)` - 获取指定索引的图像
-- `rotateImage(index, angle)` - 旋转图像
-- `deleteImageByIndex(index)` - 删除指定图像
-- `moveImage(oldIndex, newIndex)` - 调整图像顺序（将 oldIndex 移动到 newIndex）
+- `loadDevices()`
+- `selectScanDevice(deviceIndex)`
 
-#### 上传功能
-- `uploadAllImageAsPdfToUrl(url, id, desc)` - 以PDF格式上传所有图像
-- `uploadAllImageAsTiffToUrl(url, id, desc)` - 以TIFF格式上传所有图像
-- `uploadJpgImageByIndex(url, id, desc, index)` - 以JPG格式上传指定图像
+### 扫描
 
-### 事件回调
+- `startScan()`
+- `clearAll()`
 
-设置事件回调函数来处理扫描过程中的各种事件：
+### 图像
 
-```javascript
-// 获取设备列表回调
-scanner.onGetDevicesListEvent = (msg) => {
-  console.log('设备列表:', msg);
-};
+- `getImageCount()`
+- `getAllImage()`
+- `getImageById(indexOrImageId)`
+- `rotateImage(index, angle)`
+- `deleteImageByIndex(index, imageId?)`
+- `moveImage(oldIndex, newIndex)`
 
-// 扫描完成回调
-scanner.onScanFinishedEvent = (msg) => {
-  console.log('扫描完成，图像数量:', msg.imageCount);
-};
+### 上传
 
-// 选择设备回调
-scanner.onSelectScanDeviceEvent = (msg) => {
-  console.log('设备选择完成:', msg);
-};
+- `uploadAllImageAsPdfToUrl(url, id, desc)`
+- `uploadAllImageAsTiffToUrl(url, id, desc)`
+- `uploadJpgImageByIndex(url, id, desc, index)`
 
-// 获取图像回调
-scanner.onGetImageByIdEvent = (msg) => {
-  console.log('获取图像:', msg);
-};
-```
+### 扩展加载能力
 
-## 系统要求
+- `loadImageFromUrl(url, type?)`
+- `loadImageFromBase64(base64Data, format?)`
+- `loadMultipleImagesFromBase64(base64Images)`
+- `loadImageFromCanvas(canvas, format?, quality?)`
+- `loadImageFromFileInput(fileInput)`
+
+## 更新日志
 
-- 需要安装对应的扫描托盘服务程序
-- 支持的浏览器：Chrome、Firefox、Safari、Edge
-- Node.js >= 14.0.0（用于服务端）
+### 2.0.0
 
-## 许可证
+- 升级为 v2 协议
+- 新增 `protocolVersion` 和 `serverProtocolVersion`
+- 用 `scanSource` 取代歧义更大的 `autoFeedEnable` 作为主配置
+- 新增快照/增量图像事件回调
+- `getImageById` 支持传 `imageId`
+- `deleteImageByIndex` 支持同时传 `imageId`
+- 修复发布包缺少 `dist/index.d.ts`
 
-MIT License
+### 1.0.3
 
-## 技术支持
+- 添加 `moveImage`，支持前端调整扫描结果图像顺序
 
-如需更多文档帮助请访问官网：https://www.brainysoft.cn
+### 1.0.2
 
-## 更新日志
+- 添加加载 Base64 图像支持
+- `loadImageFromUrl` 支持常见图像格式
 
-### 1.0.3
-- 添加了支持前端直接调整扫描结果图像顺序的能力,前端可以通过moveImage函数调整结果图像顺序
+## 系统要求
 
+- 需要本地安装并启动 ScanOnWeb 托盘服务程序
+- 支持现代浏览器
+- Node.js >= 14
 
-### 1.0.2
-- 添加了对加载base64格式图像的支持
-- 远程加载图像除了支持pdf和tiff格式，现在也支持加载jpg、png等常见格式的图像
-
-### 1.0.1
-- 初始版本发布
-- 支持基本扫描功能
-- 支持多种输出格式
-- 添加 TypeScript 支持
+## 许可证
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+export type ScanSource = "flatbed" | "adf";
+export type ColorMode = "RGB" | "BW" | "GRAY";
+export type TransferMode = "memory" | "file" | "native";
+
+export interface ScanConfig {
+  showUI: boolean;
+  dpi_x: number;
+  dpi_y: number;
+  deviceIndex: number;
+  showDialog: boolean;
+  scanSource: ScanSource;
+  autoFeed: boolean;
+  dupxMode: boolean;
+  autoDeskew: boolean;
+  autoBorderDetection: boolean;
+  colorMode: ColorMode;
+  transMode: TransferMode;
+  /** Legacy compatibility only. Prefer `scanSource`. */
+  autoFeedEnable?: boolean;
+}
+
+export interface ImageInfo {
+  index: number;
+  imageId?: string;
+  width?: number;
+  height?: number;
+  imageBase64?: string;
+  [key: string]: any;
+}
+
+export interface WebSocketMessage {
+  cmd_type: string;
+  protocolVersion?: number;
+  ok?: boolean;
+  success?: boolean;
+  imageCount?: number;
+  currentIndex?: number;
+  currentSelected?: number;
+  selectedImageId?: string | null;
+  imageId?: string;
+  imageIndex?: number;
+  index?: number;
+  oldIndex?: number;
+  newIndex?: number;
+  beforeIndex?: number;
+  afterIndex?: number;
+  beforeImageCount?: number;
+  afterImageCount?: number;
+  scanSource?: ScanSource;
+  autoFeedEnable?: boolean;
+  autoFeed?: boolean;
+  dupxMode?: boolean;
+  autoDeskew?: boolean;
+  autoBorderDetection?: boolean;
+  colorMode?: ColorMode | string;
+  transMode?: TransferMode | string;
+  scanJobId?: string;
+  source?: string;
+  loadedCount?: number;
+  imageAfterCount?: number;
+  images?: string[];
+  imageInfos?: ImageInfo[];
+  imageBase64?: string;
+  devices?: any[];
+  [key: string]: any;
+}
+
+export interface Base64ImagePayload {
+  data: string;
+  format?: string;
+}
+
+export default class ScanOnWeb {
+  protocolVersion: number;
+  serverProtocolVersion: number | null;
+  scaner_work_config: ScanConfig & {
+    /** Legacy compatibility only. Prefer `scanSource`. */
+    autoFeedEnable?: boolean;
+  };
+  h5socket: WebSocket | null;
+  imageCount: number;
+
+  onGetDevicesListEvent?: (msg: WebSocketMessage) => void;
+  onScanFinishedEvent?: (msg: WebSocketMessage) => void;
+  onSelectScanDeviceEvent?: (msg: WebSocketMessage) => void;
+  onGetImageCountEvent?: (msg: WebSocketMessage) => void;
+  onImageListSnapshotEvent?: (msg: WebSocketMessage) => void;
+  onImageSnapshotEvent?: (msg: WebSocketMessage) => void;
+  onScanPageAddedEvent?: (msg: WebSocketMessage) => void;
+  onGetAllImageEvent?: (msg: WebSocketMessage) => void;
+  onGetImageByIdEvent?: (msg: WebSocketMessage) => void;
+  onLoadImageFromUrlEvent?: (msg: WebSocketMessage) => void;
+  onLoadImageFromBase64Event?: (msg: WebSocketMessage) => void;
+  onRotateImageEvent?: (msg: WebSocketMessage) => void;
+  onGetImageSizeEvent?: (msg: WebSocketMessage) => void;
+  onUploadAllImageAsPdfToUrlEvent?: (msg: WebSocketMessage) => void;
+  onUploadAllImageAsTiffToUrlEvent?: (msg: WebSocketMessage) => void;
+  onUploadJpgImageByIndexEvent?: (msg: WebSocketMessage) => void;
+  onUploadEvent?: (msg: WebSocketMessage) => void;
+  onImageEditedEvent?: (msg: WebSocketMessage) => void;
+  onImageMovedEvent?: (msg: WebSocketMessage) => void;
+  onImageDrapEvent?: (msg: WebSocketMessage) => void;
+  onImageDeletedEvent?: (msg: WebSocketMessage) => void;
+  onImagesClearedEvent?: (msg: WebSocketMessage) => void;
+
+  constructor();
+
+  getConnectedServer(wssUrls: string[]): Promise<WebSocket>;
+  tryConnect(): void;
+  initWebsocketCallback(server: WebSocket): void;
+  onSocketError(event: Event): void;
+  isCallbackExist(f: any): f is Function;
+  dispatchCallback(name: string, msg: WebSocketMessage): void;
+  toBoolCompat(value: any): boolean;
+  toIntCompat(value: any, fallback: number): number;
+  normalizeScanSource(
+    scanSource?: string | null,
+    legacyAutoFeedEnable?: any
+  ): ScanSource;
+  getLegacyAutoFeedEnable(scanSource?: string | null): boolean;
+  shouldIncludeLegacyAutoFeedEnable(): boolean;
+  normalizeScanConfig(
+    config?: Partial<ScanConfig> & { autoFeedEnable?: boolean },
+    options?: { includeLegacyAutoFeedEnable?: boolean }
+  ): ScanConfig & { autoFeedEnable?: boolean };
+  recordServerProtocolVersion(msg: WebSocketMessage): number;
+  applyIncomingScanConfig(msg: WebSocketMessage): void;
+  normalizeIncomingMessage(rawMsg: WebSocketMessage): WebSocketMessage;
+  onSocketMessage(event: MessageEvent): void;
+  normalizeOutgoingCommand(commandData: Record<string, any>): Record<string, any>;
+  sendWebSocketCommand(commandData: object): void;
+  setLicenseKey(
+    licenseMode: string,
+    key1: string,
+    key2: string,
+    licenseServerUrl: string
+  ): void;
+  loadDevices(): void;
+  selectScanDevice(deviceIndex: number): void;
+  startScan(): void;
+  clearAll(): void;
+  getImageCount(): void;
+  getAllImage(): void;
+  getImageById(indexOrImageId: number | string): void;
+  loadImageFromUrl(url: string, type?: string): void;
+  loadImageFromBase64(base64Data: string, format?: string): void;
+  rotateImage(index: number, angle: number): void;
+  getImageSize(index: number): void;
+  deleteImageByIndex(index: number, imageId?: string): void;
+  moveImage(oldIndex: number, newIndex: number): void;
+  uploadAllImageAsPdfToUrl(url: string, id: string, desc: string): void;
+  uploadAllImageAsTiffToUrl(url: string, id: string, desc: string): void;
+  uploadJpgImageByIndex(
+    url: string,
+    id: string,
+    desc: string,
+    index: number
+  ): void;
+  saveAllImageToLocal(filename: string): void;
+  openClientLocalfile(): void;
+  ftpUploadAllImage(
+    serverIp: string,
+    port: number,
+    username: string,
+    password: string,
+    serverPath: string,
+    filename: string
+  ): void;
+  setUploadButtonVisible(visible: boolean): void;
+  setFocus(): void;
+  hidden(): void;
+  closeWebSocket(): void;
+  loadMultipleImagesFromBase64(base64Images: Base64ImagePayload[]): void;
+  loadImageFromCanvas(
+    canvas: HTMLCanvasElement,
+    format?: string,
+    quality?: number
+  ): void;
+  loadImageFromFileInput(fileInput: HTMLInputElement): void;
+}