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 是否正确
• 模板里的静态资源是否使用 ~/ 开头