Referência de Opções de Configuração

Referência de Opções de Configuração

A maioria das operações de carregamento, gravação e conversão em Aspose.PDF FOSS para .NET aceita um *Options objeto que configura o comportamento dessa operação. LoadOptions and SaveOptions são as duas raízes abstratas desta família: cada carregador específico de formato (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) deriva de LoadOptions, e cada gravador específico de formato (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) deriva de SaveOptions. Esta página explica como a família se encaixa e documenta as classes de opções que ainda não foram abordadas pelo Conversão e Otimização guia.

Carregando Documentos com LoadOptions

Cada subclasse de *LoadOptions compartilha WarningHandler, WarningHandlerName, DisableFontLicenseVerifications e LoadFormat da classe base LoadOptions, e então adiciona propriedades específicas ao seu formato de origem.

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

Salvando em PDF com PdfSaveOptions

PdfSaveOptions controla o manuseio de fontes e a localização de arquivos temporários ao escrever um Document de volta como PDF. Ele herda CloseResponse, SaveFullPath, WarningHandler, CacheGlyphs e SaveFormat da base compartilhada SaveOptions.

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

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

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

Exportando para HTML e SVG

HtmlSaveOptions e SvgSaveOptions derivam ambos de UnifiedSaveOptions. Além dos controles de imagem/fonte/layout cobertos no guia de conversão, HtmlSaveOptions também permite escolher o tipo de documento e a estratégia de paginação, enquanto SvgSaveOptions depende inteiramente dos membros herdados 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);

Conversão em Um Passo com Document.Convert

Document.Convert aceita um LoadOptions de origem e um SaveOptions de destino juntos em uma única chamada estática, permitindo converter entre formatos sem abrir, converter e descartar manualmente um Document.

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

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

Opções de Extração de Texto

TextExtractionOptions controla como TextAbsorber (e TextDevice) formatam o texto extraído, independentemente de qual classe de absorvedor ou dispositivo realiza a extração.

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;

Otimizando a Saída com OptimizationOptions

OptimizationOptions é um mecanismo separado, independente de formato, para reduzir o tamanho do arquivo. Ele é aplicado através de Document.OptimizeResources, não por meio de uma classe *SaveOptions, podendo ser combinado com qualquer caminho de salvamento.

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

Dicas e Melhores Práticas

• Cada subclass de *LoadOptions e *SaveOptions herda WarningHandler/WarningHandlerName – configure ambos juntos para capturar diagnósticos recuperáveis.
• Prefira uma instância *LoadOptions/*SaveOptions específica de formato em vez de depender da inferência de formato baseada em extensão, especialmente ao trabalhar com streams em vez de caminhos de arquivo.
• Use Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) para conversões pontuais em vez de abrir e salvar manualmente um Document.
• OptimizationOptions é independente da família *SaveOptions – chame OptimizeResources antes de Save para reduzir a saída independentemente do formato de destino.
• Reutilize uma única instância de opções em vários documentos quando as mesmas configurações se aplicam, em vez de recriá-la a cada vez.

Problemas comuns

FAQ

Qual é a diferença entre LoadOptions e SaveOptions?

LoadOptions configura como um documento é lido de um formato de origem não PDF (HTML, Markdown, texto, SVG); SaveOptions configura como um Document é escrito para um formato de saída (PDF, HTML, SVG). Cada classe de opções específica de formato deriva exatamente de uma dessas duas raízes.

Preciso especificar LoadOptions ao abrir um PDF nativo?

Não. Document.Open e o construtor Document aceitam um caminho de arquivo simples ou um fluxo para entrada de PDF nativo. Subclasses de *LoadOptions são necessárias apenas ao importar um formato de origem não PDF, como HTML, Markdown, texto ou SVG.

Posso reutilizar a mesma instância de SaveOptions em várias chamadas de Save?

Sim. Uma instância de opções é apenas um objeto de configuração simples; não mantém estado por documento, portanto a mesma instância de PdfSaveOptions ou HtmlSaveOptions pode ser passada para Save para vários documentos que compartilham as mesmas configurações.

Como OptimizationOptions difere das classes SaveOptions específicas de formato?

OptimizationOptions é consumido por Document.OptimizeResources, uma etapa separada da gravação. Ele remove objetos/fluxos não utilizados e recomprime imagens no local, e pode ser aplicado antes de chamar Save com qualquer subclasse de *SaveOptions.

Todo formato de origem/destino possui tanto a classe LoadOptions quanto a classe SaveOptions?

Não necessariamente simétrico. Por exemplo, Markdown e texto simples atualmente expõem MdLoadOptions/TxtLoadOptions para importação, mas não há um contraparte *SaveOptions correspondente, refletindo em que direção cada formato é suportado para conversão.

API Reference Resumo

Ver também

• Conversão e Otimização
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation