Riferimento alle Opzioni di Configurazione

Riferimento alle Opzioni di Configurazione

La maggior parte delle operazioni di caricamento, salvataggio e conversione in Aspose.PDF FOSS per .NET accetta un *Options oggetto che configura il comportamento di quell’operazione. LoadOptions and SaveOptions sono le due radici astratte di questa famiglia: ogni loader specifico per formato (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) deriva da LoadOptions, e ogni writer specifico per formato (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) deriva da SaveOptions. Questa pagina spiega come la famiglia si integra e documenta le classi di opzioni non già coperte da Conversione e Ottimizzazione guida.

Caricamento dei Documenti con LoadOptions

Ogni sottoclasse di *LoadOptions condivide WarningHandler, WarningHandlerName, DisableFontLicenseVerifications e LoadFormat dalla classe base LoadOptions, quindi aggiunge proprietà specifiche per il suo formato di origine.

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

Salvataggio in PDF con PdfSaveOptions

PdfSaveOptions controlla la gestione dei font e la collocazione dei file temporanei durante la scrittura di un Document in PDF. Eredita CloseResponse, SaveFullPath, WarningHandler, CacheGlyphs e SaveFormat dalla base condivisa SaveOptions.

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

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

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

Esportazione in HTML e SVG

HtmlSaveOptions e SvgSaveOptions derivano entrambi da UnifiedSaveOptions. Oltre ai controlli di immagine/font/layout coperti nella guida di conversione, HtmlSaveOptions ti consente anche di scegliere la variante del documento e la strategia di impaginazione, mentre SvgSaveOptions si basa interamente sui membri ereditati 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);

Conversione in un solo passaggio con Document.Convert

Document.Convert accetta un LoadOptions di origine e un SaveOptions di destinazione insieme in una singola chiamata statica, così puoi convertire tra formati senza aprire, convertire e smaltire manualmente un Document.

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

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

Opzioni di estrazione del testo

TextExtractionOptions controlla come TextAbsorber (e TextDevice) formattano il testo estratto, indipendentemente da quale classe di assorbitore o dispositivo esegue l’estrazione.

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;

Ottimizzare l’output con OptimizationOptions

OptimizationOptions è un meccanismo separato, indipendente dal formato, per ridurre le dimensioni del file. Viene applicato tramite Document.OptimizeResources, non tramite una classe *SaveOptions, quindi può essere combinato con qualsiasi percorso di salvataggio.

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

Suggerimenti e migliori pratiche

• Ogni sottoclasse *LoadOptions e *SaveOptions eredita WarningHandler/WarningHandlerName - impostare entrambi insieme per acquisire diagnostica recuperabile.
• Preferisci un’istanza *LoadOptions/*SaveOptions specifica per il formato anziché fare affidamento sull’inferenza del formato basata sull’estensione, soprattutto quando si lavora con flussi invece di percorsi di file.
• Utilizza Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) per conversioni singole invece di aprire manualmente e risalvare un Document.
• OptimizationOptions è indipendente dalla famiglia *SaveOptions - chiama OptimizeResources prima di Save per ridurre l’output indipendentemente dal formato di destinazione.
• Riutilizza un’unica istanza di opzioni su più documenti quando le stesse impostazioni si applicano, invece di ricostruirla ogni volta.

Problemi comuni

FAQ

Qual è la differenza tra LoadOptions e SaveOptions?

LoadOptions configura come un documento viene letto da un formato sorgente non PDF (HTML, Markdown, text, SVG); SaveOptions configura come un Document viene scritto in un formato di output (PDF, HTML, SVG). Ogni classe di opzioni specifica per formato deriva esattamente da una di queste due radici.

Devo specificare LoadOptions quando apro un PDF nativo?

No. Document.Open e il costruttore di Document accettano un semplice percorso di file o stream per l’input di PDF nativo. Le sottoclassi di *LoadOptions sono necessarie solo quando si importa un formato sorgente non PDF come HTML, Markdown, text o SVG.

Posso riutilizzare la stessa istanza di SaveOptions in più chiamate a Save?

Sì. Un’istanza di opzioni è semplicemente un oggetto di configurazione di base; non contiene stato per documento, quindi la stessa istanza di PdfSaveOptions o HtmlSaveOptions può essere passata a Save per più documenti che condividono le stesse impostazioni.

In che modo OptimizationOptions è diverso dalle classi specifiche per formato SaveOptions?

OptimizationOptions è consumato da Document.OptimizeResources, un passaggio separato dal salvataggio. Rimuove oggetti/stream inutilizzati e ricomprime le immagini in loco, e può essere applicato prima di chiamare Save con qualsiasi sottoclasse di *SaveOptions.

Ogni formato sorgente/di destinazione ha sia una classe LoadOptions che una classe SaveOptions?

Non necessariamente simmetrico. Per esempio, Markdown e plain text attualmente espongono MdLoadOptions/TxtLoadOptions per l’importazione ma non hanno un corrispondente *SaveOptions, riflettendo quale direzione ciascun formato supporta per la conversione.

API Reference Sommario

Vedi anche

• Conversione e Ottimizzazione
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation