Render-Pipeline
Vom Dokument zu Seitenbildern
Zwischen OpenDocumentAsync und dem PNG, das den Browser erreicht, gibt es zwei getrennte Stufen: Viewer-Auflösung (welche Engine das Dokument lädt, einmal pro Öffnen entschieden) und Seitenverarbeitung (was mit jedem Seitenbild bei jeder Anforderung geschieht). Das Verständnis beider erklärt, warum ein Format so gerendert wird — und was DefaultRender wirklich umschaltet.
Stufe 1 — Auflösung des Format-Viewers
Die Fabrik ordnet die Dateierweiterung über den Formatkatalog einem Viewer zu, mit drei Prioritätsebenen:
- Benutzerdefinierte Viewer zuerst. Alles, was Sie mit
DoconutOptions.RegisterViewer(extension, factory, defaultConfig?)registriert haben, hat Vorrang vor allen eingebauten. - Eingebaute Familien-Viewer. Der Katalog ordnet jede anzeigbare Erweiterung einer Viewer-Familie zu — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — jede mit ihrem eigenen Engine-Adapter. Wenn ein lizenziertes Plugin einen Viewer für dieselbe Erweiterung bereitstellt, ersetzt der Plugin-Viewer den eingebauten.
AddDoconut()prüft registrierte Plugin-Berechtigungen beim Start; das Fallback der Fabrik zum eingebauten Viewer ist eine defensive Laufzeitregel. - Nur-Plugin-Formate. Einige Erweiterungen haben überhaupt keinen eingebauten Viewer — DICOM (
.dcm) existiert nur über das DICOM-Plugin. Das Öffnen ohne die erforderliche Fähigkeit wirft:
LicenseException: This document type requires the 'Dicom' plugin license.Eine Erweiterung, für die kein Viewer zuständig ist, löst aus:
FormatNotSupportedException: Document format '<extension>' is not supported.Nach der Auflösung ist die Konfiguration festgelegt: Ihr explizites Konfigurationsobjekt, falls Sie eines übergeben haben, andernfalls die Standardkonfiguration des Formats aus dem Katalog. DocOptions.Password wird in die Konfiguration für geschützte Dokumente kopiert.
Stufe 1b — Weiterleitungsmodus (DefaultRender = false)
Die meisten formatbezogenen Konfigurationen stellen ein DefaultRender-Flag bereit. Es wählt zwischen zwei grundlegend unterschiedlichen Pfaden:
DefaultRender = true— das Dokument wird nativ gerendert, direkt zu Seitenbildern.DefaultRender = false— das Dokument wird zuerst in ein PDF im Speicher konvertiert, die Quell-Engine wird freigegeben, und ein PDF-Viewer übernimmt. Das erzeugte PDF bettet echten Text ein, sodass die Volltextsuche pixelgenaue native Hervorhebungen erhält; die Pipeline erzwingtAllowSearchundAllowCopyfür das weitergeleitete PDF, da die Konvertierung für den Benutzer unsichtbar ist.
XPS und der Katalogstandard für MHT verwenden den Weiterleitungspfad. Eine PDF-Projektion kann native Suche für Formate wie HTML und Microsoft Project bereitstellen. Enthält das resultierende PDF Bilder ohne Textebene, kann der Standard-Viewer diese Pixel nicht durchsuchen.
Verwenden Sie den Weiterleitungsmodus, wenn Sie eine PDF-Projektion mit Text benötigen — auf Kosten einer anfänglichen Konvertierung beim Öffnen des Dokuments.
Stufe 2 — Die Seitenbild-Pipeline
Gerenderte Seiten werden pro Anforderung durch eine feste Sequenz verarbeitet:
raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response- Wasserzeichen — angewendet basierend auf dem Lizenzstatus (fehlende Lizenz, abgelaufene temporäre oder Abonnementlizenz, ungültige Domain, falsche Version) und von
DocOptions.Watermarkfür Ihren eigenen benutzerdefinierten Text. Eine korrekt lizenzierte Anwendung — oder eine aktive temporäre Lizenz — ohne benutzerdefiniertes Wasserzeichen überspringt diesen Schritt. - Drehen/Spiegeln — der pro Seite festgelegte Zustand, den der Benutzer im Widget einstellt (90°/180°/270°, horizontale/vertikale Spiegelungen), wird in der Sitzung gespeichert und bei jeder nachfolgenden Darstellung dieser Seite angewendet.
- Skalieren — Miniaturansichten und Zoomstufen werden erzeugt, indem die gerenderte Seite auf die gewünschte Zielgröße skaliert wird;
0bedeutet, in Originalgröße zu liefern. - Annotation einbrennen — gespeicherte Anmerkungen werden in das Bitmap gezeichnet, sodass Exporte und Seitenbilder sie zeigen.
- Kodierung — das Ergebnis wird zu PNG kodiert, wobei gepoolte Speicher-Streams verwendet werden, und direkt in die HTTP-Antwort geschrieben.
Fehler innerhalb der Middleware werden als PNG-Fehlerbilder (roter Text auf weiß) zurückgegeben, anstatt HTTP-Fehlerseiten, sodass das Widget sie im Seitenbereich anzeigen kann.
Seiten‑Caching
BaseConfig.CachePages (Standard true) hält gerenderte Seitenbilder im Speicher für die Lebensdauer der Dokumentsitzung, sodass ein erneuter Besuch einer Seite sie nicht neu rendert. BaseConfig.ImageResolution (25–300 DPI, 0 = Formatstandard) ist die Hauptregel für Qualität/Speicher; der Standard jedes Formats ist auf seiner Konfigurationsseite dokumentiert.
Rendering auf einem Knoten vs. vielen
Alles oben Beschriebene bezieht sich auf das Rendering auf einem einzelnen Knoten auf Abruf für die Sitzung, die das Dokument geöffnet hat. Eine Bereitstellung, bei der ein Knoten das gesamte Artefakt‑Set rendert und veröffentlicht, und andere Knoten diese Seiten aus gemeinsamem Speicher bereitstellen, verwendet einen anderen Lesepfad — siehe Verteilte Bereitstellungen.
Schriften unter Linux
Seiten werden mit den auf dem Server installierten Schriften gezeichnet. Unter Linux installieren Sie die Schriftkonfigurationsbibliothek, bevor das erste Dokument geöffnet wird (fontconfig auf RHEL und Fedora):
apt-get update && apt-get install -y libfontconfig1Ohne sie schlägt das Öffnen eines Dokuments mit The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. fehl. Es ist das einzige Systempaket, das Doconut benötigt; libgdiplus ist nicht erforderlich.
Seine Abhängigkeiten bringen ein Basis‑Schriftset (DejaVu) mit, sodass Dokumente sofort rendern. Ein Dokument, das eine Schrift anfordert, die der Server nicht hat — Calibri, Arial oder Times New Roman auf einem typischen Linux‑Image — erhält stattdessen die nächstgelegene installierte Schrift, sodass der Text eine andere Breite haben kann und Zeilenumbrüche von Windows abweichen können. Für eine Ausgabe, die Windows näher kommt, installieren Sie die metrisch kompatiblen Ersatzschriften fonts-liberation, fonts-crosextra-carlito und fonts-crosextra-caladea; fügen Sie fonts-noto-core oder fonts-noto-cjk für andere Schriftsysteme hinzu, oder kopieren Sie Ihre eigenen .ttf/.otf‑Dateien in /usr/share/fonts/ und führen Sie fc-cache -f aus.
Alpine und andere musl‑basierte Distributionen werden nicht unterstützt.
Wo man was einstellt
| Was Sie wollen | Einstellen |
|---|---|
| Scharfere Seiten | ImageResolution in der Formatkonfiguration |
| Genaue Textsuche in HTML/EPUB/E‑Mail/MHT/MPP | DefaultRender = false in der Formatkonfiguration |
| Weniger Speicher bei riesigen Dokumenten | CachePages = false, Sitzungen explizit schließen |
| Ihr eigener Stempel auf jeder Seite | DocOptions.Watermark |
War diese Seite hilfreich?