Конвертеры тонкой настройки – конвертируйте HTML, MHTML, EPUB и SVG на Java

Вы можете конвертировать HTML в различные популярные форматы несколькими способами, используя Aspose.HTML for Java:

• С помощью методов convertHTML() класса Converter. Это наиболее распространенный способ преобразования HTML в различные форматы.
• С помощью метода renderTo(device) класса HTMLDocument или методов render() класса Renderer. Этот альтернативный способ рендеринга HTML-документов может дать вам больше контроля над процессом преобразования HTML в вашем Java-приложении.

Устройство рендеринга – Rendering Device

Устройство рендеринга (вывода) инкапсулирует поверхность 2D-рисования, API которой реализован с использованием интерфейса IDevice. В настоящее время Aspose.HTML for Java API реализует набор устройств рендеринга – PdfDevice, XpsDevice, DocDevice и ImageDevice, которые используются для создания файлов PDF, XPS, DOCX и изображений соответственно.

В следующем примере показано, как использовать PdfDevice для конвертации HTML-документа в PDF-файл. Процесс преобразования происходит с параметрами рендеринга по умолчанию:

1. Загрузите HTML-документ.
2. Создайте экземпляр класса PdfDevice, используя один из конструкторов PdfDevice().
3. Вызовите метод renderTo(device) класса HTMLDocument.

// Prepare an HTML code
String code = "<span>Hello World!!</span>";

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

// Create the PDF Device and specify the output file to render
PdfDevice device = new PdfDevice("output.pdf");

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

Параметры рендеринга

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

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

// Prepare an HTML code
String code = "<span>Hello World!!</span>";

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

// Create the instance of PdfRenderingOptions and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
PageSetup pageSetup = new PageSetup();
Page anyPage = new Page();
anyPage.setSize(
        new Size(
                Length.fromInches(5),
                Length.fromInches(2)
        )
);
pageSetup.setAnyPage(anyPage);
options.setPageSetup(pageSetup);

// Create the PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

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

Общие параметры – General Options

Параметры рендеринга дают вам дополнительный контроль над устройством вывода. Пакет com.aspose.html.rendering состоит из множества объектов рендеринга и соответствующих классов опций низкого уровня, отвечающих за рендеринг документов в реализации IDevice. Классы RenderingOptions и CssOptions представляют параметры рендеринга или, другими словами, общие параметры рендеринга.

Общие параметры действительны для всех устройств рендеринга и всех процессов рендеринга: HTML в PDF, XPS, DOCX и изображения. Давайте посмотрим на некоторые из них:

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

Настройки разрешения по горизонтали и вертикали необходимы для достижения высокого качества вывода при рендеринге HTML в другие форматы, например HTML в PDF. Горизонтальное и вертикальное разрешение измеряется в пикселях на дюйм (dpi) со значением по умолчанию 300 dpi. Этот параметр обеспечивает четкую детализацию и плавную визуализацию таких элементов, как текст, изображения, а также горизонтальные и вертикальные линии в документе PDF.

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

// Prepare an HTML code and save it to the file.
String code = "< style >\n" +
        "                p\n" +
        "        {\n" +
        "            background:\n" +
        "            blue;\n" +
        "        }\n" +
        "        @media(min - resolution:300dpi)\n" +
        "        {\n" +
        "            p\n" +
        "            {\n" +
        "                /* high resolution screen color */\n" +
        "                background:\n" +
        "                green\n" +
        "            }\n" +
        "        }\n" +
        "    </style >\n" +
        "    <p > Hello World !! </p >\n";

try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of HTML document
HTMLDocument document = new HTMLDocument("document.html");

// Create options for low-resolution screens
PdfRenderingOptions options = new PdfRenderingOptions();
options.setHorizontalResolution(Resolution.to_Resolution(50d));
options.setVerticalResolution(Resolution.to_Resolution(50d));

// Create an instance of PDF device
PdfDevice device = new PdfDevice(
        options,
        "output_resolution_50.pdf"
);

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

// Create options for high-resolution screens
options = new PdfRenderingOptions();
options.setHorizontalResolution(Resolution.to_Resolution(300d));
options.setVerticalResolution(Resolution.to_Resolution(300d));

// Create an instance of PDF device
device = new PdfDevice(
        options,
        "output_resolution_300.pdf"
);

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

Тип CSS-медиа – CSS Media Type

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

Связанная таблица стилей

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

Встроенная таблица стилей

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

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

// Prepare an HTML code
String code = "<span>Hello World!!</span>";

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

// Create an option class
PdfRenderingOptions options = new PdfRenderingOptions();
// Set the 'screen' media-type
options.getCss().setMediaType(MediaType.Screen);

// Create the PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

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

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

Цвет фона – Background Color

Параметр Background Color – это важная функция для настройки внешнего вида визуализированного документа. Это позволяет разработчикам указать цвет, которым будет заполняться фон каждой страницы выходного файла. По умолчанию для этого свойства установлено значение Transparent, что означает, что фон не будет иметь видимой заливки, если это не указано явно. Настройка цвета фона может улучшить читаемость документа, удовлетворить требования к фирменному оформлению или создать визуально привлекательный дизайн.

// Prepare an HTML code and save it to the file.
String code = "<p>Hello World!!</p>";
try (java.io.FileWriter fileWriter = new java.io.FileWriter("document.html")) {
    fileWriter.write(code);
}

// Create an instance of HTML document
HTMLDocument document = new HTMLDocument("document.html");

// Initialize options with 'cyan' as a background-color
PdfRenderingOptions options = new PdfRenderingOptions();
options.setBackgroundColor(Color.getCyan());

// Create an instance of PDF device
PdfDevice device = new PdfDevice(options, "output.pdf");

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

