打印 · PrintLink

静默出纸、等待打印结果、取消任务、查询任务列表，以及如何避免同一张单打两遍。

打印是静默的：调用后不弹任何窗口，任务直接进入系统打印队列。

最简单的打印

await client.compose({ queueId })
  .addPdf(pdfBytes)
  .printAndWait();

compose() 是链式写法，.printAndWait() 会等到任务结束。想立刻返回、不等结果：

const job = await client.compose({ queueId }).addPdf(pdfBytes).print();
console.log(job.jobId);   // 任务已提交，用这个 id 查询

一次任务，不要循环

多页、多文件请永远用一次 compose() 或一份 items，不要按文件循环调用 print()——那会变成 N 条打印队列任务，用户会看到 N 条记录，出纸顺序也不再可控。见组合打印。

等待打印结果

printAndWait() 返回终态：

`status`	含义
`completed`	出纸完成
`failed`	失败，看 `error`
`canceled`	被取消

const job = await client.compose({ queueId }).addPdf(bytes).printAndWait({
  onStatus: (event) => updateProgress(event.status),   // 可选：中间状态
});
if (job.status === 'failed') showError(job.error);

默认最多等 120 秒，可用 timeoutMs 调整。批量打印时不要串行等待，用 print() + 事件订阅自行汇总更快。

「完成」的可信度分三级

不同平台和驱动对「出纸完成」的确认能力不同，PrintLink 不掩盖这层差异，终态任务会带 completionLevel：

device-reported —— 打印机自己报告完成，最可信；
spooler-completed —— 系统打印队列报告完成；
submitted —— 只确认已成功提交，之后的状态跟踪不到。

界面与代码都应按这个字段决定提示语的语气，不要一律显示「打印成功」。

取消任务

await client.cancelJob(jobId);        // 取消自己提交的任务（需 job.cancel 权限）

只能在任务还没出纸时取消。已经进入打印机的任务无法撤回。

查询任务

const job = await client.getJob(jobId);          // 单个任务详情
const jobs = await client.listJobs(50);          // 最近 50 条，仅限本站点提交的

任务详情里包含提交的参数、实际生效的参数、降级警告与状态时间线，可以据此向用户解释「为什么和我选的不一样」。

桌面端控制台「任务」页可以看到所有任务（不只是自己站点提交的），支持搜索、筛选、取消排队中的任务，并查看每页的渲染结果。任务产物默认保留 7 天，可在设置里调整（1–365 天）。

避免同一张单打两遍

网络抖动或用户连点可能造成同一张单据打两次。给任务一个幂等键即可：

await client.compose({ queueId })
  .addPdf(bytes)
  .idempotencyKey(`invoice-${invoiceNo}`)   // 1–128 位可见 ASCII
  .printAndWait();

相同幂等键的重复提交会被抑制，只执行一次；被抑制的提交通过 onDuplicateSuppressed() 通知，可以据此告诉用户「这张单已经打过了」。

换成预览

把 .printAndWait() 换成 .preview() 即为「先让人确认再出纸」，参数完全一样。见预览。

打印