配置选项参考

大多数在 Aspose.PDF FOSS for .NET 中的加载、保存和转换操作接受一个 *Options 用于配置该操作行为的对象。 LoadOptions and SaveOptions 是此族的两个抽象根基：每个特定格式的加载器（HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions）派生自 LoadOptions，以及每个特定格式的写入器（PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions）派生自 SaveOptions。此页面解释了该族如何协同工作，并记录了尚未在转换和优化指南。

使用 LoadOptions 加载文档

每个 *LoadOptions 子类都继承自 LoadOptions 基类的 WarningHandler、WarningHandlerName、DisableFontLicenseVerifications 和 LoadFormat，随后添加其源格式特有的属性。

// HTML: resolve relative images/CSS against a base path
var htmlOptions = new HtmlLoadOptions("assets/");
htmlOptions.IsEmbedFonts = true;
using var htmlDoc = new Document("input.html", htmlOptions);

// Markdown: apply custom CSS while rendering to PDF
var mdOptions = new MdLoadOptions();
mdOptions.CssStyles = "body { font-family: sans-serif; }";
using var mdDoc = new Document("input.md", mdOptions);

// Plain text: control the rendered font size
var txtOptions = new TxtLoadOptions();
txtOptions.FontSize = 11;
using var txtDoc = Document.Open("input.txt", txtOptions);

// SVG: let the page size follow the artwork dimensions
var svgOptions = new SvgLoadOptions();
svgOptions.AdjustPageSize = true;
using var svgDoc = new Document("input.svg", svgOptions);

使用 PdfSaveOptions 保存为 PDF

PdfSaveOptions 在将 Document 导出为 PDF 时控制字体处理和临时文件位置。它从共享的 SaveOptions 基类继承了 CloseResponse、SaveFullPath、WarningHandler、CacheGlyphs 和 SaveFormat。

using var doc = Document.Open("input.pdf");

var pdfOptions = new PdfSaveOptions();
pdfOptions.DefaultFontName = "Arial";
pdfOptions.TempPath = "temp/";

doc.Save("output.pdf", pdfOptions);

导出为 HTML 和 SVG

HtmlSaveOptions 和 SvgSaveOptions 都派生自 UnifiedSaveOptions。除了转换指南中涉及的图像/字体/布局控制之外，HtmlSaveOptions 还允许您选择文档类型和分页策略，而 SvgSaveOptions 完全依赖继承的 SaveOptions/UnifiedSaveOptions 成员。

using var doc = Document.Open("input.pdf");

// Fixed-layout HTML5 output, split one file per page
var htmlOptions = new HtmlSaveOptions(HtmlDocumentType.Html5, fixedLayout: true);
htmlOptions.SplitIntoPages = true;
htmlOptions.ImageResolution = 150;
htmlOptions.Title = "Converted Document";
doc.Save("output.html", htmlOptions);

// SVG export configured through the shared SaveOptions members
var svgOptions = new SvgSaveOptions();
svgOptions.SaveFullPath = false;
doc.Save("output.svg", svgOptions);

使用 Document.Convert 的一步转换

Document.Convert 接受源 LoadOptions 和目标 SaveOptions，在一次静态调用中一起处理，这样您就可以在格式之间转换，而无需手动打开、转换和释放 Document。

var loadOptions = new HtmlLoadOptions();
var saveOptions = new PdfSaveOptions();

Document.Convert("input.html", loadOptions, "output.pdf", saveOptions);

文本提取选项

TextExtractionOptions 控制 TextAbsorber（以及 TextDevice）格式化提取的文本，独立于执行提取的吸收器或设备类。

using var doc = Document.Open("input.pdf");

var extractionOptions = new TextExtractionOptions(TextFormattingMode.Raw);
extractionOptions.ScaleFactor = 1.0;
extractionOptions.IgnoreResourceFontErrors = true;

var absorber = new TextAbsorber(extractionOptions);
doc.Pages[1].Accept(absorber);

string text = absorber.Text;

使用 OptimizationOptions 优化输出

OptimizationOptions 是一种独立的、与格式无关的文件大小压缩机制。它通过 Document.OptimizeResources 应用，而不是通过 *SaveOptions 类，因此可以与任何保存路径结合使用。

using var doc = Document.Open("input.pdf");

var optimizationOptions = new OptimizationOptions();
optimizationOptions.RemoveUnusedObjects = true;
optimizationOptions.CompressObjects = true;
optimizationOptions.SubsetFonts = true;
optimizationOptions.ImageCompressionOptions.CompressImages = true;
optimizationOptions.ImageCompressionOptions.ImageQuality = 80;

