福昕 PDF SDK 打印能力与接入说明
本文面向开发者梳理福昕 PDF SDK 的打印相关能力。福昕 PDF SDK 的打印能力覆盖了桌面端物理打印、macOS 原生打印接入、服务端文件输出，以及文档偏好、脚本触发、XFA 表单等扩展场景。
这篇文章重点说明三类内容：
- 打印能力分别由哪些接口提供
- 常见打印路径及其适用方式
- 接入时需要关注的输出配置、打印偏好与回调处理
如果你的项目需要把 PDF 输出到物理打印机、系统打印服务，或直接生成 PDF / PostScript 文件，这篇文章可以作为接入前的快速参考。
组成打印能力的接口
打印相关能力并不是集中在一个单独模块里，而是分布在几个接口中：
| 接口 | 主要作用 | 适用场景 |
|---|---|---|
| Renderer | 将 PDF 页面输出到打印设备、位图或文件 | 物理打印、虚拟打印、服务端输出 |
| DocViewerPrefs | 读写文档内嵌的打印偏好 | 预设打印范围、缩放、份数 |
| ActionCallback | 接收脚本或动作触发的打印请求 | 自动化打印流程、宿主应用接管打印 |
| XFA::DocProviderCallback | 处理 XFA 表单文档的打印回调 | XFA 表单打印 |
常见的三条打印路径
1. Windows 物理打印
这条路径通过 Windows 设备上下文将 PDF 页面直接发送到物理打印机或系统虚拟打印机。
- 适用平台：Windows
- 入口：
Renderer(HDC dc, const wchar_t* printer_driver_name) - 常见场景：桌面端应用的打印菜单、需要接入系统打印机的本地程序
这类场景下，纸张大小、方向、份数等设置通常仍由 Windows 打印体系负责，SDK 主要完成页面渲染。
2. macOS 打印设备输出
在 macOS 上，可以通过 Core Graphics 上下文把 PDF 页面输出到打印设备。
- 适用平台：macOS
- 入口：
Renderer(const CGContextRef& context, DeviceType device_type) - 设备类型：
e_DeviceDisplay、e_DevicePrinter
如果你的应用已经接入 macOS 原生打印流程，这条路径更容易和系统打印服务保持一致。
3. 输出为 PDF 或 PostScript 文件
如果目标不是立即发送到物理打印机，而是先生成可继续流转的打印文件，可以使用文件输出方式。
- 适用平台：Windows、macOS、Linux
- 入口：
Renderer(const PrintDeviceSettingData& print_param, const wchar_t* dest_file_path) - 相关接口：PrintDeviceSettingData
- 输出格式：PDF（所有平台）、PostScript（仅 Linux）
- 授权说明：需要 Print2PDF 模块授权
这条路径更适合服务端或批处理场景，尤其是在 Linux 无桌面环境下，生成 PDF 或 PostScript 文件通常比直接对接物理打印机更容易落地。
文件输出方式配置
PrintDeviceSettingData 用于配置文件输出时的打印参数，常见项包括：
| 参数 | 说明 |
|---|---|
device_width / device_height | 输出设备尺寸，默认值对应 A4、300 DPI |
device_margin | 页面边距 |
orientation | 纵向或横向 |
resolution | 输出分辨率 |
copies | 打印份数，主要对 PostScript 输出生效 |
如果你的服务端任务需要固定纸张尺寸、固定分辨率或统一边距，这些参数通常需要在接入阶段提前确定。
打印输出效果控制
Renderer 提供了多项与打印效果相关的控制接口：
| 控制项 | API | 作用 |
|---|---|---|
| 打印模式 | EnableForPrint(true) | 仅渲染允许打印的注释 |
| 文本转图形 | SetPrintTextAsGraphic() | 降低字体依赖带来的差异 |
| 文本转图像 | SetPrintTextAsImage() | 以图像方式输出文本 |
| 叠印 | SetOverprint() | 适配专业印刷场景 |
| 抗锯齿 | SetAntiAliasing() | 分别控制文本、路径和图像的抗锯齿 |
其中，EnableForPrint(true) 在打印场景里比较关键。启用后，输出结果会遵循 PDF 中注释的打印标志，只保留允许打印的注释内容。
文档内嵌打印偏好处理
有些 PDF 会在文档中直接写入打印偏好。DocViewerPrefs 可以用来读取和设置这些参数：
| 偏好项 | API | 说明 |
|---|---|---|
| 打印区域 | GetPrintArea() / SetPrintArea() | 指定打印使用的页面框 |
| 打印裁剪 | GetPrintClip() / SetPrintClip() | 指定打印时的裁剪边界 |
| 打印缩放 | GetPrintScale() / SetPrintScale() | 设定是否按默认方式缩放 |
| 打印份数 | GetPrintCopies() / SetPrintCopies() | 预设打印对话框中的份数 |
| 打印页面范围 | GetPrintRange() / SetPrintRange() | 预设打印页面范围 |
如果你的产品需要在用户打开打印对话框前就给出默认配置，可以优先看这组接口。
脚本或动作触发的打印接管
如果 PDF 中的脚本或动作会触发打印，宿主应用通常需要通过 ActionCallback 接管这类请求。
基础打印回调如下：
cpp
virtual bool Print(const pdf::PDFDoc& document, bool is_ui,
const common::Range& page_range, bool is_silent,
bool is_shrunk_to_fit, bool is_printed_as_image,
bool is_reversed, bool is_to_print_annots) = 0;
如果需要更完整的打印参数，可以结合 PrintParams 使用。它覆盖的内容包括：
- 打印内容范围
- 双面打印方式
- 缩放与多页排版
- 小册子模式
- 打印机名称、输出文件名、页面范围、份数等输出控制项
此外，打印前后还可以接收事件触发：
e_TriggerDocWillPrinte_TriggerDocPrinted
如果你的业务需要在打印前做审计、日志、参数确认，或在打印后记录结果，这组回调会更有用。
XFA 表单打印接口
XFA 动态表单的打印由 XFA::DocProviderCallback 提供：
cpp
virtual void Print(const XFADoc& doc, int start_page_index,
int end_page_index, uint32 options) = 0;
常用打印选项包括：
| 选项 | 说明 |
|---|---|
e_PrintOptionShowDialog | 显示打印对话框 |
e_PrintOptionCanCancel | 允许取消打印 |
e_PrintOptionShrinkPage | 缩小页面以适应内容区域 |
e_PrintOptionAsImage | 以图像方式打印 |
e_PrintOptionReverseOrder | 逆序打印 |
e_PrintOptionPrintAnnot | 打印注释 |
如果项目里存在 XFA 表单，建议把普通 PDF 打印路径和 XFA 打印路径分开设计，不要混用同一套处理逻辑。
如果你的项目主要处理普通 PDF，可以优先从 Renderer 和 DocViewerPrefs 开始评估；如果涉及脚本触发打印或 XFA 表单，再补充对应的回调接口。