组合打印

一份多页 PDF 那样的体验，内容却可以来自不同地方：

第 1 页    照片
第 2–4 页  报告 PDF 的第 2–4 页
第 5 页    面单（绑定订单数据）

用户只看到一次预览、只点一次打印，打印队列里只有一条任务。

十行上手

const session = await client
  .compose({ queueId })
  .paper('A4')                                         // 一张纸，设一次
  .pageLayout('auto')                                  // 全任务统一预设
  .addImage(photoA).imageLayout({ mode: 'custom', scalePercent: 80 })
  .addPdf(reportPdf).pageRange('2-4')                  // 项级设置只作用于这一项
  .addImage(photoB).imageLayout({ mode: 'fill' })
  .addDocument(labelDoc).data({ orderNo: 'A-1024' })
  .preview();

console.log(session.pageCount);      // 5
console.log(session.source.items);   // 每一项落在哪些输出页
await client.previewPrint(session.previewSessionId);

不预览直接打就用 .printAndWait()；想看它实际发送了什么用 .toParams()。

几个关键规则

一条任务一张纸。 options.paper 是整条任务唯一的尺寸，每一页都落在它上面。 任何内容项都没有自己的纸张尺寸。要换纸就改任务纸张。

顺序就是页序。 add* 的调用顺序 = 输出页顺序。

项级设置只影响该项。 .pageRange() 跟在前一个 addPdf 后面，.data() 跟着 前一个 addDocument，.imageLayout() 跟着前一张图。类型层面也挡得住写错的组合 （比如 .addImage(x).pageRange() 是编译错误）。

份数不复制缩略图。 copies 由打印机重复，预览里仍然只显示一份。

限制

超限报错而不是静默截断。需要打 50 页以上时，考虑用 repeat 元素或分批提交。

用 repeat 做批量

同一份模板打 N 页（比如一批订单的面单）不要循环调用 print()，而是共用一条任务：

const job = client.compose({ queueId }).paper('100x150');
for (const order of orders) job.addDocument(template).data(order);
await job.printAndWait();

或者把循环放进模板里，用 repeat 元素——这样连 data 都只传一份。 见内容来源 · 模板文档。

预览里看到什么

• 缩略图按输出页排列，混排时每张带来源角标（图片 / PDF / 网页 / 模板）。
• 状态栏显示 输出 12 页 · 来源 4 项 · 纸张 A4 210×297 mm。
• 选中某一页会显示它来自哪里（例如「第 3 页 · PDF 2/3」）。
• 改纸张或任务级预设会对整批内容重新生成成品；改图片布局只影响那一张。

常见错误

• 按文件循环 print()：会变成 N 条任务、开 N 个预览窗口。永远用一次 compose() 或一份 items。
• 想给某一项设纸张尺寸：协议里没有这个字段，尺寸是任务级的。
• 用 pageRange 重排页序：它只是过滤器；重排请放多个项。
• 多个模板共用一份 data：数据跟着内容项走，请分别 .data()。

相关页面