Puppeteer Sharp导出PDF分页时UI元素被切割截断问题咨询

Puppeteer Sharp 依赖Chromium内核的打印逻辑实现PDF导出，默认分页规则是按设置的页面尺寸硬切割，不会主动避让页面元素，就会出现UI元素从中间被拆分的问题，按以下步骤配置即可实现元素完整不被切割的正常分页效果：

• 第一步：添加打印专属CSS分页避让规则
  给所有不允许被拆分的元素（卡片、图片、表格行、按钮、代码块等）添加分页避让属性，兼容新旧版本内核：

  @media print {
    /* 给不可拆分元素统一加no-break类名 */
    .no-break {
      page-break-inside: avoid !important;
      break-inside: avoid !important;
    }
  
    /* 基础规则：避免图片、表格行、标题被截断 */
    img, tr, td, th, table, h1, h2, h3, h4 {
      page-break-inside: avoid !important;
      break-inside: avoid !important;
    }
  
    /* 避免标题单独留在页尾，和后续内容拆分 */
    h1, h2, h3, h4 {
      page-break-after: avoid !important;
      break-after: avoid !important;
    }
  
    /* 手动分页位置使用该类，强制从新页开始渲染 */
    .manual-page-break {
      page-break-before: always !important;
      break-before: page !important;
    }
  }
  

  注意：如果页面使用了flex、grid布局，部分Chromium版本对布局子项的分页避让支持有问题，打印样式中可将需要避让的元素外层容器临时改为display: block，即可正常触发避让规则。

• 第二步：排查失效的定位属性
  被设置为position: absolute、position: fixed的元素无法触发分页避让逻辑，导出PDF前需要将这类非必要的特殊定位改为position: relative或默认静态定位。

• 第三步：优化Puppeteer Sharp导出参数
  生成PDF时预留足够页边距，开启背景打印，优先识别CSS打印规则，参考配置：

  await page.PdfAsync("export_result.pdf", new PdfOptions
  {
      Format = PaperFormat.A4,
      PrintBackground = true,
      PreferCSSPageSize = true,
      MarginOptions = new MarginOptions
      {
          Top = "18mm",
          Bottom = "18mm",
          Left = "12mm",
          Right = "12mm"
      }
  });
  

• 特殊场景适配
  如果单个元素高度超过单页可渲染高度（比如长表格、超长截图），不要给这类元素加break-inside: avoid，否则会导致前一页出现大面积空白，这类元素可以通过手动插入分页符的方式控制拆分位置，保证拆分后内容可读性。

问题示例截图：

内容的提问来源于stack exchange，提问作者user3310437