跳到主要内容
版本：3.0.0

文档处理

这页对应 3.x 里的文档处理与文件服务体系。标准入口是 文档处理（Aegis.Documents），如果还涉及文件上传、下载和落盘，再配合 文件管理（Aegis.FileManager） 或 NAS 文件存储（Aegis.FileManager.Nas）。

先看整体分工​

当前这组能力可以先按下面方式理解：

能力对应组件负责什么
根组件文档处理统一装配整套文档能力
HTML 转 PDFPlaywright 文档转换浏览器渲染型输出
Word 转 PDFLibreOffice 文档转换Office 文档输出
OFD 输出OFD 文档转换PDF/HTML/Word -> OFD
模板渲染Razor 文档渲染模板变 HTML
Word 编辑OpenXml 文档编辑填模板、改表格
文件抽象文件管理上传下载抽象、校验
NAS 落地NAS 文件存储文件真正存储到目录或 NAS

最常见的判断方式是：

  • 只要导出 PDF / OFD，先看 Documents
  • 只要模板渲染，先看 Razor
  • 只要修改 Word 文档，先看 OpenXml
  • 只要上传下载和文件落盘，先看 FileManager

最小接入方式​

1. 启用 Documents​

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

2. 准备常用配置​

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

3. 直接注入需要的接口​

public class ReportController : ControllerBase
{
    private readonly IHtmlToPdfConverter _htmlToPdfConverter;
    private readonly IWordToPdfConverter _wordToPdfConverter;
    private readonly ITemplateRenderer _templateRenderer;

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

最常用的几条业务链路​

HTML -> PDF​

[HttpGet("pdf")]
public async Task<IActionResult> GeneratePdf()
{
    var html = "<html><body><h1>Hello PDF</h1></body></html>";
    var pdfBytes = await _htmlToPdfConverter.ConvertAsync(html);
    return File(pdfBytes, "application/pdf", "output.pdf");
}

Word -> PDF​

[HttpPost("word-to-pdf")]
public async Task<IActionResult> ConvertWordToPdf(IFormFile file)
{
    var format = Path.GetExtension(file.FileName).ToLower() == ".docx"
        ? DocFormat.Docx
        : DocFormat.Doc;

    await using var stream = file.OpenReadStream();
    var pdfBytes = await _wordToPdfConverter.ConvertAsync(stream, format);

    return File(pdfBytes, "application/pdf", Path.ChangeExtension(file.FileName, ".pdf"));
}

Razor -> PDF​

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);

HTML -> OFD​

var ofdBytes = await _htmlToOfdConverter.ConvertAsync(html, new HtmlToOfdOptions
{
    PageSize = PageSize.A4,
    Render = new OfdRenderSettings
    {
        ImageFormat = OfdImageFormat.Jpeg,
        RenderDpi = 150
    }
});

Word 模板填充后再转 PDF​

var wordBytes = await _wordDocumentEditor.FillTemplateAsync(templateStream, new Dictionary<string, string>
{
    ["PatientName"] = "张三",
    ["VisitNo"] = "ZY20260318001"
});

await using var wordStream = new MemoryStream(wordBytes);
var pdfBytes = await _wordToPdfConverter.ConvertAsync(wordStream, DocFormat.Docx);

文件管理怎么接进来​

如果文档生成后还要上传、存档或下载，就继续接文件管理层。

启用校验​

builder.Services.AddFileValidation(options =>
{
    options.EnableValidation = true;
    options.StrictExtensionCheck = true;
});

启用 NAS 文件存储​

{
  "Components": {
    "Services": [
      "NasFileManager"
    ]
  },
  "NasStorage": {
    "RootPath": "/data/nas"
  }
}

业务里直接保存文件​

public class ArchiveService
{
    private readonly IFileManager _fileManager;

    public ArchiveService(IFileManager fileManager)
    {
        _fileManager = fileManager;
    }

    public bool SavePdf(string fileName, byte[] pdfBytes)
    {
        return _fileManager.UploadFile(fileName, pdfBytes, FileType.Pdf, "reports");
    }
}

运行环境怎么准备​

能力依赖
HTML -> PDFChrome / Edge / Chromium
Word -> PDFLibreOffice 7.0+
Linux 下 Word -> PDFLibreOffice 7.0+、Python、unoserver
OFD无额外系统依赖

环境准备和部署建议见：

接入后怎么验收​

建议至少做这几项：

  1. 生成一份最简单的 HTML -> PDF
  2. 上传一份 .docx，验证 Word -> PDF
  3. 用一份包含中文、表格、图片的模板做 Razor -> PDF
  4. 把 PDF 或 OFD 存入 IFileManager
  5. 回读文件并确认下载正常

常见问题​

启用了 Documents，但模板图片不显示​

优先检查：

  • Documents 是否同时放进了 Middlewares
  • Documents:Razor:ResourceRootPath 是否正确
  • 模板资源路径是否以 ~/ 开头

Word 转 PDF 报错，但 HTML 转 PDF 正常​

这通常说明浏览器环境没问题，但 LibreOffice 环境不完整。优先检查：

  • soffice --version
  • Linux 下 python3 / python3-uno / unoserver
  • 中文字体

文件管理启用了校验，但注入 IFileManager 失败​

这是因为你只启用了抽象和校验层，还没有接实际存储实现。需要继续启用 NasFileManager 或其他存储实现。