文档排版与 PDF 转换（Windows，可选）

MS.Microservice.Documents.Rendering 用已安装的 Edge／Chrome 排版静态 HTML，用已安装的 LibreOffice 将 DOCX 转为 PDF。它是独立的可选组件，普通 Documents 使用者无需携带浏览器驱动；源码与包接入方式。

当前只支持 Windows，需要可用的 dotnet 主机，以及对应功能的排版引擎。组件不会下载或安装浏览器、LibreOffice，不使用用户登录或 Office 配置。HTML 转换要求浏览器沙箱可用，宿主运行身份及额外进程沙箱策略须允许浏览器创建上下文和页面。Playwright 依赖包约 203.6 MiB，本机 Windows 驱动复制约 102.2 MiB；发布时须保留驱动目录及 worker 文件。

HTML 转 PDF

using MS.Microservice.Documents.Rendering;

var renderer = new HtmlPdfRenderer(new()
{
    Channel = HtmlBrowserChannel.MicrosoftEdge,
    TemporaryDirectory = Path.Combine(Path.GetTempPath(), "my-app-rendering")
});
await using var output = new FileStream("report.pdf", FileMode.CreateNew);
var result = await renderer.RenderAsync(
    "<meta charset=utf-8><h1>中文报告</h1><p style='break-after:page'>第一页</p><p>第二页</p>",
    output, cancellationToken: cancellationToken);

Channel 也可选 GoogleChrome，或改为可信宿主配置的绝对 ExecutablePath；两者必须且只能提供一个。临时目录应由服务账户控制并允许创建、删除。输入是 HTML 字符串，目标从当前位置写入并保持打开；文件覆盖与原子发布由宿主负责。

额外资源通过 HtmlPdfOptions.Assets 显式传入，例如 options.Assets["logo.png"] 对应 HTML 的 <img src="logo.png">。值为 HtmlPdfAsset(内容类型, 字节数组)，支持 PNG、JPEG、静态 WebP、CSS、WOFF／WOFF2／TTF／OTF。名称区分大小写，须为单层文件名，不能是 index.html、.、.. 或包含 URL／路径分隔符。MIME 类型大小写不敏感。

参数 默认值 说明
WidthMillimeters / HeightMillimeters 210 / 297 纸张宽高，范围 10–1000 mm
MarginMillimeters 10 四边等宽，须为页面保留有效内容区域
PreferCssPageSize false 允许 CSS @page size 优先；结果仍受尺寸上限约束
PrintBackground true 打印背景色与背景图片
Timeout 30 s worker 处理期限，包含启动、排版、PDF 校验和 SDK 关闭；可配置至 10 分钟
MaximumHtmlBytes 4 MiB HTML 的 UTF-8 编码大小
MaximumAssets / MaximumAssetBytes / MaximumTotalAssetBytes 64 / 4 MiB / 32 MiB 资源数量、单份与累计编码大小
MaximumImagePixels 20M 每份图片资源的像素上限
MaximumPdfBytes / MaximumPages 32 MiB / 100 PDF 编码大小和页数上限；页数可配置为 1–10000

Maximum* 参数位于 HtmlPdfOptions.Limits。超时或取消后，进程树退出和临时目录清理另有最多 10 秒预算；整个调用不承诺 30 秒硬上限。目标流复制遵从调用方取消令牌，其 I/O 时长由目标流决定。

HTML 限制

HTML 流程、浏览器约束及验证见 HTML 渲染设计。

DOCX 转 PDF

libreOfficeExecutablePath 由可信宿主配置为已安装或完整便携 LibreOffice 的绝对 program/soffice.com 路径。仅使用 DOCX 转换时不需要安装浏览器；组件不会自动安装 LibreOffice 或修改系统注册表。

using MS.Microservice.Documents.Rendering;

var converter = new WordPdfConverter(new()
{
    LibreOfficeExecutablePath = libreOfficeExecutablePath,
    TemporaryDirectory = Path.Combine(Path.GetTempPath(), "my-app-rendering")
});
await using var input = File.OpenRead("contract.docx");
await using var output = new FileStream("contract.pdf", FileMode.CreateNew);
var result = await converter.ConvertAsync(input, output, cancellationToken: cancellationToken);

支持普通、未签名、未启用保护的 Transitional DOCX，包含正文、表格、页眉、页脚、分页及现代 DrawingML 内嵌 PNG／JPEG。支持 PAGE、NUMPAGES、SECTION、SECTIONPAGES 页码类字段及常用通用格式开关；跨 run 的字段也可识别。

参数 默认值 说明
WordPdfOptions.Timeout 60 s worker 处理期限，包含 DOCX 检查、引擎启动、转换、PDF 校验和结果传输；最多 10 分钟
MaximumInputBytes 64 MiB 从输入当前位置读取的 DOCX 编码大小
MaximumEntries 1024 ZIP 条目数量
MaximumExpandedBytes 128 MiB ZIP 实际展开的累计字节数
MaximumXmlCharactersPerPart 16M 每个 XML 部件的字符上限
MaximumImagePixels 20M 每幅内嵌 PNG／JPEG 的像素上限
MaximumPdfBytes / MaximumPages 32 MiB / 100 PDF 编码大小和页数；超限失败，不返回截断 PDF

Maximum* 参数位于 WordPdfOptions.Limits。DOCX 检查和转换在独立进程内完成；输入源不修改，输入和目标流从当前位置使用并保持打开，不能共用同一流或底层文件。

DOCX 限制

字段语法、包验证、进程生命周期及实际转换测试见 DOCX 渲染设计。

部署与输出约束