NexScanner Web SDK 开发套件下载 —— 浏览器扫描插件二次开发 SDK（JavaScript / TypeScript）

NexScanner Web SDK v1.0.0

适用插件版本：NexScanner 扫描插件（WebSocket 服务 ws://127.0.0.1:11345/）
适配系统：Windows 7+ / 统信 UOS / 银河麒麟 / macOS / Linux

v1.0.0当前版本
16.7 KB安装包大小
2026-10-05更新时间

提示：服务器上暂未找到 SDK 安装包，下载按钮已置灰。请把安装包上传到以下任一位置后刷新本页：
app/static/sdk/sdk.rar（随代码发布，推荐）或 app/upload_files/plugins/sdk.rar

开发SDK

什么是 NexScanner Web SDK

NexScanner 扫描插件通过本地 WebSocket 服务（默认 ws://127.0.0.1:11345/）为网页提供高拍仪、高速扫描仪的调用能力。Web SDK 在协议之上做了一层封装，把「连接设备 → 设置参数 → 扫描 → 收图 → 编辑 → 上传」的完整流程变成 Promise 风格的 JavaScript API，业务系统不需要自己拼协议、切分二进制图片帧或匹配命令响应。

开发包内容

文件	说明
`examples/sdk/nexscanner-sdk.js`	浏览器端 SDK，UMD 风格，`<script>` 直接引入，也可用模块方式加载
`examples/sdk/nexscanner-sdk.d.ts`	TypeScript 类型声明，Vue / React / Angular 工程可获得完整类型提示
`examples/sdk/nexscanner-sdk-demo.html`	本地 Demo（离线可用）；在线体验请用页面顶部的「在线 Demo」，与本站在线演示页 `/scanner_client.htm` 是同一套能力
`docs/NexScanner-Web-SDK使用说明.html`	开发说明文档（与本页「开发文档」一致）

核心能力

协议全封装

连接管理、请求响应匹配、超时与重连、二进制分块图片拼装全部由 SDK 处理。

扫描控制

设备枚举与切换，分辨率/色彩/单双面/进纸方式/纸张尺寸与方向/驱动类型等参数设置，支持连续扫描。

图像编辑

旋转、裁剪、矩形标注，坐标使用 0~1 相对比例，适配不同分辨率预览区。

本地图片

无需连接插件即可选择本地图片并在浏览器内完成旋转、裁剪与标注。

类型友好

内置 .d.ts 声明与事件列表，编辑器内自动补全。

零依赖

纯原生 JavaScript，不依赖 jQuery / 框架，与 Vue、React、Angular 等均可集成。

运行环境

浏览器需支持原生 WebSocket：Chrome、Edge、Firefox 及 Chromium 内核的国产浏览器。
需先安装并启动 NexScanner 扫描插件，且插件已开启 WebSocket 服务（默认端口 11345）。
支持 Windows 7+、统信 UOS、银河麒麟、macOS、Linux；扫描仪驱动支持 WIA / TWAIN / SANE。
无需构建工具，静态页面直接引入即可运行。

第 1 步：下载并解压开发包

点击页面顶部「立即下载 SDK」获取 sdk.rar，解压后得到 examples/sdk/ 与 docs/ 目录。

想先看效果？可直接打开在线 Demo （需本机已安装并启动 NexScanner 扫描插件）。

第 2 步：启动扫描插件

安装并启动 NexScanner 扫描插件，确认插件设置中已启用 WebSocket 服务，默认地址：

地址ws://127.0.0.1:11345/

第 3 步：页面引入 SDK

html<script src="./nexscanner-sdk.js"></script>

第 4 步：最小可用示例

连接插件 → 枚举设备 → 连接扫描仪 → 设置参数 → 开始扫描，扫描结果通过 image 事件推送。

javascript

<img id="preview">
<script>
const scanner = new NexScannerClient({ url: 'ws://127.0.0.1:11345/' });

scanner.on('image', image => {
  document.querySelector('#preview').src = image.url;
  console.log('收到扫描图片', image.seq, image.blob);
});

async function startScan() {
  await scanner.connect();
  const devices = await scanner.listScanners();
  await scanner.connectScanner(devices[0]);
  await scanner.setParams({
    resolution: 300,
    colormode: 2,   // 0 黑白，1 灰度，2 彩色
    duplex: 0,      // 0 单面，1 双面
    source: 1,      // 0 自动，1 平板，2 ADF
    pageSize: 0,    // 纸张尺寸：0 A4(默认)，1 A3，2 A5，3 A6，4 Letter，5 Legal，6 B5，7 自动
    orientation: 0, // 纸张方向：0 纵向(默认)，1 横向(平板横放)，2 自动
    format: 'jpg',
    backend: 'WIA', // WIA / TWAIN / SCAN
    brightness: 0,
    contrast: 0
  });
  await scanner.scan();
}
</script>

