插件打印
通过本机打印服务（magic-print）把报表 PDF 直接送到指定打印机的工作方式：触发条件、报表设置、连接地址、降级规则与可用的调用接口。
概述
浏览器打印每次都会弹出系统打印对话框。插件打印让浏览器通过本机运行的打印服务，把服务端生成的 PDF 直接发送到指定打印机，适合票据、单据连续出单的场景。
插件打印依赖用户电脑上运行的本机打印服务（magic-print）。该服务不属于 Sight Report 服务端，需要安装在打印所在的那台电脑上。
前置条件
| 条件 | 说明 |
|---|---|
| 本机打印服务 | 在打印电脑上运行 magic-print，默认监听 ws://127.0.0.1:10086（端口见下文「打印插件端口号」）。浏览器通过 WebSocket 连接它，因此服务必须与浏览器在同一台电脑上。安装包与安装方式以该服务的提供方为准，本产品不随包分发。 |
| 打印机 | 在操作系统中已正确安装，并能被本机打印服务枚举到。 |
| 报表设置 | 「打印机名称」已填写，「打印预览」已关闭。 |
功能入口
- 设计器顶栏「报表设置」（单据模板为「页面设置」）>「页面设置」页签 >「打印配置」。
- 查看页工具栏「打印」>「插件打印 (全部页)」或「插件打印 (当前页)」。「当前页」只在分页查看方式下出现。
操作步骤
- 在「打印配置」中填写「打印机名称」，可填打印机的系统名称或显示名称，匹配时不区分大小写。
- 按需设置「打印份数」（1 到 100，默认 1）。
- 把「打印预览」开关切到关闭。
- 保存报表。
- 在打印电脑上启动本机打印服务。
- 打开报表查看页，点击「打印」>「插件打印 (全部页)」。系统依次连接打印服务、检查打印机状态、生成 PDF、发送到打印机，成功后提示「已发送到打印机：打印机名称」。
属性/参数说明
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
| 打印机名称 | 目标打印机，填系统名称或显示名称 | 文本；留空表示未配置打印机 |
| 打印份数 | 插件打印时发给打印服务的份数 | 1 到 100；默认 1 |
| 打印预览 | 开启时弹出系统打印对话框；关闭时走插件打印 | 开启（默认）/ 关闭 |
触发规则与降级
点击「插件打印」后，按下表依次判断：
| 情况 | 结果 |
|---|---|
| 「打印预览」开启（默认），或未填「打印机名称」 | 不使用插件，直接弹出系统打印对话框 |
| 连接不上本机打印服务（4 秒超时、服务未启动或鉴权被拒） | 弹出确认框「本地打印服务不可用」，点「使用浏览器打印」后降级为系统打印对话框，点「取消」则不打印 |
| 配置的打印机在打印服务中不存在，或状态为脱机 | 提示「打印机「xxx」不存在」或「已脱机」，自动转为系统打印对话框 |
| 打印服务返回发送失败 | 提示「插件打印失败」，自动转为系统打印对话框 |
| 其余情况 | 静默发送到配置的打印机，任务标题为「报表」，「当前页」打印时为「报表-第N页」 |
注意：默认「打印预览」是开启的，此时点击「插件打印」与点击「打印预览」效果相同。要实现静默出单，必须同时关闭「打印预览」并填写「打印机名称」。
打印服务提供的能力
前端封装的调用如下，供二次开发或排查参考。
| 方法 | 作用 |
|---|---|
getServerInfo |
读取服务名称、版本、支持的格式（text、html、pdf、image）和打印选项 |
listPrinters / getDefaultPrinter / getPrinter |
枚举打印机、取默认打印机、取指定打印机状态 |
print（含 printPdf 等） |
提交打印，参数含 data、printer、copies、paperSize、duplex、orientation、tray、mediaType、title |
getJob / cancelJob / listJobs |
查询、取消、列出打印任务 |
selfTest |
服务自检，返回 ok |
报表打印只使用 printPdf，data 为 PDF 的 base64（不含 data: 前缀）。
注意：连接地址为
ws://127.0.0.1:<端口>，端口取管理端「系统设置」>「报表」中的「打印插件端口号」，未配置时为 10086。现场端口冲突时，先改 magic-print 的监听端口，再把这里改成同一个值；修改后重新打开报表即生效。嵌入第三方系统时同样生效。
与静默导出接口的关系
导出 PDF 接口（GET /report/export/pdf）支持 silent=true 参数，此时响应不是文件流，而是 JSON {"base64": "..."}，同时在响应头返回纸张信息（paper）、文件名（name，Base64 编码）和报表 id（id）。宿主系统可以用它自行把 PDF 交给自己的打印通道。
注意事项
提示：报表打印发送给打印服务的参数只有 PDF 数据、任务标题、份数和打印机名，纸张由 PDF 页面尺寸决定。对位要求高的套打，请保证打印机纸张与报表页面设置一致，并在驱动里避免缩放。见 套打与定位。
提示：数据浏览报表不提供打印功能。
