跳到主要内容
版本：3.0.0

OFD 文档转换（Aegis.Documents.Conversion.Ofd）

Aegis.Documents.Conversion.Ofd 负责 PDF -> OFD，同时也是 HTML -> OFD 和 Word -> OFD 的最后一跳。

组件概览​

字段说明
组件名称OFD 文档转换
真实类库Aegis.Documents.Conversion.Ofd
组件定位PDF 转 OFD 以及 OFD 输出链路的核心引擎
默认接入方式通过 文档处理（Aegis.Documents） 一起装配
主要接口IPdfToOfdConverter、IHtmlToOfdConverter、IWordToOfdConverter
主要配置单次调用时通过 HtmlToOfdOptions、WordToOfdOptions、OfdRenderSettings 传入
常见配套Playwright 文档转换、LibreOffice 文档转换

什么时候重点看这页​

适合场景：

  • 你要输出 OFD 电子单据
  • 你要控制 OFD 的 DPI、图像格式和页面尺寸
  • 你要判断 PDF -> OFD、HTML -> OFD、Word -> OFD 分别该怎么接

三条常见转换路径​

接口实际路径
IPdfToOfdConverterPDF -> OFD
IHtmlToOfdConverterHTML -> PDF -> OFD
IWordToOfdConverterWord -> PDF -> OFD

所以：

  • 如果输入已经是 PDF，直接注入 IPdfToOfdConverter
  • 如果输入是 HTML，最终会同时依赖 Playwright 和 OFD
  • 如果输入是 Word，最终会同时依赖 LibreOffice 和 OFD

最小使用示例​

PDF -> OFD​

[HttpPost("pdf-to-ofd")]
public async Task<IActionResult> ConvertPdfToOfd(
    IFormFile file,
    [FromServices] IPdfToOfdConverter converter)
{
    await using var stream = file.OpenReadStream();
    var ofdBytes = await converter.ConvertAsync(stream);

    return File(
        ofdBytes,
        "application/ofd",
        Path.ChangeExtension(file.FileName, ".ofd"));
}

HTML -> OFD​

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

Word -> OFD​

await using var stream = file.OpenReadStream();
var format = Path.GetExtension(file.FileName).ToLower() == ".docx"
    ? DocFormat.Docx
    : DocFormat.Doc;

var ofdBytes = await _wordToOfdConverter.ConvertAsync(stream, format);

渲染参数怎么理解​

OfdRenderSettings​

配置项默认值说明
ImageFormatPng图像格式，文字类文档更适合 Png
RenderDpi150渲染分辨率，越高越清晰，文件也越大

DPI 选择建议​

场景建议 DPI
屏幕预览72~96
普通打印150
高质量打印200~300

接入后怎么确认生效​

可以用下面几项验收：

  • IPdfToOfdConverter 能直接处理普通 PDF
  • IHtmlToOfdConverter 在 HTML 中文和图片场景下输出正常
  • IWordToOfdConverter 可以把 .docx 成功转成 OFD
  • 同一份文档在提高 DPI 后，清晰度有明显变化

常见问题​

OFD 文件过大​

优先从两处收：

  • 把 RenderDpi 从 200 降到 150 或 96
  • 图片较多时把 ImageFormat 改成 Jpeg

OFD 文字发虚​

通常是 DPI 过低，先把 RenderDpi 提高到 150 或 200 再看。

HTML -> OFD 或 Word -> OFD 失败​

这不一定是 OFD 引擎本身的问题，先回头检查上一跳：

  • HTML 场景检查浏览器环境
  • Word 场景检查 LibreOffice 和字体环境