Параметры рендеринга – С#

Параметры рендеринга дают вам дополнительный контроль над устройством рендеринга. Каждое устройство рендеринга – PdfDevice, XpsDevice, DocDevice, и ImageDevice имеет собственный уникальный набор параметров, реализованных с помощью классов PdfRenderingOptions, XpsRenderingOptions, DocRenderingOptions, и ImageRenderingOptions соответственно. Вы можете изменить размер страницы, настроить поля и цвета, установить пароль безопасности в случае устройства PDF и т. д. Настройка параметров рендеринга необходима для получения желаемого выходного документа. Например, вы можете уменьшить размер файла, настроив качество и разрешение изображения, или улучшить читаемость, настроив поля страницы и форматирование текста.

В этой статье мы опишем на примерах C#, как использовать параметры рендеринга для настройки процесса рендеринга из HTML в PDF, XPS, DOCX и изображения. Устройство визуализации принимает объект опций в качестве параметра и представляет выходной документ. Чтобы узнать больше, обратитесь к статье Устройство рендеринга.

Ниже показано, как использовать PdfRenderingOptions для настройки размера страницы во время рендеринга HTML в PDF:

// Render HTML to PDF in C# with custom page size

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

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

// Create an instance of PdfRenderingOptions and set a custom page size
PdfRenderingOptions 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 PdfDevice device = new PdfDevice(options, savePath);

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

Общие Hастройки

Пространство имен Aspose.Html.Rendering состоит из многочисленных объектов рендеринга и соответствующих низкоуровневых классов опций, отвечающих за рендеринг документов в IDevice реализации. RenderingOptions и CssOptions представляют общие параметры рендеринга. Эти параметры действительны для всех устройств рендеринга и всех процессов рендеринга HTML в PDF, XPS, DOCX и изображения:

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.

Горизонтальное и Вертикальное Разрешение

В следующем примере мы покажем, как мы можем управлять разрешением результирующего файла изображения, в конечном итоге влияя на его размер и качество:

// Render HTML to PNG with custom resolution using C#

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

// Create an instance of HTML document
using HTMLDocument 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
    ImageRenderingOptions options1 = new ImageRenderingOptions()
    {
        HorizontalResolution = 50,
        VerticalResolution = 50
    };

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

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


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

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

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

На следующем рисунке показан результат рендеринга файла spring.html с разрешением 50 dpi и 300 dpi:

CSS Media Type

CSS media-type – важная функция, которая определяет, как документ будет представлен на разных носителях: на экране, на бумаге, с помощью устройства Брайля и т. д. Существует несколько способов указать madia-type для таблицы стилей, через связанные таблицы стилей или через встраивание:

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>

Aspose.HTML API поддерживает эту функцию, поэтому вы можете преобразовывать HTML-документы так, как они выглядят на экране или при печати, применяя соответствующие типы носителей и таблицы стилей. В следующем примере показано, как настроить тип носителя:

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

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

Обратите внимание, что значением по умолчанию для CssOptions.MediaType является Print. Это означает, что документ будет преобразован с применением таблиц стилей, относящихся к печатающему устройству, и выглядит как на бумаге (вы можете использовать предварительный просмотр печати в браузере, чтобы увидеть разницу). Поэтому, если вы хотите, чтобы документ выглядел так, как он отображается на экране, вы должны использовать MediaType.Screen.

Цвет фона – Background Color

Свойство BackgroundColor используется для установки цвета фона выходного документа при преобразовании HTML-файлов в формат PDF, XPS, DOCX или форматы изображений. По умолчанию цвет фона прозрачный. Однако вы можете установить для этого свойства определенный цвет с помощью класса RenderingOptions.

// Render HTML to PDF with custom background color using C#

// 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 HTMLDocument document = new HTMLDocument(documentPath);

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

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

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

Параметры страницы – Page Setup

Параметры страницы – это набор параметров, определяющих макет печатной страницы. Эти параметры включают в себя все, от размера страницы, полей и автоматического изменения размера до правил приоритета @page. Используя этот набор параметров, вы можете легко настроить индивидуальный макет для каждой страницы.

В следующем примере показано, как создать PDF-документ с разными размерами страниц для левой и правой страниц (см. визуализацию результата на рисунке (a) ниже):

// Render HTML to PDF with custom page size using C#

// Prepare HTML code
string 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 HTMLDocument document = new HTMLDocument(code, ".");

// Create the instance of Rendering Options and set a custom page size
PdfRenderingOptions 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 PdfDevice device = new PdfDevice(options, savePath);

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

