Конвертеры тонкой настройки – конвертируйте 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.

// Render HTML to PDF using Java

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

// Initialize an HTML document from HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the PdfDevice class and specify the output file to render
    try (PdfDevice device = new PdfDevice("output.pdf")) {

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

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

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

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

// Render HTML to PDF in Java with custom page size

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

// Initialize a HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an 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 a PDF Device and specify options and output file
    try (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-файла, что в конечном итоге влияет на его размер и качество:

// Render HTML to PDF with custom resolution using Java

// Prepare HTML code and save it to a 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 the HTMLDocument class
try (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 the PdfDevice
    try (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
    try (PdfDevice 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-документы так, как они выглядят на экране или при печати, с применением соответствующих типов мультимедиа и таблиц стилей. В следующем примере показано, как настроить тип носителя:

// Render HTML to PDF with custom MediaType settings with Java

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

// Initialize an HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

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

    // Create a PDF Device and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

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

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

Цвет фона – Background Color

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

// Render HTML to PDF with custom background color using Java

// Prepare HTML code and save it to a 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 the HTMLDocument class
try (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 the PdfDevice class
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

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

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

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

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

// Render HTML to PDF and adjust to the widest page with Java

// Prepare 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 an HTML document from HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the PdfRenderingOptions class 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 an instance of the PdfDevice class and specify options and output file
    try (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.

// Render HTML to PDF with password protection using Java

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

// Initialize an HTML document from the HTML code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

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

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

    // Create a PDF Device and specify options and output file
    try (PdfDevice device = new PdfDevice(options, "output.pdf")) {

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

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

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

// Render HTML to JPG with custom resolution and antialiasing settings with Java

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

// Initialize an instance of the HTMLDocument class based on prepared code
try (HTMLDocument document = new HTMLDocument(code, ".")) {

    // Create an instance of the ImageRenderingOptions class
    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 the ImageDevice class
    try (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-документов:

// Merge HTML to PDF using Java

// Prepare 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 the PdfDevice class
try (PdfDevice device = new PdfDevice("output.pdf")) {

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

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

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

// Render HTML to PDF with timeout settings using Java

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

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

    // Create an instance of the PdfDevice class
    try (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, демонстрируемая возможностью использования нескольких средств визуализации, настройки общих и специфичных для формата параметров и даже управления тайм-аутами, делает его отличным выбором для создания высококачественных настраиваемых документов.