打印参数

份数、纸张、方向、单双面、彩色/黑白、质量、纸张类型、装订等选项怎么设，参数不生效时怎么查。

所有打印参数都在 options 里，print() 与 preview() 用法相同。

await client.compose({ queueId })
  .paper('A4')            // 纸张
  .copies(2)              // 份数
  .duplex('long-edge')    // 双面
  .color(false)           // 黑白
  .addPdf(bytes)
  .printAndWait();

一张任务一张纸

paper 是整条任务唯一的尺寸：混排时每一页都落在这张纸上。

不设置时由 PrintLink 推断，并在 warnings 里说明用了哪条规则：

情况	结果
你给了纸张（或配置档里设了）	就用它
没给，内容各页尺寸一致	用该尺寸（纸面跟随内容）
没给，各页尺寸不一致	取最大的一页，并给 `MIXED_PAGE_SIZES_UNIFIED`
没给，只有图片 / 网页	打印机默认纸张，取不到则 A4，并给 `PAPER_DEFAULTED`

拿不准时直接看一眼预览窗口状态栏，那里写的是实际用的纸张，不用猜。

常用选项

选项	取值	说明
`copies`	数字	份数。由打印机重复，不会复制预览缩略图
`orientation`	`auto` / `portrait` / `landscape`	纸面方向。省略 = `auto`，横向内容自动落到横向纸
`paper`	`auto` 或纸张对象	见上一节
`tray`	纸盒 id 或 `auto`	进纸器。省略 = 打印机默认
`duplex`	`auto` / `one-sided` / `long-edge` / `short-edge`	单双面与翻面方向
`color`	`true` 彩色 / `false` 黑白	省略 = 打印机默认
`quality`	`auto` / `draft` / `normal` / `high` / `best`	见下节
`mediaType`	纸张类型关键字	见「纸张类型」一节
`borderless`	`true` / `false`	无边框满版。省略 = 打印机默认
`collate`	`true` / `false`	多份时是否逐份分页
`reverseOrder`	`true` / `false`	倒序出纸
`pageRange`	如 `'1-8'`	只打输出页中的某几页，见下

「自动」的统一写法：auto 与「不填」完全等价，两者都表示交给 PrintLink 或打印机决定。

开关类选项（color、borderless、collate、reverseOrder）没有 auto： 省略就是「用打印机默认」，不要写成 false，两者含义不同。为方便表单，字符串 'true' / 'false' 也能提交，但 PrintLink 回给你的永远是布尔值。

打印质量

质量固定只有四档，界面和代码都是这四档：

取值	含义
`draft`	经济（最省墨、最快）
`normal`	标准
`high`	高
`best`	最佳
`auto`	省略或不填，交给打印机默认

各家打印机的档名五花八门（「经济模式」「低压缩 JPEG」「最佳照片」…），对调用方没有意义，因此 PrintLink 按位次把这四档映射到这台打印机自己的档位上：经济恒取第一档、最佳恒取最后一档。3 档的机器上「最佳」和「高」会落到同一档，这是正常的，四档始终可选。

想精确指定驱动里的某一档，用 outputQuality：

const caps = await client.getCapabilities(queueId);
caps.outputQuality?.supported;   // 驱动原始档位关键字
caps.outputQuality?.names;       // 每一档的显示名，只用于界面

两个都给时 outputQuality 优先。打印机没声明这一层时提交它会被丢弃并给警告，不会静默换档。

质量不控制照片模式

喷墨打印机是否进入照片模式（慢速多遍、照片墨量）由纸张类型决定，不是 quality。在照片纸上按「普通纸」打会发白发灰、颗粒明显，出纸也明显更快。见下一节。

纸张类型

想打照片、投影片这类特殊介质时，要同时设对纸张类型：

const caps = await client.getCapabilities(queueId);
caps.mediaTypes?.supported;   // 关键字列表，原样填进 options.mediaType

await client.compose({ queueId })
  .paper('4x6')
  .mediaType('photographic-glossy')   // 照片纸
  .addImage(photoBytes)
  .printAndWait();

关键字才是提交值，caps.mediaTypes.names 里的显示名只用于界面。
打印机没声明纸张类型时，提交它仍会放行但带 MEDIA_TYPE_UNVERIFIED 警告。
普通纸的关键字是 stationery，始终可用。

图片位置与大小

任务级的 pageLayout 只有三种统一预设：

预设	效果
`auto`（默认）	等比缩放到可打印区内并居中，不裁切
`actual`	原始大小，居中，超出部分裁切
`fill`	等比放大铺满可打印区，超出部分裁切

单张图片可以单独精细调整，且只影响这一张：

await client.compose({ queueId })
  .paper('A4')
  .addImage(cover)
  .imageLayout({
    mode: 'custom',
    horizontal: 'left',           // left | center | right
    vertical: 'top',              // top | center | bottom
    scalePercent: 80,             // 与 size 二选一
    offset: { xMm: 10, yMm: 15 }, // 微调位置
    rotate: 90,                   // 0 | 90 | 180 | 270
    flipHorizontal: true,
  })
  .addPdf(report)                 // 这一份不受上面影响
  .preview();

预览窗口里的拖动、缩放、旋转、翻转，写回的就是当前这一张图的这套设置。

只打某几页

pageRange 作用于输出页（合并后的最终页），与单份内容的 pageRange 互不干扰：

await client.compose({ queueId })
  .paper('A4')
  .addPdf(bytes).pageRange('2-4')   // 这一份 PDF 的 2–4 页
  .outputPageRange('1-2')           // 合并后只打前 2 页
  .print();

语法是 1 基的 '1-3,5'。写成 '3-1'、'a-b' 会得到 INVALID_REQUEST；部分越界会截断到实际页数并给 PAGE_RANGE_CLAMPED。

参数不生效怎么办

PrintLink 不会静默丢弃参数：打印机不支持某个取值时会按兼容方式降级，并在结果里给出结构化警告。

const check = await client.compose({ queueId }).paper('A3').addPdf(bytes).validate();
console.log(check.requested);   // 你要求的
console.log(check.effective);   // 实际会用的
console.log(check.warnings);    // 差异说明

推荐在提交前先 validate()，把差异展示给用户，而不是打完了才发现被降级。控制台「任务」页里每个任务也永久保留这三份数据。

常见警告：

警告	原因
`UNSUPPORTED_PRINT_OPTION`	该打印机不支持这个选项，已忽略或降级
`DUPLEX_NOT_SUPPORTED`	不支持双面，已按单面打
`COLOR_NOT_SUPPORTED`	不支持彩色，已按黑白打
`MEDIA_TYPE_UNVERIFIED`	打印机没报告纸张类型，无法确认取值有效
`PAPER_DEFAULTED`	没给纸张且推断不出，用了打印机默认
`MIXED_PAGE_SIZES_UNIFIED`	内容页尺寸不一致，统一到了最大页
`PAGE_RANGE_CLAMPED`	页段越界，已截断到实际页数

完整说明见错误码。

保存常用配置

同一台打印机反复用同一套参数时，存成配置档，打印时引用即可：

await client.compose({ queueId }).profile(profileId).addDocument(doc).print();

见打印机与配置档。

本页目录