关于幅面：插件默认按 A4 下发扫描区域。用 A3 幅面机器、或平板要横放纸张时，请显式指定 pageSize 与 orientation，否则会出现"Linux/国产系统扫出来是 A3、Windows 是 A4"或"横放被裁掉"的问题，详见「API 参考」里的纸张尺寸与方向。

第 5 步：图像编辑

编辑接口需要传入插件返回的图片序号 seq，坐标与宽高均为 0~1 的相对比例，编辑结果通过 edit 事件返回。

javascript

// 旋转
await scanner.rotateLeft(seq);
await scanner.rotate180(seq);

// 从 10%,10% 的位置开始，裁剪 80% 宽、80% 高
await scanner.crop(seq, 0.1, 0.1, 0.8, 0.8);

// 红色矩形标注，线宽 3px
await scanner.annotateRect(seq, 0.1, 0.1, 0.5, 0.3, '#ff0000', 3);

scanner.on('edit', image => {
  document.querySelector('#preview').src = image.url;
});

// 本地图片（无需连接插件）
const images = await scanner.pickLocalImages({ multiple: true, accept: 'image/*' });
const marked = await scanner.annotateLocalImage(images[0], 0.1, 0.1, 0.5, 0.3, '#0066ff', 3);

第 6 步：保存与上传

javascript

scanner.on('image', image => {
  // image.url 是浏览器临时地址，上传请使用 blob / bytes
  const fd = new FormData();
  fd.append('file', image.blob, 'scan-' + image.seq + '.' + image.format);
  fetch('/api/upload', { method: 'POST', body: fd });
});

提示：扫描图片由插件主动推送，是 image 事件的返回值，而不是 scan() 的返回值。

创建客户端

javascript

const scanner = new NexScannerClient({
  url: 'ws://127.0.0.1:11345/',
  timeout: 15000,        // 命令超时时间（毫秒）
  autoReconnect: false,  // 是否自动重连
  reconnectDelay: 3000   // 重连间隔（毫秒）
});

方法一览

方法	说明
`connect(url?)`	连接插件 WebSocket 服务，返回 Promise
`disconnect()`	断开 WebSocket 连接
`isConnected()`	当前连接状态
`on(event, handler)`	监听事件，返回取消监听的函数
`off(event, handler)`	移除事件监听
`command(cmd, params?)`	发送自定义命令，插件新增命令时无需改动 SDK
`request(cmd, params?, options?)`	底层请求方法，可自定义 id 与超时
`listScanners()`	枚举可用扫描仪，返回设备名数组
`connectScanner(name)`	连接指定扫描仪
`disconnectScanner()`	断开扫描仪
`getStatus()`	获取插件与扫描仪状态
`getParams()`	获取当前扫描参数（含 `pageSizeName`、`orientationName` 可读名称）
`setParams(params)`	设置扫描参数（分辨率、色彩、单双面、进纸方式、纸张尺寸与方向、驱动等）
`setPaperSize(size)`	单独设置纸张尺寸，接受索引、枚举名或 `PaperSize` 常量
`setPaperOrientation(orientation)`	单独设置纸张方向，接受索引、枚举名或 `PaperOrientation` 常量
`scan()`	开始扫描，图片通过 `image` 事件推送
`stopScan()`	停止扫描
`rotateLeft(seq)` / `rotateRight(seq)` / `rotate180(seq)`	旋转图片
`rotate(seq, angle)`	按指定角度旋转
`crop(seq, x, y, width, height)`	裁剪，坐标为 0~1 相对比例
`annotateRect(seq, x, y, w, h, color?, thickness?)`	矩形标注，可指定颜色与线宽
`editImage(params)`	底层图片编辑接口
`pickLocalImages(options?)`	选择本地图片，无需连接插件
`imageFromFile(file)`	将 File 对象转换为 SDK 图片对象
`rotateLocalImage(img, angle)`	本地图片旋转
`cropLocalImage(img, x, y, w, h)`	本地图片裁剪
`annotateLocalImage(img, x, y, w, h, color?, thickness?)`	本地图片矩形标注

事件列表

事件	说明
`open`	WebSocket 已连接
`close`	WebSocket 已断开
`error`	WebSocket 错误
`send`	已发送命令
`command`	收到命令响应
`image`	收到扫描图片
`edit`	收到编辑后的图片
`image-meta`	收到图片元数据
`edit-meta`	收到编辑元数据
`text`	收到非 JSON 文本

扫描参数说明

参数	取值	说明
`resolution`	200 / 300 / 600 等	扫描分辨率 DPI
`colormode`	0 / 1 / 2	0 黑白，1 灰度，2 彩色
`duplex`	0 / 1	0 单面，1 双面
`source`	0 / 1 / 2	0 自动，1 平板，2 ADF（自动进纸器）
`pageSize`	0 A4(默认) / 1 A3 / 2 A5 / 3 A6 / 4 Letter / 5 Legal / 6 B5 / 7 自动	纸张尺寸，三端（WIA / TWAIN / SANE）统一按此下发幅面，也支持传枚举名如 `'A3'`
`orientation`	0 纵向(默认) / 1 横向 / 2 自动	纸张方向，平板横放必须显式指定，否则会被裁掉；`2` 为横竖并集
`format`	jpg / png / tiff	输出图片格式
`backend`	WIA / TWAIN / SCAN	扫描仪驱动类型
`brightness` / `contrast`	整数	亮度与对比度，部分扫描仪不支持