В некоторых случаях содержимое HTML-страницы может быть шире, чем размер страницы, определенный параметрами. Если вы не хотите обрезать содержимое страницы, вы можете попробовать свойство AdjustToWidestPage класса PageSetup. В следующем примере показано, как настроить размер страницы в соответствии с содержимым (см. визуализацию результата на рисунке (b) ниже):

// Render HTML to PDF and adjust to the widest page with C#

// Prepare HTML code
string 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 HTMLDocument document = new HTMLDocument(code, ".");

// Create the instance of Rendering Options and set a custom page-size
PdfRenderingOptions 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 PdfDevice device = new PdfDevice(options, savePath);

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

Чтобы узнать больше о процессе рендеринга, обратитесь к статье Устройство рендеринга.

Если вас интересует, как использовать параметры рендеринга для изменения размера страниц документа в соответствии с размером содержимого и наоборот, посетите статью Как изменить размер документа во время преобразования из HTML?

PDF Options

Класс PdfRenderingOptions, наряду с общими параметрами, поддерживает некоторые специфические параметры, такие как JpegQuality, DocumentInfo, Encryption и 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.

Свойство FormFieldBehaviour используется для указания поведения полей формы в документе PDF. Чтобы узнать, что означает сведение файла PDF и как это сделать с помощью библиотеки Aspose.HTML for .NET, обратитесь к статье Flatten PDF.

Следующий код C# демонстрирует, как добавить шифрование в выходной файл PDF с помощью класса PdfRenderingOptions:

// Render HTML to PDF with password protection using C#

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

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

// Create the instance of Rendering Options
PdfRenderingOptions 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 PdfDevice device = new PdfDevice(options, savePath);

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

В приведенном выше примере показано, как создать новый экземпляр PdfRenderingOptions и установить параметры шифрования для выходного файла PDF. Для этого вы должны использовать PdfEncryptionInfo(userPassword, ownerPassword, permissions, encryptionAlgorithm) для создания объекта PdfEncryptionInfo, который определяет параметры шифрования для файла PDF. Конструктор принимает четыре параметра:

• userPassword и ownerPassword, необходимые для открытия и работы с файлом PDF;
• permissions – набор разрешенных разрешений для файла PDF. В этом случае указывается PdfPermissions.PrintDocument, что позволяет пользователю распечатать документ;
• encryptionAlgorithm – алгоритм шифрования, используемый для защиты файла PDF. В этом случае используется PdfEncryptionAlgorithm.RC4_128, который представляет собой 128-битный алгоритм шифрования RC4.

Image Options

Класс ImageRenderingOptions поддерживает все общие параметры и позволяет настраивать определенные параметры, например сглаживание, конфигурацию рендеринга текста, выбор формата и сжатие изображений.

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 this image.
Text	Gets a TextOptions object which is used for configuration of text rendering.

Рассмотрим, как использовать специализированный объект ImageRenderingOptions для настройки качества рендеринга изображения. В следующем примере показано, как изменить разрешение и сглаживание для результирующего изображения.

// Render HTML to JPG with custom resolution and antialiasing settings with C#

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

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

// Create an instance of Rendering Options
ImageRenderingOptions 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 ImageDevice device = new ImageDevice(options, savePath);

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

XPS Options

Файлы XPS, сгенерированные нашей библиотекой, не имеют каких-либо определенных параметров. Все параметры XpsRenderingOptions унаследованы от базового класса RenderingOptions и описаны здесь.

// Render HTML to XPS with custom page size using C#

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

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

// Create an instance of Rendering Options
XpsRenderingOptions 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 XpsDevice device = new XpsDevice(options, savePath);

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

DOCX Options

Класс DocRenderingOptions поддерживает все общие параметры и позволяет настраивать свойства FontEmbeddingRule и DocumentFormat для выходной файл.

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.

В следующем примере показано, как настроить параметры рендеринга для выходных документов, установив размер страницы и правило встраивания шрифта:

// Render HTML to DOCX in C# with custom page settings

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

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

// Create an instance of Rendering Options and set a custom page size
DocRenderingOptions 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 DocDevice device = new DocDevice(options, savePath);

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

Вы можете скачать полные примеры C# и файлы данных с GitHub.

Aspose.HTML предлагает бесплатные онлайн Конвертеры, которые могут преобразовывать файлы HTML, XHTML, MHTML, EPUB, XML и Markdown в ряд популярных форматов. Вы можете легко конвертировать HTML-документы в форматы PDF, XPS, DOCX, JPG, PNG, GIF, TIFF и другие форматы. Просто выберите файл, выберите формат для преобразования, и все готово. Лучше всего то, что это совершенно бесплатно!