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