DocFx 中自定义 PDF 输出页面方向与尺寸的技术实现

在技术文档生成工具 DocFx 中，用户经常需要将生成的文档导出为 PDF 格式。默认情况下，DocFx 使用纵向（Portrait）方向和标准页面尺寸（如 A4）来生成 PDF 文件。然而，在实际应用中，用户可能需要根据内容特性或打印需求调整页面方向和尺寸，例如使用横向（Landscape）方向或更大的页面尺寸（如 A3）。

技术背景

DocFx 底层使用 Playwright 进行 PDF 生成，Playwright 提供了丰富的 PDF 生成选项。其中关键参数 PreferCSSPageSize 决定了是否优先使用 CSS 中定义的页面尺寸设置。当该参数设为 true 时，PDF 生成会遵循 CSS 中通过 @page 规则定义的页面样式。

实现方案

要实现自定义 PDF 页面方向和尺寸，可以通过以下两个步骤完成：

1. 启用 CSS 页面尺寸优先
   在 DocFx 的 PDF 生成代码中，需要将 PagePdfOptions 的 PreferCSSPageSize 属性设为 true。这告知 Playwright 在生成 PDF 时优先采用 CSS 中定义的页面设置。

2. 定义打印样式
   在自定义模板的 CSS 文件（通常是 main.css）中添加打印媒体查询，通过 @page 规则指定所需的页面尺寸和方向。例如：

   @media print {
     @page {
       size: A3 landscape;
     }
   }
   

   这里可以灵活组合各种标准页面尺寸（A0-A10、Letter 等）和方向（landscape 或 portrait）。

实际应用建议

对于需要频繁切换不同输出格式的用户，可以考虑以下实践：

1. 创建多个 CSS 文件，分别定义不同的打印样式
2. 通过构建脚本或配置参数动态选择所需的 CSS 文件
3. 对于复杂文档，可以针对不同章节应用不同的页面设置
4. 在团队协作环境中，将这些配置纳入版本控制，确保输出一致性

注意事项

• 某些非常规页面尺寸可能需要特定打印机支持
• 横向布局时要注意内容元素的排列方式，避免出现不预期的换行或截断
• 建议在最终输出前进行测试打印，确认实际效果符合预期

通过这种基于 CSS 的方案，DocFx 用户可以灵活控制 PDF 输出的页面特性，满足各种专业文档的输出需求，而无需修改核心生成逻辑。这种解耦的设计也便于后续维护和扩展。