跳到主要内容
版本：3.0.0

Playwright 文档转换（Aegis.Documents.Conversion.Playwright）

Aegis.Documents.Conversion.Playwright 负责 HTML 转 PDF。HTML -> OFD 也建立在这层能力之上，所以这页实际上对应的是整条浏览器渲染链路。

组件概览​

字段说明
组件名称Playwright 文档转换
真实类库Aegis.Documents.Conversion.Playwright
组件定位浏览器内核驱动的 HTML 转 PDF 引擎
默认接入方式通过 文档处理（Aegis.Documents） 一起装配
主要接口IHtmlToPdfConverter
主要配置Documents:Playwright
常见配套Razor 文档渲染、OFD 文档转换

什么时候重点看这页​

适合场景：

  • 你要做 HTML 转 PDF
  • 你要控制页眉页脚、边距、横向打印、等待页面加载完成
  • 你要排查浏览器路径、自动下载、并发数或冷启动问题
  • 你要做 Razor -> HTML -> PDF 这条链路

标准接法​

标准 Aegis 项目里，优先直接启用根组件：

{
  "Components": {
    "Services": [
      "Documents"
    ],
    "Middlewares": [
      "Documents"
    ]
  }
}

然后只准备 Documents:Playwright 配置即可：

{
  "Documents": {
    "Playwright": {
      "Strategy": "Auto",
      "Channel": null,
      "ExecutablePath": null,
      "AllowAutoDownload": false,
      "AutoStart": true,
      "Headless": true,
      "MaxConcurrency": 3,
      "LaunchTimeoutMs": 60000
    }
  }
}

最小使用示例​

[HttpGet("pdf")]
public async Task<IActionResult> GeneratePdf(
    [FromServices] IHtmlToPdfConverter converter)
{
    var html = "<html><body><h1>Hello PDF</h1></body></html>";
    var pdfBytes = await converter.ConvertAsync(html);

    return File(pdfBytes, "application/pdf", "output.pdf");
}

常见场景​

带页眉页脚​

var pdfBytes = await _converter.ConvertAsync(html, new HtmlToPdfOptions
{
    PageSize = PageSize.A4,
    Margin = new MarginSettings(top: 20, bottom: 20, left: 10, right: 10),
    Header = new HeaderFooterSettings
    {
        Center = "月度销售报告",
        Right = "[date]",
        FontSize = 10,
        Line = true
    },
    Footer = new HeaderFooterSettings
    {
        Center = "第 [page] 页 / 共 [toPage] 页",
        FontSize = 9
    }
});

等待异步内容加载完成​

var pdfBytes = await _converter.ConvertAsync(html, new HtmlToPdfOptions
{
    Load = new LoadSettings
    {
        WaitUntil = WaitUntil.NetworkIdle,
        WaitForSelector = ".chart-loaded",
        TimeoutMs = 60000
    }
});

横向打印​

var pdfBytes = await _converter.ConvertAsync(html, new HtmlToPdfOptions
{
    PageSize = PageSize.A4,
    Landscape = true
});

关键配置怎么理解​

配置项作用推荐理解
Strategy浏览器解析策略一般保持 Auto
Channel指定浏览器渠道已明确要用 Chrome / Edge 时再配
ExecutablePath指定浏览器路径离线部署或固定浏览器版本时使用
AllowAutoDownload无浏览器时自动下载默认关闭，线上更建议预装浏览器
AutoStart启动时预热浏览器建议保持 true
Headless是否无头模式线上一般保持 true
MaxConcurrency最大并发转换数按机器规格调
LaunchTimeoutMs浏览器启动超时浏览器冷启动慢时再调大

浏览器选择建议​

场景建议
普通 Windows 服务器直接走 Auto，优先使用系统 Edge
Linux 服务器预装 Chromium，再保持 Auto 或显式配置 ExecutablePath
离线环境明确配置 ExecutablePath
本地排查问题可暂时把 Headless 调成 false

接入后怎么确认生效​

可以用下面几项做验收：

  • 应用启动时没有浏览器解析失败日志
  • 控制器能正常注入 IHtmlToPdfConverter
  • 简单 HTML 可以稳定输出 PDF
  • 中文、页眉页脚、表格跨页等最常见场景都能正确渲染

常见问题​

程序提示找不到浏览器​

优先处理顺序：

  1. 确认服务器是否已安装 Chrome、Edge 或 Chromium
  2. 如为离线环境，显式配置 ExecutablePath
  3. 不建议把线上环境完全依赖在自动下载上

HTML 能渲染，但中文是方块​

这不是 Playwright 组件本身的问题，通常是服务器缺少中文字体。请补齐字体后再验证。

首页能导出，Razor 模板导出却缺少样式​

优先检查：

  • Documents 是否启用了 Middlewares
  • Documents:Razor:ResourceRootPath 是否正确
  • 模板里的静态资源是否使用 ~/ 开头