Opciones de renderizado

Las Opciones de renderizado le brindan control adicional sobre el dispositivo de renderizado. Cada dispositivo de renderizado – PdfDevice, XpsDevice, DocDevice, y ImageDevice tiene su propio conjunto único de opciones implementadas con clases PdfRenderingOptions, XpsRenderingOptions, DocRenderingOptions, y ImageRenderingOptions respectivamente. Puede cambiar el tamaño de la página, configurar márgenes y colores, establecer una contraseña de seguridad en el caso de un dispositivo PDF, etc. Personalizar las opciones de renderizado es esencial para lograr el documento de salida deseado. Por ejemplo, puede reducir el tamaño del archivo ajustando la calidad y resolución de la imagen o mejorar la legibilidad configurando los márgenes de la página y el formato del texto.

En este artículo, describimos en ejemplos de C# cómo usar las opciones de renderizado para personalizar el proceso de renderizado de HTML a PDF, XPS, DOCX e imágenes. Un dispositivo de renderizado toma un objeto de opciones como parámetro y representa un documento de salida. Para obtener más información, lea el artículo Dispositivo de renderizado.

A continuación se muestra una demostración de cómo utilizar PdfRenderingOptions para personalizar el tamaño de la página al representar HTML a PDF:

var code = @"<span>Hello, World!!</span>";

// Initialize an HTML document from HTML code
using var document = new HTMLDocument(code, ".");

// Create an instance of PdfRenderingOptions and set a custom page size
var options = new PdfRenderingOptions()
{
    PageSetup =
        {
            AnyPage = new Page(new Size(Length.FromInches(4),Length.FromInches(2)))
        }
};

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "file-with-custom-page-size.pdf");            

// Create an instance of the PdfDevice and specify the options and output file to render
using var device = new PdfDevice(options, savePath);

// Render HTML to PDF
document.RenderTo(device);

Opciones generales

El espacio de nombres Aspose.Html.Rendering consta de numerosos objetos de representación y clases de opciones de bajo nivel apropiadas responsables de representar documentos en la implementación de IDevice. Las clases RenderingOptions y CssOptions representan opciones de renderizado, o en otras palabras, opciones de renderizado generales. Estas opciones son válidas para todos los dispositivos de renderizado y todos los procesos de renderizado desde HTML a PDF, XPS, DOCX e Imágenes:

Property	Description
PageSetup	This property gets a page setup object and uses it for configuration output page-set.
Css	Gets a CssOptions object which is used for configuration of CSS properties processing.
BackgroundColor	This property sets the color that will fill the background of every page. By default, this property is Transparent.
HorizontalResolution	Sets horizontal resolution for output images in pixels per inch. The default value is 300 dpi.
VerticalResolution	Sets vertical resolution for output images in pixels per inch. The default value is 300 dpi.
MediaType	Sets MediaType which will be used for media queries resolution during rendering. Default value is Print.

Resolución horizontal y vertical

En el siguiente ejemplo, mostraremos cómo podemos controlar la resolución del archivo de imagen resultante, afectando en última instancia su tamaño y calidad:

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "spring.html");            

// Create an instance of HTML document
using var document = new HTMLDocument(documentPath);

// Prepare path to save output file 
string savePath1 = Path.Combine(OutputDir, "output_resolution_50.png");
string savePath2 = Path.Combine(OutputDir, "output_resolution_300.png");

// Create options for low-resolution screens
    var options1 = new ImageRenderingOptions()
    {
        HorizontalResolution = 50,
        VerticalResolution = 50
    };

// Create an instance of Image device
using var device1 = new ImageDevice(options1, savePath1);

// Render HTML to PNG
document.RenderTo(device1);


// Create options for high-resolution screens
var options2 = new ImageRenderingOptions()
{
    HorizontalResolution = 300,
    VerticalResolution = 300
};

// Create an instance of Image device
using var device2 = new ImageDevice(options2, savePath2);

// Render HTML to PNG
document.RenderTo(device2);

La siguiente imagen muestra el resultado del renderizado del archivo spring.html con resoluciones de 50 ppp y 300 ppp:

Tipo de medio CSS – CSS Media Type

CSS media-type is an important feature that specifies how a document will be presented on different media: on the screen, on paper, with a braille device, etc. There are a few ways to specify media-type for a style sheet, via linked style sheets or, via inlining:

Linked Style Sheet

 <link rel="stylesheet" type="text/css" media="print" href="style.css">

Inline Style Sheet

