稳定性：stable。核心默认值来自 builderProps.ts；静默输出 handler 还补充 offsetPosition: null 和 showPrintConfPanel: false。未知字段会随对象进入当前打印链，但最终语义可能由下游打印服务解释。

调用方式与方法签名

api.print({ reportOptions, printOptions }, Vue): Promise<unknown>
api.printAll(batchReportOptions, printOptions, Vue, showBatchPrintProgress?): Promise<unknown>

参数与默认值

参数	类型	必填	默认值	说明
useDefaultPrinter	Boolean	否	true	找不到指定打印机时使用默认打印机
checkPrinter	Boolean	否	false	为 `true` 时在打印前检查打印机状态
zoom	String	否	fit	PDF 打印缩放策略
viewPdf	Boolean	否	false	是否预览 PDF；`printAll` 会移除此字段
businessId	String \| null	否	null	续打业务标识；`printAll` 不支持并移除
startPageNumber	Number	否	1	起始页码
showPrintOffset	Boolean	否	false	显示续打偏移；`printAll` 会移除
isPageReverse	Boolean	否	false	逆序页码/打印顺序
printName	String	否	`""`（调用链约定）	打印机名称，需目标客户端验证
printType	String	否	调用链决定	下游打印服务类型；不是 `builderProps` 的稳定默认值
page	String	否	空	页码表达式；批量打印最终移除指定页
paper	String	否	空	纸张名称，由打印客户端解释
pl	String	否	空	方向参数，由目标打印机/客户端解释
autoOpen	Boolean	否	链路中部分场景默认为 `true`	PDF 是否自动打开，需环境验证
printOffset	Number	否	无	续打偏移；`printAll` 会移除
offsetPosition	String[] \| null	否	`null`	偏移标记位置；`printAll` 会移除
showPrintConfPanel	Boolean	否	false	显示静默打印配置面板；`printAll` 会移除

旧文档还列出 duplex、scaleFactor、copies、popWindow、contextPath 等字段。当前实现会把调用方字段继续传入打印链，但这些字段没有统一的 OwlReport 默认值，且由客户端版本、操作系统和打印机解释；只有完成目标环境验证后才应使用，不视为稳定跨环境契约。

返回值与异常

print 和 printAll 返回 Promise。成功对象由打印服务决定；不要把旧文档中的固定 200 当作 createError 的统一成功契约。打印客户端/文件/服务异常分别可能对应 501/502/503。

最小示例

await api.print(
  {
    reportOptions: {
      reportCode: "sales-summary",
      reportVersion: "1.0.0",
    },
    printOptions: {
      useDefaultPrinter: true,
      checkPrinter: false,
      zoom: "fit",
      viewPdf: false,
    },
  },
  Vue,
);

iframe 模式差异

mount 的 iframe 分支会把 printOptions 与 reportOptions 一起写入同源子窗口的 $$BEEREPORT_PARAMS，并可能访问 contentWindow.document；真正打印仍取决于子页面和打印客户端。不要把跨域入口仅当作消息或 CSP 配置问题，也不要期待父页面同步读取子页打印状态。

常见错误

静默打印前在最终用户电脑探活 http://127.0.0.1:45111/bios-printer/。批量打印不要依赖续打、指定页或 viewPdf。