DM-ROW 接口文档

Appearance

打印管理功能 ​

**本文档引用的文件** - [print.js](file://dm/lemes-web/src/utils/print.js) - [local-print.js](file://dm/lemes-web/src/utils/local-print.js) - [LodopFuncs.js](file://dm/lemes-web/src/utils/LodopFuncs.js) - [htmlToPdf.js](file://dm/lemes-web/src/utils/htmlToPdf.js) - [local-service.js](file://dm/lemes-web/src/utils/local-service.js) - [localService.js](file://dm/lemes-web/src/utils/localService.js) - [localServiceForPrint.js](file://dm/lemes-web/src/utils/localServiceForPrint.js) - [printer.js](file://dm/lemes-web/src/views/devicemate/api/system/printer.js) - [printer-config.js](file://dm/lemes-web/src/views/devicemate/config/api/system/printer.js)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件系统性梳理 DeviceMate 项目的打印管理功能，覆盖以下方面：

  • 打印架构与实现模式：Lodop 打印控件集成、本地打印服务方案、HTML 转 PDF 的实现原理与页面布局优化。
  • 打印配置管理：打印机信息的增删改查、分页查询、按用户筛选等接口。
  • 打印模板设计与批量打印：基于本地服务的 BarTender 模板、ZPL 模板、激光打印机模板的打印流程；HTML 标签页打印与批量处理。
  • 使用示例、常见问题与性能优化建议：包括打印预览、打印设置、打印状态监控的实现要点。

项目结构 ​

围绕打印功能的关键目录与文件组织如下：

  • 工具层（utils）
    • print.js：通用 HTML 打印封装（iframe 内嵌打印）。
    • htmlToPdf.js：HTML 转 PDF 的 Vue 插件封装。
    • local-print.js：本地服务打印入口（打印机列表、模板打印）。
    • local-service.js：本地服务健康检查、版本检测与下载安装流程。
    • localService.js：本地服务通用工具（文件读写、命令执行、版本升级）。
    • localServiceForPrint.js：打印全流程编排（Bartender/ZPL/Lodop/HTML 打印）、变量解析、批量打印。
    • LodopFuncs.js：Lodop 控件加载、跨平台兼容与安装引导。
  • 配置与 API 层（views/devicemate）
    • printer.js：打印机信息的 API 调用封装。
    • printer-config.js：打印机相关 API 基础路径配置。

图表来源

章节来源

核心组件 ​

  • 通用 HTML 打印（print.js）
    • 功能：收集样式与表单元素状态，注入隐藏 iframe，触发打印，支持 beforeprint/afterprint 回调。
    • 关键点：通过选择器收集样式与链接资源，序列化表单控件状态，避免打印时丢失数据。
  • HTML 转 PDF（htmlToPdf.js）
    • 功能：基于 html2canvas 与 jspdf，将指定 DOM 区域渲染为 PDF，支持多页拼接与 A4 尺寸适配。
    • 关键点：计算缩放比例、分页策略、保存文件名。
  • 本地打印服务（local-print.js + local-service.js + localService.js + localServiceForPrint.js）
    • 功能：本地服务健康检查与版本升级、下载安装包；模板打印（ZPL/激光）、BarTender 模板打印、HTML 标签页打印、Lodop 打印与预览。
    • 关键点：统一的本地服务通信协议、错误提示与国际化消息、批量打印与变量解析。
  • Lodop 打印控件（LodopFuncs.js）
    • 功能：跨平台判断、动态加载 CLodop 或 IE 插件、安装引导弹窗、版本检测与升级提示。
    • 关键点：针对不同浏览器与系统环境的兼容性处理。
  • 打印机配置 API（printer.js + printer-config.js）
    • 功能：分页查询、保存、更新、删除、批量删除、按用户获取打印机列表等。
    • 关键点：统一的 API 路径配置与请求封装。

章节来源

架构总览 ​

整体打印架构分为三层：

  • 前端工具层：负责打印能力封装与跨平台兼容（print.js、htmlToPdf.js、LodopFuncs.js、local-print.js、local-service.js、localService.js、localServiceForPrint.js）。
  • 本地服务层：提供文件读写、命令执行、模板变量解析、打印任务调度等能力。
  • 后端 API 层：提供打印机配置管理接口，供前端进行增删改查与分页查询。

图表来源

详细组件分析 ​

组件一：通用 HTML 打印（print.js） ​

  • 设计要点
    • 支持传入 DOM 选择器或 Vue 实例，自动定位根节点。
    • 收集样式与链接资源，确保打印样式完整。
    • 序列化表单控件（复选框、单选框、文本框、下拉框），避免打印时丢失数据。
    • 通过隐藏 iframe 注入内容，触发打印，支持打印前后回调。
  • 处理逻辑
    • 初始化：合并样式与 HTML。
    • 写入 iframe：打开、写入、关闭。
    • 触发打印：优先使用 document.execCommand('print')，失败回退至 window.print()。
    • 清理：延时移除 iframe 并回调 afterprint。

图表来源

章节来源

组件二：HTML 转 PDF（htmlToPdf.js） ​

  • 设计要点
    • 基于 html2canvas 将 DOM 转为 Canvas，再由 jspdf 输出 PDF。
    • 计算 A4 尺寸下的缩放比例，支持整页填充与纵向/横向布局。
    • 对超长内容进行分页追加，最终保存 PDF 文件。
  • 处理逻辑
    • 获取目标 DOM 宽高与页面高度。
    • 计算图片宽度与高度，生成 base64 数据。
    • 循环添加页面并保存 PDF。

图表来源

章节来源

组件三：本地打印服务（local-print.js + local-service.js + localService.js + localServiceForPrint.js） ​

  • 设计要点
    • 本地服务健康检查与版本升级：通过本地 9001 端口探测服务状态，必要时引导下载安装包。
    • 模板打印：支持 ZPL 与激光打印机模板，按类型路由到对应接口。
    • 打印编排：统一入口 startPrint，根据 configType 选择 BarTender、ZPL、Lodop 或 HTML 打印。
    • BarTender 模板：检查模板文件是否存在，不存在则写入；支持变量解析与 mock 文件关联。
    • HTML 标签页打印：将 HTML 列表转换为图片或 PDF，再通过本地服务打印。
    • Lodop 打印：封装 PRINT/PRINTA/PREVIEW 三种模式，支持指定打印机索引。
  • 关键流程（模板打印）

图表来源

图表来源

章节来源

组件四：Lodop 打印控件（LodopFuncs.js） ​

  • 设计要点
    • 跨平台判断：移动端、Edge、Firefox、Opera、Chrome 等环境下优先使用 CLodop。
    • 动态加载：从本地 8000/18000 端口加载 CLodop，避免端口占用。
    • 安装引导：根据浏览器类型弹出安装/升级提示，支持下载链接与协议链接。
    • 版本检测：对 LODOP 版本进行检测，必要时提示升级。
  • 关键流程

图表来源

章节来源

组件五：打印配置管理（printer.js + printer-config.js） ​

  • 设计要点
    • 统一的 API 路径配置文件，便于集中维护。
    • 提供分页查询、保存、更新、删除、批量删除、按用户获取列表等接口封装。
  • 关键接口
    • 分页查询：pageAjax(params)
    • 保存：saveAjax(params)
    • 更新：updateAjax(params)
    • 删除：deleteAjax(id)
    • 批量删除：batchesDeleteAjax(params)
    • 获取详情：getPrinterAjax(id)
    • 获取当前用户列表：getPrinterListByActiveUserAjax(params)

图表来源

章节来源

依赖关系分析 ​

  • 组件耦合
    • local-print.js 依赖 local-service.js 进行本地服务检测与下载。
    • localServiceForPrint.js 统一编排打印流程，依赖 LodopFuncs.js（Lodop）、localService.js（文件系统与命令执行）、html2canvas/jspdf（HTML 转 PDF/图片）。
    • print.js 与 htmlToPdf.js 作为通用能力被上层打印流程复用。
  • 外部依赖
    • 浏览器打印栈（execCommand/print）、Lodop 控件、本地服务进程（9001 端口）。
  • 潜在风险
    • 本地服务不可用时的降级策略（引导安装/切换打印方式）。
    • 不同浏览器对 html2canvas/jspdf 的兼容性差异。

图表来源

章节来源

性能考虑 ​

  • HTML 转 PDF
    • 控制截图区域尺寸与 html2canvas 的宽高参数，减少内存占用与渲染时间。
    • 对超长内容采用分页策略，避免一次性生成大体积 PDF。
  • 本地打印
    • BarTender 模板写入与变量解析仅在首次缺失时执行，后续复用以降低开销。
    • 批量打印时尽量合并请求，减少本地服务往返次数。
  • Lodop 打印
    • 预览与直接打印分离，避免不必要的打印动作。
    • 在移动端或不支持插件的环境中优先使用 CLodop，减少失败重试成本。

故障排查指南 ​

  • 本地服务未启动/版本不匹配
    • 现象：调用本地服务接口报网络错误或版本不一致。
    • 排查：检查本地服务进程状态、端口占用情况；根据提示下载安装最新版本。
    • 参考
  • BarTender 模板缺失或变量解析失败
  • HTML 打印样式异常
    • 现象：打印样式丢失或布局错乱。
    • 排查：确认传入的样式选择器与链接资源；检查表单控件序列化逻辑。
    • 参考
  • Lodop 控件加载失败
    • 现象：无法获取 LODOP 实例或版本过低。
    • 排查：检查浏览器类型与端口占用；根据提示安装/升级 Lodop。
    • 参考

章节来源

结论 ​

DeviceMate 的打印管理功能通过“前端工具层 + 本地服务 + 后端 API”的分层设计，实现了对多种打印场景的支持：

  • 通用 HTML 打印与 HTML 转 PDF 保证了页面样式的可控输出；
  • 本地服务提供了 BarTender、ZPL、激光打印与 HTML 标签页打印的统一编排；
  • Lodop 控件在跨平台场景下提供稳定的打印体验；
  • 打印机配置 API 保障了打印设备管理的灵活性。

建议在生产环境中结合业务场景选择合适的打印路径，并完善本地服务与浏览器兼容性的监控与告警。

附录 ​