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

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

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

Ниже показано, как использовать PdfRenderingOptions для настройки размера страницы во время рендеринга HTML в 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);

Общие 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.

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

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

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

На следующем рисунке показан результат рендеринга файла 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.

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

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

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

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

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

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

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

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

Если вас интересует, как использовать параметры рендеринга для изменения размера страниц документа в соответствии с размером содержимого и наоборот, посетите статью Как изменить размер документа во время преобразования из 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:

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

В приведенном выше примере показано, как создать новый экземпляр 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 для настройки качества рендеринга изображения. В следующем примере показано, как изменить разрешение и сглаживание для результирующего изображения.

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

XPS Options

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

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

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.

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

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

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

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