Справочник параметров конфигурации

Справочник параметров конфигурации

Большинство операций загрузки, сохранения и конвертации в Aspose.PDF FOSS для .NET принимают *Options объект, который настраивает поведение этой операции. LoadOptions and SaveOptions являются двумя абстрактными корнями этой семьи: каждый загрузчик, специфичный для формата (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) наследуется от LoadOptions, и каждый записыватель, специфичный для формата (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) наследуется от SaveOptions. Эта страница объясняет, как семья взаимосвязана, и документирует классы параметров, которые ещё не охвачены Преобразование и Оптимизация руководство.

Загрузка документов с помощью LoadOptions

Каждый подкласс *LoadOptions наследует WarningHandler, WarningHandlerName, DisableFontLicenseVerifications и LoadFormat из базового класса LoadOptions, а затем добавляет свойства, специфичные для его исходного формата.

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

Сохранение в PDF с помощью PdfSaveOptions

PdfSaveOptions управляет обработкой шрифтов и размещением временных файлов при записи Document обратно в PDF. Он наследует CloseResponse, SaveFullPath, WarningHandler, CacheGlyphs и SaveFormat из общего базового класса SaveOptions.

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 — вызовите OptimizeResources перед Save, чтобы уменьшить размер вывода независимо от целевого формата.
• Переиспользуйте один экземпляр параметров для нескольких документов, когда применяются одинаковые настройки, вместо того чтобы каждый раз создавать его заново.

Распространённые проблемы

FAQ

В чём разница между LoadOptions и SaveOptions?

LoadOptions настраивает, как документ читается из исходного формата, отличного от PDF (HTML, Markdown, text, SVG); SaveOptions настраивает, как Document записывается в выходной формат (PDF, HTML, SVG). Каждый класс параметров, специфичный для формата, наследуется ровно от одного из этих двух корней.

Нужно ли указывать LoadOptions при открытии нативного PDF?

Нет. Document.Open и конструктор Document принимают простой путь к файлу или поток для нативного PDF-ввода. Подклассы *LoadOptions требуются только при импорте исходного формата, отличного от PDF, такого как HTML, Markdown, text или SVG.

Могу ли я переиспользовать один и тот же экземпляр SaveOptions для нескольких вызовов Save?

Да. Экземпляр параметров — это просто обычный объект конфигурации; он не содержит состояния, зависящего от документа, поэтому один и тот же экземпляр PdfSaveOptions или HtmlSaveOptions может быть передан в Save для нескольких документов, использующих одинаковые настройки.

Чем отличается OptimizationOptions от специфичных для формата классов SaveOptions?

OptimizationOptions используется Document.OptimizeResources, отдельным шагом от сохранения. Он удаляет неиспользуемые объекты/потоки и повторно сжимает изображения на месте, и может быть применён перед вызовом Save с любым подклассом *SaveOptions.

Есть ли у каждого исходного/целевого формата и класс LoadOptions, и класс SaveOptions?

Не обязательно симметрично. Например, Markdown и обычный текст в настоящее время предоставляют MdLoadOptions/TxtLoadOptions для импорта, но не имеют соответствующего *SaveOptions, отражая, в каком направлении каждый формат поддерживается для конвертации.

API Reference Сводка

См. также:

• Преобразование и оптимизация
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation