WebPrint JS SDK 0.6.0 · HTTPS 网页自动连接本机打印
一、客户首次设置
1. 安装对应系统的 0.5.3 桌面软件(或后续兼容版本),并保持运行。苹果芯片 Mac 使用 arm64 版。
2. 选择系统打印机或已添加的网口设备,点击“保存打印机”。
3. 打开“服务配置与调试”,开启“允许已授权的业务网页自动连接本机打印服务”。旧版本升级后需要首次手动开启。
4. 在“允许调用的其他业务网页来源”中加入实际业务网址,例如 https://erp.example.com。只填来源,不带路径或末尾斜杠,端口非默认时需包含端口。
5. 保存设置。回到 HTTPS 业务网页,点击打印;浏览器首次请求本地网络访问权限时,请允许。
之后不需要客户复制端口或访问令牌。软件修改主服务端口后,重新自动连接即可获取最新地址。
此功能寻找的是当前电脑的软件,不扫描局域网其他电脑。实际打印机仍通过系统驱动或软件中保存的网口配置连接。
二、网站部署
将 webprint-js-sdk-0.6.0.zip 完整解压到 HTTPS 业务网站,如 /webprint/。保留 sdk.js、vendor/、render.js、chart.js、format.js 等相对目录关系。
不要只复制 sdk.js;SDK 的排版、条码等依赖也必须由业务 HTTPS 网站提供。
auto-connect-test.html 为可直接部署的测试页。访问 https://你的业务域名/webprint/auto-connect-test.html 后,按页面提示授权来源。
业务网站需要正常受信任的 HTTPS 证书。本机回环接口使用 HTTP,不安装本地证书,不要求客户跳过证书错误。
三、JS 调用示例
WebPrint.autoConnect() 返回已准备好的 WebPrint.Printer 实例,也可通过 WebPrint.getPrinter() 取得当前实例。
WebPrint JS SDK 0.6.0 使用 init、addText、print 等命名;print() 返回 Promise,成功值为本服务任务 UUID。
旧版大写方法与兼容入口仍保留,具体迁移说明见 WebPrint-JS-SDK接入说明.txt。
它自动匹配软件中已保存的本机打印机。尚未保存、设备已移除或编号不匹配时返回错误,不自动改投其他设备。
业务系统也可明确指定唯一设备:await WebPrint.autoConnect({ printerName: '系统中完整的打印机名称' }),或使用 printerId;名称匹配多个设备时会拒绝。
纸张、份数、样张仍由业务 JS 设置。任务“已提交”不代表人工确认物理出纸。
四、浏览器与 CSP
以现代 Chrome/Edge 的 HTTPS 网页为首版支持目标;浏览器的本地网络权限必须允许,不能由 JS 绕过。
SDK 使用 http://127.0.0.1 回环地址,并在 fetch 中标记 targetAddressSpace: 'loopback'。
如网站设置 CSP,至少要允许 connect-src 'self' http://127.0.0.1:*;SDK 静态文件可由 script-src 'self' 加载。使用弹出/内嵌预览时也需允许对应本机窗口或 frame-src。
不可将所有 https://业务网页 → 任意 HTTP 局域网地址理解为均可访问;本版自动发现只访问本机回环地址。
Safari、Firefox、企业定制浏览器及 WebView 的实际权限/策略兼容需要另行测试;本版不宣称所有浏览器均可无设置使用。
五、权限和故障
软件仅在 127.0.0.1 的 18118/18119/18120 中选择可用发现端口;主打印/管理服务仍使用原来的随机或指定端口。
发现端口全部占用时会在软件显示原因;手工接入配置仍可使用。不要对用户网络进行端口扫描。
SDK 不向网页提供本机管理令牌;授权网址获得约 15 分钟有效、绑定来源的临时打印凭据,只可打印、预览并查询自己创建的任务。
不同业务来源的请求编号和任务查询隔离;重复请求编号及相同内容不会产生重复任务。修改来源或关闭自动连接可撤销已有临时凭据。
自动连接不授权读写本地文件、串口、原始指令、修改软件配置或读取保存的远端连接凭据。这些扩展仍需原有的显式管理接入。
临时凭据仅保存在页面内存,不写入 URL、localStorage、sessionStorage 或测试报告。页面加载和自动连接本身不会打印。
常见错误:
AUTO_CONNECT_DISABLED:在软件配置页打开网页自动连接。
ORIGIN_NOT_AUTHORIZED:在软件中添加当前业务网页来源。
PRINTER_NOT_SAVED:先在打印软件中选择并保存打印机。
SAVED_PRINTER_UNAVAILABLE:已保存设备不可用,请检查系统驱动/网口配置后重新保存。
LOCAL_SERVICE_NOT_FOUND:软件未运行、发现端口被占用、浏览器拒绝本地网络权限或 CSP 拦截。
SERVICE_RESTARTING:正在应用服务设置,等待后重新连接。
浏览器规则参考:
https://learn.microsoft.com/en-us/deployedge/ms-edge-local-network-access
https://developer.chrome.com/blog/local-network-access