<style type="text/css">
@media print {
  body{ color: #000000; }
}
</style>

La API Aspose.HTML admite esta función, por lo que puede convertir documentos HTML tal como aparecen en la pantalla o impresos aplicando los tipos de medios y hojas de estilo correspondientes. El siguiente ejemplo muestra cómo configurar el tipo de medio:

// Create an option class
var options = new PdfRenderingOptions();

// Set the 'screen' media-type
options.Css.MediaType = MediaType.Screen;

Tenga en cuenta que el valor predeterminado de CssOptions.MediaType es Imprimir. Significa que el documento se convertirá aplicando hojas de estilo relacionadas con el dispositivo de impresión y se verá como en papel (puede usar la vista previa de impresión de su navegador para ver la diferencia). Entonces, si desea que el documento se vea tal como se muestra en la pantalla, debe usar MediaType.Screen.

Color de fondo – Background Color

La propiedad BackgroundColor se utiliza para establecer el color de fondo del documento de salida al representar archivos basados ​​en HTML en formatos PDF, XPS, DOCX o de imagen. De forma predeterminada, el color de fondo es transparente. Sin embargo, puede establecer esta propiedad en un color específico usando la clase RenderingOptions.

// Prepare path to a source HTML file
string documentPath = Path.Combine(DataDir, "spring.html");

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "spring.pdf");

// Create an instance of HTML document
using var document = new HTMLDocument(documentPath);

// Initialize options with 'Azure' as a background-color
var options = new PdfRenderingOptions()
{
    BackgroundColor = System.Drawing.Color.Azure
};

// Create an instance of PDF device
using var device = new PdfDevice(options, savePath);

// Render HTML to PDF
document.RenderTo(device);

Configuración de página – Page Setup

La configuración de página es un conjunto de parámetros que determinan el diseño de una página impresa. Esos parámetros incluyen todo, desde el tamaño de la página, los márgenes y el cambio de tamaño automático hasta las reglas de prioridad @page. Puede configurar fácilmente un diseño individual para cada página utilizando este conjunto de parámetros.

El siguiente ejemplo demuestra cómo crear un documento PDF con diferentes tamaños de página para las páginas izquierda y derecha (consulte la visualización del resultado en la figura (a) a continuación):

// Prepare HTML code
var code = @"<style>div { page-break-after: always; }</style>
<div>First Page</div>
<div>Second Page</div>
<div>Third Page</div>
<div>Fourth Page</div>";

// Initialize an HTML document from the HTML code
using var document = new HTMLDocument(code, ".");

// Create the instance of Rendering Options and set a custom page size
var options = new PdfRenderingOptions();
options.PageSetup.SetLeftRightPage(
    new Page(new Size(400, 150)),
    new Page(new Size(400, 50))
);

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "output-custom-page-size.pdf");

// Create the PDF Device and specify options and output file
using var device = new PdfDevice(options, savePath);

// Render HTML to PDF
document.RenderTo(device);

En algunos casos, el contenido de la página HTML puede ser más ancho que el tamaño de página definido con las opciones. Si no desea cortar el contenido de la página, puede probar la propiedad AdjustToWidestPage de la clase PageSetup. El siguiente ejemplo muestra cómo ajustar el tamaño de la página al contenido (consulte la visualización del resultado en la figura (b) a continuación):

// Prepare HTML code
var code = @"<style>
    div { page-break-after: always; }
</style>
<div style='border: 1px solid red; width: 300px'>First Page</div>
<div style='border: 1px solid red; width: 500px'>Second Page</div>";

// Initialize an HTML document from the HTML code
using var document = new HTMLDocument(code, ".");

// Create the instance of Rendering Options and set a custom page-size
var options = new PdfRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(400, 200));

// Enable auto-adjusting for the page size
options.PageSetup.AdjustToWidestPage = true;

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "output-widest-page-size.pdf");

// Create the PdfDevice and specify options and output file
using var device = new PdfDevice(options, savePath);

// Render HTML to PDF
document.RenderTo(device);

Para obtener más información sobre el proceso de renderizado, lea el artículo Dispositivo de renderizado.

Si está interesado en cómo utilizar las opciones de representación para cambiar el tamaño de las páginas del documento al tamaño del contenido y viceversa, visite el artículo ¿Cómo cambiar el tamaño del documento durante la conversión desde HTML?

Opciones de renderizado de PDF – PdfRenderingOptions

La clase PdfRenderingOptions, junto con las opciones generales, admite algunos parámetros específicos, como JpegQuality, DocumentInfo, Encryption y FormFieldBehaviour.

Property	Description
JpegQuality	Specifies the quality of JPEG compression for images. The default value is 95.
DocumentInfo	This property contains information about the output PDF document.
Encryption	This property gets or sets encryption details. If it is not set, then no encryption will be performed.
FormFieldBehaviour	This property specifies the behavior of form fields in the output PDF document.

La propiedad FormFieldBehaviour se utiliza para especificar el comportamiento de los campos de formulario en un documento PDF. Para saber qué significa aplanar un archivo PDF y cómo hacerlo usando la biblioteca Aspose.HTML for .NET, consulte el artículo Aplanar PDF.

El siguiente código C# demuestra cómo agregar cifrado a un archivo de salida PDF usando la clase PdfRenderingOptions:

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "document.html");

// Initialize the HTML document from the file
using var document = new HTMLDocument(documentPath);

// Create the instance of Rendering Options
var options = new PdfRenderingOptions();

// Set the permissions to the file
options.Encryption = new PdfEncryptionInfo(
        "user_pwd",
        "owner_pwd",
        PdfPermissions.PrintDocument,
        PdfEncryptionAlgorithm.RC4_128);

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "output-options.pdf");