Настройка страницы – Page Setup

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

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

// Prepare an HTML code
String code = "    <style>\n" +
        "        div {\n" +
        "            page - break -after:always;\n" +
        "        }\n" +
        "    </style >\n" +
        "    <div style = 'border: 1px solid red; width: 400px' > First Page</div >\n" +
        "    <div style = 'border: 1px solid red; width: 600px' > Second Page</div >\n";
// Initialize the HTML document from the HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create the instance of Rendering Options and set a custom page-size
PdfRenderingOptions options = new PdfRenderingOptions();
options.getPageSetup().setAnyPage(new Page(new Size(500, 200)));

// Enable auto-adjusting for the page size
options.getPageSetup().setAdjustToWidestPage(true);

// Create the PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

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

Параметры PDF – PdfRenderingOptions Class

Класс PdfRenderingOptions предоставляет разработчикам широкие возможности управления процессом рендеринга при преобразовании HTML в PDF. Он позволяет настраивать все общие параметры и, кроме того, предлагает параметры, специфичные для рендеринга только в формате PDF: DocumentInfo, Encryption, FormFieldBehaviour и JpegQuality.

В следующем примере демонстрируется возможность установки разрешений для файла PDF.

// Prepare an HTML code
String code = "<div>Hello World!!</div>";
// Initialize the HTML document from the HTML code
HTMLDocument document = new HTMLDocument(code, ".");

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

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

// Create the PDF Device and specify options and output file
PdfDevice device = new PdfDevice(options, "output.pdf");

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

Параметры изображения – ImageRenderingOptions Class

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

// Prepare an HTML code
String code = "<div>Hello World!!</div>";

// Initialize an instance of HTML document based on prepared code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of Rendering Options
ImageRenderingOptions options = new ImageRenderingOptions();
options.setFormat(ImageFormat.Jpeg);

// Disable smoothing mode
options.setSmoothingMode(SmoothingMode.None);

// Set the image resolution as 75 dpi
options.setVerticalResolution(Resolution.fromDotsPerInch(75));
options.setHorizontalResolution(Resolution.fromDotsPerInch(75));

// Create an instance of Image Device
ImageDevice device = new ImageDevice(options, "output.jpg");

// Render HTML to Image
document.renderTo(device);

Рендереры – Renderers

Хотя метод renderTo(device) класса Document дает вам возможность отправить один документ на выходное устройство рендеринга, напрямую используя экземпляры Renderer вы можете отправить несколько файлов одновременно. Aspose.HTML for Java предоставляет следующую реализацию средств рендеринга: HtmlRenderer, SvgRenderer, MhtmlRenderer и EpubRenderer, которые используются для рендеринга HTML, SVG, MHTML и EPUB соответственно.

Следующий пример демонстрирует, как использовать HtmlRenderer для рендеринга нескольких HTML-документов:

// Prepare an HTML code
String code1 = "<br><span style='color: green'>Hello World!!</span>";
String code2 = "<br><span style='color: blue'>Hello World!!</span>";
String code3 = "<br><span style='color: red'>Hello World!!</span>";

// Create three HTML documents to merge later
HTMLDocument document1 = new HTMLDocument(code1, ".");
HTMLDocument document2 = new HTMLDocument(code2, ".");
HTMLDocument document3 = new HTMLDocument(code3, ".");

// Create an instance of HTML Renderer
HtmlRenderer renderer = new HtmlRenderer();

// Create an instance of PDF device
PdfDevice device = new PdfDevice("output.pdf");

// Merge all HTML documents into PDF
renderer.render(device, new HTMLDocument[]{document1, document2, document3});

Установить тайм-аут – Set Timeout

Еще одна важная функция, доступная для рендереров, – это настройка таймаута. Вы можете использовать его, чтобы указать, как долго вы готовы ждать завершения всех внутренних процессов, связанных с жизненным циклом документа, таких как загрузка ресурсов, активные таймеры и т. д. Конечно, вы можете указать бесконечный период ожидания. Однако если документ содержит скрипт с бесконечным циклом, ждать придется бесконечно. В примере ниже показано, как использовать параметр timeout в методе render(device, timeout, documents):

// Prepare an HTML code
String code = "< script >\n" +
        "        var count = 0;\n" +
        "        setInterval(function()\n" +
        "        {\n" +
        "            var element = document.createElement('div');\n" +
        "            var message = (++count) + '. ' + 'Hello World!!';\n" +
        "            var text = document.createTextNode(message);\n" +
        "            element.appendChild(text);\n" +
        "            document.body.appendChild(element);\n" +
        "        },1000);\n" +
        "</script >\n";

// Initialize an HTML document based on prepared HTML code
HTMLDocument document = new HTMLDocument(code, ".");

// Create an instance of HTML Renderer
HtmlRenderer renderer = new HtmlRenderer();

// Create an instance of PDF device
PdfDevice device = new PdfDevice("output.pdf");

// Render HTML to PDF
renderer.render(device, 5, document);

Заключение

Aspose.HTML for Java – это мощная и гибкая библиотека для рендеринга HTML, MHTML, EPUB и SVG в различные форматы, такие как PDF, XPS, DOCX и изображения. Класс Converter быстро и легко использовать для решения простых задач. Однако, если вам нужен больший контроль над параметрами рендеринга, используйте метод renderTo(device).

Благодаря широкому спектру параметров рендеринга и настраиваемых функций разработчики имеют полный контроль над выводом, включая разрешение, настройки страницы, типы мультимедиа CSS и конфигурации для конкретного устройства. Гибкость API, демонстрируемая возможностью использования нескольких средств визуализации, настройки общих и специфичных для формата параметров и даже управления тайм-аутами, делает его отличным выбором для создания высококачественных настраиваемых документов.