Rendering-Optionen

Rendering Options gibt Ihnen zusätzliche Kontrolle über das Rendering-Gerät. Jedes Rendering-Gerät – PdfDevice, XpsDevice, DocDevice, und ImageDevice – verfügt über einen eigenen Satz von Optionen, die in den Klassen PdfRenderingOptions, XpsRenderingOptions, DocRenderingOptions bzw. ImageRenderingOptions implementiert sind. Sie können die Seitengröße ändern, Ränder und Farben konfigurieren, ein Sicherheitskennwort für ein PDF-Gerät festlegen usw. Die Anpassung der Rendering-Optionen ist wichtig, um das gewünschte Ausgabedokument zu erhalten. So können Sie beispielsweise die Dateigröße verringern, indem Sie die Bildqualität und -auflösung anpassen, oder die Lesbarkeit verbessern, indem Sie Seitenränder und Textformatierung einstellen.

In diesem Artikel wird anhand von C#-Beispielen beschrieben, wie Rendering-Optionen verwendet werden können, um den Rendering-Prozess von HTML zu PDF, XPS, DOCX und Bildern anzupassen. Ein Renderer-Gerät nimmt ein Options-Objekt als Parameter und stellt ein Ausgabedokument dar. Um mehr zu erfahren, lesen Sie bitte den Artikel Rendering Device.

Im Folgenden wird gezeigt, wie Sie mit PdfRenderingOptions die Seitengröße beim Rendern von HTML in PDF anpassen können:

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

Allgemeine Optionen

Der Namensraum Aspose.Html.Rendering besteht aus zahlreichen Renderer-Objekten und entsprechenden Low-Level-Optionen-Klassen, die für das Rendering von Dokumenten in der IDevice Implementierung verantwortlich sind. Die Klassen RenderingOptions und CssOptions repräsentieren Rendering-Optionen, oder mit anderen Worten, allgemeine Rendering-Optionen. Diese Optionen gelten für alle Rendering-Geräte und alle Rendering-Verfahren von HTML bis PDF, XPS, DOCX und Images:

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.

Horizontale und vertikale Auflösung

Im folgenden Beispiel zeigen wir, wie wir die Auflösung der resultierenden Bilddatei steuern können, was sich letztlich auf ihre Größe und Qualität auswirkt:

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

Das nächste Bild zeigt das Ergebnis des Renderings der Datei spring.html mit 50 dpi und 300 dpi Auflösung:

CSS-Medientyp

CSS der Medientyp ist ein wichtiges Merkmal, das angibt, wie ein Dokument auf verschiedenen Medien dargestellt werden soll: auf dem Bildschirm, auf Papier, mit einer Blindenschriftvorrichtung, usw. Es gibt mehrere Möglichkeiten, den Medientyp für eine Formatvorlage anzugeben: über verknüpfte Formatvorlagen oder durch 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>

Aspose.HTML API unterstützt diese Funktion, so dass Sie HTML-Dokumente so konvertieren können, wie sie auf dem Bildschirm oder im Druck aussehen, indem Sie die entsprechenden Medientypen und Stilvorlagen anwenden. Das folgende Beispiel zeigt, wie man den Medientyp einrichtet:

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

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

Bitte beachten Sie, dass der Standardwert von CssOptions.MediaType Print ist. Das bedeutet, dass das Dokument durch Anwendung von Stilvorlagen für das Druckgerät konvertiert wird und wie auf Papier aussieht (Sie können die Druckvorschau Ihres Browsers verwenden, um den Unterschied zu sehen). Wenn Sie also möchten, dass das Dokument so aussieht, wie es auf dem Bildschirm dargestellt wird, sollten Sie MediaType.Screen. verwenden

Hintergrundfarbe

Die Eigenschaft BackgroundColor wird verwendet, um die Hintergrundfarbe des Ausgabedokuments festzulegen, wenn HTML-basierte Dateien in PDF-, XPS-, DOCX- oder Bildformate gerendert werden. Standardmäßig ist die Hintergrundfarbe transparent. Sie können diese Eigenschaft jedoch mit der Klasse RenderingOptions auf eine bestimmte Farbe einstellen.

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

Seite einrichten

Die Seiteneinrichtung ist eine Reihe von Parametern, die das Layout einer gedruckten Seite bestimmen. Diese Parameter umfassen alles von der Seitengröße, den Rändern und der automatischen Größenanpassung bis hin zu den @Seitenprioritätsregeln. Mit diesen Parametern können Sie ganz einfach ein individuelles Layout für jede Seite einrichten.

Das nächste Beispiel zeigt, wie man ein PDF-Dokument mit unterschiedlichen Seitengrößen für die linke und rechte Seite erstellt (siehe die Ergebnisvisualisierung in Abbildung (a) unten):

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

