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当前版本
9.5 KB安装包大小
2026-09-16更新时间
1累计下载

提示：服务器上暂未找到 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，覆盖扫描、编辑、裁剪、标注、本地图片等能力
`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
    format: 'jpg',
    backend: 'WIA', // WIA / TWAIN / SCAN
    brightness: 0,
    contrast: 0
  });
  await scanner.scan();
}
</script>

第 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()`	获取当前扫描参数
`setParams(params)`	设置扫描参数（分辨率、色彩、单双面、进纸方式、驱动等）
`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（自动进纸器）
`format`	jpg / png / tiff	输出图片格式
`backend`	WIA / TWAIN / SCAN	扫描仪驱动类型
`brightness` / `contrast`	整数	亮度与对比度，部分扫描仪不支持

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

数据来源：插件下载日志（download_log），按插件名「NexScanner-Web-SDK」统计。

1累计下载次数

1今日下载

1近 7 天下载

1下载独立 IP

版本分布

NexScanner-Web-SDK v1.0.0 1 次

近 14 天下载趋势

09-0309-0409-0509-0609-0709-0809-0909-1009-1109-1209-1309-1409-1509-16

下载时间	插件名称	来源 IP	终端
2026-09-16 18:58	NexScanner-Web-SDK v1.0.0	182.200.192.*	Windows

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 级示例代码与集成指导。