纸张尺寸（pageSize）

插件在 Windows(WIA/TWAIN) 与 Linux/国产系统(SANE) 三端统一按 pageSize 下发幅面，默认 A4。原因是部分 A3 幅面扫描仪在 Linux/国产系统下 SANE 后端默认幅面是 A3，而 Windows 驱动默认是 A4，不显式指定时两端结果会不一致；选 7（自动）则沿用设备/驱动默认幅面。

javascript

// 方式一：合并到 setParams
await scanner.setParams({ pageSize: 0 });     // A4
await scanner.setParams({ pageSize: 'A3' });  // 也支持枚举名（SDK 自动转换）

// 方式二：单独调用
await scanner.setPaperSize('A3');
await scanner.setPaperSize(NexScannerClient.PaperSize.A4);

// 常量表（window.NexScannerPaperSize 同名可用）
NexScannerClient.PaperSize.A4;    // 0
NexScannerClient.PaperSize.A3;    // 1
NexScannerClient.PaperSize.Auto;  // 7

传了无法识别的值时 setParams / setPaperSize 会 reject（Invalid pageSize: xxx），不会再把这个参数发给插件。

纸张方向（orientation）

平板扫描时纸张可以竖放也可以横放：A4 竖放是 210×297，横放是 297×210。只下发 pageSize 时扫描区域仍按 210×297 下发，横放的纸张会被裁掉，所以横放必须同时指定方向。

javascript

// 平板横放纸张
await scanner.setParams({ source: 1, pageSize: 0, orientation: 1 });

// 或者单独设置
await scanner.setPaperOrientation('landscape');
await scanner.setPaperOrientation(NexScannerClient.PaperOrientation.Landscape);

// 横竖都可能出现、不想每次切换 → 自动（平板按横竖并集 297×297 下发，ADF 仍按纵向）
await scanner.setPaperOrientation('auto');

NexScannerClient.PaperOrientation.Portrait;   // 0 纵向（默认）
NexScannerClient.PaperOrientation.Landscape;  // 1 横向
NexScannerClient.PaperOrientation.Auto;       // 2 自动

三端实现：WIA 改 Page Width/Height、TWAIN 用 ICAP_UNITS+ICAP_FRAMES 下发扫描区域、SANE 改 --page-width/--page-height。若某台设备 / TWAIN 驱动不支持 ICAP_FRAMES，插件会在扫描日志里给出告警，此时平板横向扫描请改用 WIA 后端。
提示：setPaperSize / setPaperOrientation 与两个常量表由新版 SDK 提供；若浏览器提示 is not a function，说明手上的 SDK 包还是旧版，请重新下载最新开发包。

提示：服务器上暂未找到开发说明文档，请把 NexScanner-Web-SDK使用说明.html 放到项目根目录或 app/static/sdk/ 目录后刷新本页；也可直接下载 SDK 开发包，文档已包含在包的 docs/ 目录中。

1. 连接失败，提示 WebSocket closed / timeout？

确认 NexScanner 扫描插件已启动，并且插件设置中已开启 WebSocket 服务。
确认端口为默认的 11345，如被占用请在插件中修改端口，并同步修改 SDK 的 url。
插件与网页需在同一台机器上，SDK 默认连接 127.0.0.1。

2. 扫描没有返回图片？

图片是通过 image 事件异步推送的，请先注册监听再调用 scan()。
ADF（自动进纸器）模式请把 source 设为 2，并确认纸张已放好。
部分扫描仪不支持亮度、对比度设置，如报错可去掉这两个参数。

3. 扫描结果如何上传到服务器？

image.url 是浏览器临时地址（blob URL），仅用于预览；上传或保存请使用 image.blob 或 image.bytes（ArrayBuffer）。

4. 支持哪些浏览器和操作系统？

支持基于 Chromium 内核、Firefox 内核的国产浏览器，以及 Firefox、Chrome、Edge；操作系统支持 Windows 7+、统信 UOS、银河麒麟、macOS、Linux，CPU 覆盖飞腾、鲲鹏、龙芯、海思等。

5. 插件升级后 SDK 需要更新吗？

SDK 只封装稳定协议，一般小版本升级无需改动业务代码；如插件新增命令，可直接通过 scanner.command('新命令') 调用，无需等待 SDK 更新。

6. 想获得技术支持或定制开发？

可致电 400-660-5996 或通过页面右下角「在线咨询」联系我们，提供 Demo 级示例代码与集成指导。