In einigen Fällen kann der Inhalt der HTML-Seite breiter sein als die mit den Optionen festgelegte Seitengröße. Wenn Sie den Seiteninhalt nicht abschneiden möchten, können Sie die Eigenschaft AdjustToWidestPage der Klasse PageSetup verwenden. Das folgende Beispiel zeigt, wie man die Seitengröße an den Inhalt anpasst (siehe die Ergebnisvisualisierung in Abbildung (b) unten):

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

Um mehr über den Rendering-Prozess zu erfahren, lesen Sie bitte den Artikel Rendering Device.

Wenn Sie wissen möchten, wie Sie die Rendering-Optionen nutzen können, um die Größe der Dokumentseiten an die Größe des Inhalts anzupassen und umgekehrt, lesen Sie bitte den Artikel Wie kann ich die Größe des Dokuments während der Konvertierung von HTML ändern?

PDF-Rendering-Optionen

Die Klasse PdfRenderingOptions unterstützt neben allgemeinen Optionen auch einige spezifische Parameter wie JpegQuality, DocumentInfo, Encryption und 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.

Die Eigenschaft FormFieldBehaviour wird verwendet, um das Verhalten von Formularfeldern in einem PDF-Dokument festzulegen. Was es bedeutet, eine PDF-Datei zu reduzieren und wie man dies mit der Aspose.HTML for .NET-Bibliothek macht, erfahren Sie im Artikel PDF reduzieren.

Der folgende C#-Code zeigt, wie eine PDF-Ausgabedatei mit Hilfe der Klasse “PdfRenderingOptions” verschlüsselt werden kann:

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

Das obige Beispiel zeigt, wie man eine neue PdfRenderingOptions Instanz erstellt und Verschlüsselungsoptionen für eine PDF-Ausgabedatei festlegt. Dazu sollten Sie den PdfEncryptionInfo(userPassword, ownerPassword, permissions, encryptionAlgorithm) Konstruktor verwenden, um ein PdfEncryptionInfo Objekt zu erstellen, das die Verschlüsselungseinstellungen für die PDF-Datei definiert. Der Konstruktor benötigt vier Parameter:

– userPassword und ownerPassword, die zum Öffnen und Arbeiten mit der PDF-Datei erforderlich sind;

• permissions - eine Reihe von erlaubten Berechtigungen für eine PDF-Datei. In diesem Fall ist PdfPermissions.PrintDocument angegeben, wodurch der Benutzer das Dokument drucken kann;
• encryptionAlgorithm - der Verschlüsselungsalgorithmus, mit dem die PDF-Datei gesichert wird. In diesem Fall wird PdfEncryptionAlgorithm.RC4_128 verwendet, ein 128-Bit-RC4-Verschlüsselungsalgorithmus.

Optionen für die Bildwiedergabe

Die Klasse ImageRenderingOptions unterstützt alle allgemeinen Optionen und ermöglicht die Konfiguration spezifischer Optionen wie Anti-Aliasing, Text-Rendering-Konfiguration, Bildformatauswahl und Bildkomprimierung.

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.

Betrachten wir, wie man ein spezielles ImageRenderingOptions-Objekt verwendet, um die Rendering-Qualität für das Bild zu konfigurieren. Das folgende Beispiel zeigt, wie man die Auflösung und das Antialiasing für das resultierende Bild ändern kann.

// 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-Rendering-Optionen

Die von unserer Bibliothek erzeugten XPS-Dateien haben keine spezifischen Parameter. Alle Parameter von XpsRenderingOptions werden von der Basisklasse RenderingOptions geerbt und hier beschrieben

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

DOC-Rendering-Optionen

Die Klasse DocRenderingOptions unterstützt alle allgemeinen Optionen und ermöglicht es Ihnen, die Eigenschaften FontEmbeddingRule und DocumentFormat für die Ausgabedatei anzupassen.

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.

Das folgende Beispiel zeigt, wie Sie die Rendering-Optionen für Ausgabedokumente anpassen können, indem Sie die Regel für die Seitengröße und die Schrifteinbettung festlegen:

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

Sie können die vollständigen C#-Beispiele und Datendateien von GitHub herunterladen.

Aspose.HTML bietet kostenlose Online- Konverter, die HTML-, XHTML-, MHTML-, EPUB-, XML- und Markdown-Dateien in eine Reihe von gängigen Formaten konvertieren können. Sie können Ihre HTML-basierten Dokumente ganz einfach in PDF, XPS, DOCX, JPG, PNG, GIF, TIFF und andere konvertieren. Wählen Sie einfach eine Datei aus, wählen Sie das zu konvertierende Format, und schon sind Sie fertig. Und das Beste daran: Es ist völlig kostenlos!