// Create an instance of the PdfDevice and specify options and output file
using var device = new PdfDevice(options, savePath);

// Render HTML to PDF
document.RenderTo(device);

El ejemplo anterior muestra cómo crear una nueva instancia de PdfRenderingOptions y configurar opciones de cifrado para un archivo de salida PDF. Para esto, debe usar el constructor PdfEncryptionInfo(userPassword, ownerPassword, permissions, encryptionAlgorithm) para crear un objeto PdfEncryptionInfo, que define la configuración de cifrado para el archivo PDF. El constructor toma cuatro parámetros:

• userPassword y ownerPassword, que son necesarios para abrir y trabajar con el archivo PDF;
• permissions: un conjunto de permisos permitidos para un archivo PDF. En este caso, se especifica PdfPermissions.PrintDocument, que permite al usuario imprimir el documento;
• encryptionAlgorithm: el algoritmo de cifrado utilizado para proteger el archivo PDF. En este caso se utiliza PdfEncryptionAlgorithm.RC4_128, que es un algoritmo de cifrado RC4 de 128 bits.

Opciones de renderizado de imágenes – ImageRenderingOptions

La clase ImageRenderingOptions admite todas las opciones generales y le permite configurar opciones específicas, como suavizado (difuminado), configuración de representación de texto, formatos de imagen y compresión de imágenes.

Property	Description
Compression	Sets Tagged Image File Format (TIFF) Compression. By default, this property is LZW.
Format	Sets the ImageFormat (JPG, PNG, BMP, TIFF, or GIF). By default, this property is PNG.
UseAntialiasing	This property sets the rendering quality for the image.
Text	Gets a TextOptions object which is used for configuration of text rendering.

Consideremos cómo utilizar un objeto ImageRenderingOptions especializado para configurar la calidad de renderizado de la imagen. El siguiente ejemplo demuestra cómo cambiar la resolución y el antialiasing de la imagen resultante.

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "color.html");

// Initialize the HTML document from the file
using var document = new HTMLDocument(documentPath);

// Create an instance of Rendering Options
var options = new ImageRenderingOptions(ImageFormat.Jpeg)
{
    // Disable smoothing mode
    UseAntialiasing = false,

    // Set the image resolution as 75 dpi
    VerticalResolution = Resolution.FromDotsPerInch(75),
    HorizontalResolution = Resolution.FromDotsPerInch(75),
};

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "color-options.jpg");

// Create an instance of the ImageDevice and specify options and output file
using var device = new ImageDevice(options, savePath);

// Render HTML to JPG
document.RenderTo(device);

Opciones de renderizado XPS – XpsRenderingOptions

Los archivos XPS generados por nuestra biblioteca no tienen ningún parámetro específico. Todos los parámetros de XpsRenderingOptions se heredan de la clase base RenderingOptions y se describen aquí.

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "document.html");

// Initialize the HTML document from the file
using var document = new HTMLDocument(documentPath);

// Create an instance of Rendering Options
var options = new XpsRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(Length.FromInches(5), Length.FromInches(2)));

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "document-options.xps");

// Create an instance of the XpsDevice and specify options and output file
using var device = new XpsDevice(options, savePath);

// Render HTML to XPS
document.RenderTo(device);

Opciones de renderizado DOC – DocRenderingOptions

La clase DocRenderingOptions admite todas las opciones generales y le permite personalizar las propiedades FontEmbeddingRule y DocumentFormat para el archivo de salida.

Property	Description
FontEmbeddingRule	This property gets or sets the font embedding rule. Available values are Full and None. The default value is None.
DocumentFormat	This property gets or sets the file format of the output document. The default value is DOCX.

El siguiente ejemplo muestra cómo personalizar las opciones de representación para documentos de salida estableciendo el tamaño de página y la regla de incrustación de fuente:

// Prepare a path to a source HTML file
string documentPath = Path.Combine(DataDir, "nature.html");

// Initialize the HTML document from the file
using var document = new HTMLDocument(documentPath);

// Create an instance of Rendering Options and set a custom page size
var options = new DocRenderingOptions();
options.PageSetup.AnyPage = new Page(new Size(Length.FromInches(8), Length.FromInches(10)));
options.FontEmbeddingRule = (FontEmbeddingRule.Full);

// Prepare a path to save the converted file 
string savePath = Path.Combine(OutputDir, "nature-options.docx");

// Create an instance of the DocDevice and specify options and output file
using var device = new DocDevice(options, savePath);

// Render HTML to DOCX
document.RenderTo(device);

Puede descargar los ejemplos completos de C# y los archivos de datos desde GitHub.

Aspose.HTML ofrece Convertidores gratuitos en línea que pueden convertir archivos HTML, XHTML, MHTML, EPUB, XML y Markdown a una variedad de formatos populares. Puede convertir fácilmente sus documentos basados ​​en HTML a PDF, XPS, DOCX, JPG, PNG, GIF, TIFF y otros. Simplemente seleccione un archivo, elija el formato a convertir y listo. ¡Lo mejor de todo es que es completamente gratis!