跳到主要内容
版本：3.0.0

文档处理（Aegis.Documents）

Aegis.Documents 是文档处理体系的根组件。标准接入时，优先直接启用它；HTML 转 PDF、Word 转 PDF、OFD 转换、OpenXml 编辑和 Razor 模板渲染都会一起装配好。

组件概览​

字段说明
组件名称文档处理
真实类库Aegis.Documents
组件定位文档转换、编辑和模板渲染的统一入口组件
引入方式安装 NuGet，并在 Component.deps.json 的 Services 和 Middlewares 中启用 Documents
组件声明Documents
核心能力HTML 转 PDF、Word 转 PDF、PDF 转 OFD、HTML 转 OFD、Word 转 OFD、OpenXml 编辑、Razor 渲染
典型配套Playwright 文档转换、LibreOffice 文档转换、OFD 文档转换、Razor 文档渲染

什么时候要用它​

适合场景：

  • 你要在 Aegis 项目里统一提供文档生成与转换能力
  • 你要直接在控制器或服务里注入转换器接口
  • 你既要文档转换，又要 Razor 模板渲染或 OpenXml 模板填充
  • 你希望按 Aegis 的标准方式接入，而不是手工拼装各个文档子模块

最小可运行路径​

第一步：安装根组件​

dotnet add package Aegis.Documents

第二步：在 Component.deps.json 中启用 Documents​

Documents 不只注册服务，还会启用静态文件中间件，所以标准接法是同时放到 Services 和 Middlewares。

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

第三步：准备常用配置​

{
  "Documents": {
    "Playwright": {
      "Strategy": "Auto",
      "AutoStart": true,
      "MaxConcurrency": 3
    },
    "LibreOffice": {
      "LibreOfficePath": null,
      "MaxConcurrency": 5,
      "ConversionTimeoutSeconds": 300
    },
    "Razor": {
      "TemplateRootPath": "Templates",
      "ResourceRootPath": "wwwroot",
      "StaticResourceStrategy": "Inline",
      "EnableAutoWarmup": true
    }
  }
}

第四步：在业务代码里直接注入接口​

[ApiController]
[Route("api/[controller]")]
public class ReportController : ControllerBase
{
    private readonly IHtmlToPdfConverter _htmlToPdfConverter;
    private readonly ITemplateRenderer _templateRenderer;

    public ReportController(
        IHtmlToPdfConverter htmlToPdfConverter,
        ITemplateRenderer templateRenderer)
    {
        _htmlToPdfConverter = htmlToPdfConverter;
        _templateRenderer = templateRenderer;
    }

    [HttpGet("invoice")]
    public async Task<IActionResult> DownloadInvoice()
    {
        var model = new
        {
            InvoiceNo = "INV-20260318-001",
            CustomerName = "张三",
            Amount = 1234.56m
        };

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

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

这个组件会带出哪些接口​

启用 Documents 后，最常直接使用的是下面这些接口：

接口用途
IHtmlToPdfConverterHTML 转 PDF
IWordToPdfConverterWord 转 PDF
IPdfToOfdConverterPDF 转 OFD
IHtmlToOfdConverterHTML 转 OFD
IWordToOfdConverterWord 转 OFD
ITemplateRendererRazor 模板渲染
IWordDocumentEditorOpenXml 文档编辑

常见接入顺序​

建议按这个顺序理解这组能力：

  1. 先确认你要的是 HTML、Word、OFD 还是模板渲染。
  2. 再准备对应的运行环境。
  3. 最后在控制器或服务里注入最贴近业务的接口。

最常见的几条路径是：

  • 网页或模板导出 PDF：ITemplateRenderer + IHtmlToPdfConverter
  • 上传 Word 后导出 PDF：IWordToPdfConverter
  • 生成电子单据 OFD：IHtmlToOfdConverter 或 IWordToOfdConverter
  • 先填充 Word 模板再下载：IWordDocumentEditor

运行环境怎么判断​

能力依赖
HTML 转 PDFChromium / Chrome / Edge
Word 转 PDFLibreOffice 7.0+
Linux 下 Word 转 PDFLibreOffice 7.0+、Python、unoserver
PDF 转 OFD无额外系统依赖

如果是中文文档，还要额外确认服务器字体可用。环境准备和部署细节见：

接入后怎么确认生效​

满足下面几项，通常就说明根组件已经接通：

  • 应用启动阶段没有浏览器、LibreOffice 或字体相关报错
  • Documents 已同时出现在 Services 和 Middlewares
  • 可以正常注入 IHtmlToPdfConverter、IWordToPdfConverter、ITemplateRenderer
  • Razor 模板中的 ~/css/...、~/images/... 资源能被正确处理

常见问题​

已经启用了 Documents，但模板里的图片或 CSS 仍然失效​

先检查两件事：

  • Component.deps.json 是否把 Documents 同时放进了 Middlewares
  • Documents:Razor:ResourceRootPath 是否指向了实际静态资源目录

HTML 转 PDF 没问题，Word 转 PDF 却失败​

这通常不是组件注册问题，而是运行环境不完整。优先检查：

  • soffice --version 是否达到 7.0+
  • Linux 机器是否具备 python3、python3-uno、unoserver
  • 中文字体是否已经安装

是否需要单独安装各个子包​

标准 Aegis 项目里，默认先用根组件 Aegis.Documents。只有你需要单独理解某项能力的边界、配置或排障时，再看对应子组件页面。