Referencia de Opciones de Configuración

Referencia de Opciones de Configuración

La mayoría de las operaciones de carga, guardado y conversión en Aspose.PDF FOSS para .NET aceptan un *Options objeto que configura el comportamiento de esa operación. LoadOptions and SaveOptions son las dos raíces abstractas de esta familia: cada cargador específico de formato (HtmlLoadOptions, MdLoadOptions, TxtLoadOptions, SvgLoadOptions) deriva de LoadOptions, y cada escritor específico de formato (PdfSaveOptions, HtmlSaveOptions, SvgSaveOptions) deriva de SaveOptions. Esta página explica cómo encaja la familia y documenta las clases de opciones que aún no están cubiertas por el Conversión y Optimización guía.

Cargando Documentos con LoadOptions

Cada subclase de *LoadOptions comparte WarningHandler, WarningHandlerName, DisableFontLicenseVerifications y LoadFormat de la clase base LoadOptions, y luego agrega propiedades específicas de su formato de origen.

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

Guardando en PDF con PdfSaveOptions

PdfSaveOptions controla el manejo de fuentes y la ubicación de archivos temporales al generar un Document como PDF. Hereda CloseResponse, SaveFullPath, WarningHandler, CacheGlyphs y SaveFormat de la base compartida SaveOptions.

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

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

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

Exportando a HTML y SVG

HtmlSaveOptions y SvgSaveOptions se derivan de UnifiedSaveOptions. Más allá de los controles de imagen/fuente/diseño cubiertos en la guía de conversión, HtmlSaveOptions también le permite elegir el tipo de documento y la estrategia de paginación, mientras que SvgSaveOptions depende íntegramente de los miembros heredados 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);

Conversión en un solo paso con Document.Convert

Document.Convert acepta un LoadOptions de origen y un SaveOptions de destino juntos en una única llamada estática, de modo que puede convertir entre formatos sin abrir, convertir y eliminar manualmente un Document.

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

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

Opciones de extracción de texto

TextExtractionOptions controla cómo TextAbsorber (y TextDevice) formatean el texto extraído, independientemente de qué absorbente o clase de dispositivo realice la extracción.

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;

Optimización de salida con OptimizationOptions

OptimizationOptions es un mecanismo separado, independiente del formato, para reducir el tamaño del archivo. Se aplica mediante Document.OptimizeResources, no a través de una clase *SaveOptions, por lo que puede combinarse con cualquier ruta de guardado.

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

Consejos y mejores prácticas

• Cada subclase de *LoadOptions y *SaveOptions hereda WarningHandler/WarningHandlerName - configure ambos juntos para capturar diagnósticos recuperables.
• Prefiera una instancia *LoadOptions/*SaveOptions específica del formato antes de depender de la inferencia de formato basada en extensiones, especialmente al trabajar con flujos en lugar de rutas de archivo.
• Utilice Document.Convert(srcFileName, loadOptions, dstFileName, saveOptions) para conversiones puntuales en lugar de abrir manualmente y volver a guardar un Document.
• OptimizationOptions es independiente de la familia *SaveOptions - llame a OptimizeResources antes de Save para reducir la salida sin importar el formato de destino.
• Reutilice una única instancia de opciones en varios documentos cuando se apliquen los mismos ajustes, en lugar de reconstruirla cada vez.

Problemas comunes

FAQ

¿Cuál es la diferencia entre LoadOptions y SaveOptions?

LoadOptions configura cómo se lee un documento a partir de un formato de origen que no es PDF (HTML, Markdown, texto, SVG); SaveOptions configura cómo se escribe un Document a un formato de salida (PDF, HTML, SVG). Cada clase de opciones específica de formato deriva de exactamente una de estas dos raíces.

¿Necesito especificar LoadOptions al abrir un PDF nativo?

No. Document.Open y el constructor de Document aceptan una ruta de archivo simple o un flujo para la entrada de PDF nativo. Las subclases de *LoadOptions solo son necesarias al importar un formato de origen que no sea PDF, como HTML, Markdown, texto o SVG.

¿Puedo reutilizar la misma instancia de SaveOptions en varias llamadas a Save?

Sí. Una instancia de opciones es simplemente un objeto de configuración simple; no mantiene estado por documento, por lo que la misma instancia de PdfSaveOptions o HtmlSaveOptions puede pasarse a Save para varios documentos que comparten la misma configuración.

¿En qué se diferencia OptimizationOptions de las clases específicas de formato SaveOptions?

OptimizationOptions es consumido por Document.OptimizeResources, un paso separado del guardado. Elimina objetos/streams sin usar y vuelve a comprimir imágenes en el sitio, y puede aplicarse antes de llamar a Save con cualquier subclase de *SaveOptions.

¿Cada formato de origen/destino tiene tanto una clase LoadOptions como una SaveOptions?

No necesariamente simétrico. Por ejemplo, Markdown y texto plano actualmente exponen MdLoadOptions/TxtLoadOptions para importación pero no hay una contraparte *SaveOptions coincidente, reflejando qué dirección cada formato admite para la conversión.

Resumen de API Reference

Ver también

• Conversión y Optimización
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation