跳到主要内容
版本：3.0.0

Razor 文档渲染（Aegis.Documents.Rendering.Razor）

Aegis.Documents.Rendering.Razor 负责把 Razor 模板渲染成 HTML。它自己不直接输出 PDF 或 OFD，而是通常和 IHtmlToPdfConverter、IHtmlToOfdConverter 组合使用。

组件概览​

字段说明
组件名称Razor 文档渲染
真实类库Aegis.Documents.Rendering.Razor
组件定位模板渲染层，把模型数据转成 HTML
默认接入方式通过 文档处理（Aegis.Documents） 一起装配
主要接口ITemplateRenderer
主要配置Documents:Razor
常见配套Playwright 文档转换、OFD 文档转换

什么时候重点看这页​

适合场景：

  • 你要按业务数据套模板生成 PDF
  • 你要把发票、单据、报表等页面模板化
  • 你要处理模板目录、静态资源、预热和资源缓存

标准接法​

Razor 渲染标准上还是跟着根组件 Documents 走，然后准备 Documents:Razor 配置。

{
  "Documents": {
    "Razor": {
      "TemplateRootPath": "Templates",
      "ResourceRootPath": "wwwroot",
      "StaticResourceStrategy": "Inline",
      "EnableAutoWarmup": true,
      "EnableResourceCache": true,
      "WatchResourceChanges": false
    }
  }
}

最小使用示例​

[HttpGet("{id}")]
public async Task<IActionResult> DownloadInvoice(
    int id,
    [FromServices] ITemplateRenderer renderer,
    [FromServices] IHtmlToPdfConverter pdfConverter)
{
    var model = new
    {
        InvoiceNo = $"INV-{id:D6}",
        CustomerName = "张三",
        Amount = 1234.56m,
        CreateTime = DateTime.Now
    };

    var html = await renderer.RenderAsync("Invoices/Template.cshtml", model);
    var pdfBytes = await pdfConverter.ConvertAsync(html);

    return File(pdfBytes, "application/pdf", $"invoice-{id}.pdf");
}

推荐目录结构​

Templates/
├── _ViewImports.cshtml
├── _Layout.cshtml
├── Shared/
│   ├── _Header.cshtml
│   └── _Footer.cshtml
└── Invoices/
    └── Template.cshtml

wwwroot/
├── css/
│   └── invoice.css
└── images/
    └── logo.png

模板和静态资源怎么写​

模板里建议按 Web 资源的写法组织：

@model InvoiceModel
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="~/css/invoice.css" />
</head>
<body>
    <img src="~/images/logo.png" alt="Logo" />
    <h1>发票 @Model.InvoiceNo</h1>
</body>
</html>

通常要记住两点：

  • 模板路径是相对 TemplateRootPath
  • CSS、图片等静态资源路径以 ~/ 开头最稳

关键配置怎么理解​

配置项作用
TemplateRootPath模板根目录
ResourceRootPath静态资源根目录
PathMappings额外的虚拟路径映射
StaticResourceStrategy静态资源处理策略，默认 Inline
EnableAutoWarmup是否启动时自动预热模板
EnableResourceCache是否缓存静态资源内容
WatchResourceChanges是否监控资源文件变化

Inline 是文档导出场景里最常用的默认值，因为转换器处理的是内存中的 HTML，静态资源内联后更稳定。

常见场景​

手动预热常用模板​

var renderer = app.Services.GetRequiredService<ITemplateRenderer>();
await renderer.WarmupAsync(new[]
{
    "Invoices/Template.cshtml",
    "Reports/Monthly.cshtml"
});

Razor -> OFD​

var html = await _templateRenderer.RenderAsync("Invoices/EInvoice.cshtml", invoice);
var ofdBytes = await _htmlToOfdConverter.ConvertAsync(html);

接入后怎么确认生效​

可以用下面几项验收：

  • ITemplateRenderer 可以正常注入
  • 模板文件改动后能正确渲染新内容
  • ~/css/...、~/images/... 资源能正确进入最终 HTML
  • 经过 PDF / OFD 转换后样式和图片仍然存在

常见问题​

模板能渲染，但样式没有带进去​

优先检查：

  • ResourceRootPath 是否正确
  • 资源路径是否使用了 ~/
  • Documents 是否启用了 Middlewares

第一次导出很慢​

这是典型冷启动。可以：

  • 保持 EnableAutoWarmup = true
  • 对高频模板手动调用 WarmupAsync(...)

模板更新后站点仍然输出旧样式​

如果启用了资源缓存，开发期可以临时关闭 EnableResourceCache，或开启 WatchResourceChanges。