doc.OptimizeResources(optimizationOptions);
doc.Save("optimized.pdf");

技巧与最佳实践

每个 *LoadOptions 和 *SaveOptions 子类都继承 WarningHandler/WarningHandlerName——将两者一起设置以捕获可恢复的诊断信息。
优先使用特定格式的 *LoadOptions/*SaveOptions 实例，而不是依赖基于扩展名的格式推断，尤其在处理流而非文件路径时。
使用 Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) 进行一次性转换，而不是手动打开并重新保存 Document。
OptimizationOptions 与 *SaveOptions 系列无关——在调用 Save 之前先调用 OptimizeResources，即可在不论目标格式的情况下压缩输出。
在相同设置适用的多个文档之间复用同一个选项实例，而不是每次都重新构建。

常见问题

问题	原因	修复
加载 HTML 时未解析相对 image/CSS 路径	`HtmlLoadOptions.BasePath` 从未设置	通过 `HtmlLoadOptions(basePath)` 构造函数传递基础路径
生成了错误的输出格式	针对目标扩展名使用了不匹配的 `*SaveOptions` 子类或 `SaveFormat`	使用匹配目标格式的 `*SaveOptions` 子类
`OptimizeResources` 不会减小文件大小	`OptimizationOptions` 保持默认设置，未启用任何减小标志	显式设置 `RemoveUnusedObjects`、`CompressObjects` 和 `SubsetFonts`
加载/保存期间产生的警告会被静默丢弃	在未指定处理程序的情况下设置了 `WarningHandler`	将 `WarningHandler` 和 `WarningHandlerName` 一起设置

FAQ

LoadOptions 与 SaveOptions 有何区别？

LoadOptions 配置文档从非 PDF 源格式（HTML、Markdown、文本、SVG）读取的方式；SaveOptions 配置 Document 写入输出格式（PDF、HTML、SVG）的方式。每个特定格式的选项类只继承自这两个根类中的一个。

打开原生 PDF 时，我需要指定 LoadOptions 吗？

不需要。Document.Open 和 Document 构造函数接受普通文件路径或流来读取原生 PDF 输入。只有在导入非 PDF 源格式（例如 HTML、Markdown、文本或 SVG）时才需要使用 *LoadOptions 子类。

我可以在多个 Save 调用中复用同一个 SaveOptions 实例吗？

可以。选项实例只是一个普通的配置对象；它不保存每个文档的状态，因此相同的 PdfSaveOptions 或 HtmlSaveOptions 实例可以传递给 Save，用于多个共享相同设置的文档。

OptimizationOptions 与特定格式的 SaveOptions 类有什么区别？

OptimizationOptions 由 Document.OptimizeResources 消费，是保存之外的独立步骤。它会删除未使用的对象/流并在原位重新压缩图像，并且可以在调用 Save 之前，对任何 *SaveOptions 子类应用。

每种源/目标格式都有 LoadOptions 和 SaveOptions 两个类吗？

不一定是对称的。例如，Markdown 和纯文本当前提供 MdLoadOptions/TxtLoadOptions 用于导入，但没有相匹配的 *SaveOptions 对应项，反映了每种格式支持转换的方向。

API Reference 摘要

类 / 方法	描述
`LoadOptions`	所有文档加载选项类型的基类
`SaveOptions`	所有文档保存选项类型的基类
`HtmlLoadOptions`	将 HTML 导入为 PDF 文档的选项
`MdLoadOptions`	将 Markdown 导入为 PDF 文档的选项
`TxtLoadOptions`	将纯文本导入为 PDF 文档的选项
`SvgLoadOptions`	将 SVG 导入为 PDF 文档的选项
`PdfSaveOptions`	将文档保存为 PDF 的选项
`HtmlSaveOptions`	将文档另存为 HTML 的选项
`SvgSaveOptions`	将文档另存为 SVG 的选项
`UnifiedSaveOptions`	用于 `HtmlSaveOptions` 和 `SvgSaveOptions` 的共享基础
`Document.Convert`	使用 `LoadOptions`/`SaveOptions` 对进行的静态一步转换
`TextExtractionOptions`	用于 `TextAbsorber` 文本提取的格式化配置
`OptimizationOptions`	与格式无关的文档大小/资源优化设置
`Document.OptimizeResources`	将 `OptimizationOptions` 实例应用于文档

配置选项参考