Live-OOXML-Vertrag

DOCX-Genauigkeit und Sicherheit

Der Export-Endpoint in Next.js erzeugt lokal ein natives WordprocessingML-Paket. Diese Matrix ist an den laufenden Genauigkeitstest auf Paketebene im Repository gebunden; sie behauptet nicht, dass beliebiges Browser-CSS eine Eins-zu-eins-Entsprechung in Word hat. Zwei Konstrukte haben eigene Artikel: Formeln, die einen Hin- und Rückweg durch Word überstehen und was tatsächlich in einer .docx steckt.

Getestete Zuordnungen

Bereich	Native DOCX-Ausgabe
Dokumentstruktur	Überschriften, Absätze, Blockzitate, verschachtelte Aufzählungs- und Dezimallisten, Tabellen mit festem Layout
Zeichenformatierung	Fett, kursiv, unterstrichen, durchgestrichen, Code, Schriftfamilie und -größe, Text- und Hintergrundfarbe, tief- und hochgestellt
Absatzlayout	Ausrichtung, Ränder, Zeilenhöhe, Einzug der ersten Zeile, page-break-before und explizite Seitenumbrüche
Seitenlayout	Letter oder A4, Hoch- oder Querformat, begrenzte Ränder, Standard-Kopf- und -Fußzeilen, Felder für aktuelle Seite und Gesamtseitenzahl
Tabellen	Exaktes DXA-Raster, wiederholte Kopfzeilen, Spalten- und Zeilenverbund, Zellschattierung und vertikale Ausrichtung
Review-Semantik	Native DOCX-Einfügungen, -Löschungen, Kommentare, Fußnoten und Endnoten
Formeln	LaTeX, umgewandelt in natives OMML – Brüche, Hoch- und Tiefstellungen, Wurzeln, n-äre Operatoren, Klammern, Funktionen, Grenzwerte, Akzente, Striche und Kästen; im Formeleditor von Word bearbeitbar, kein Bild
Links und Medien	Links mit HTTP/HTTPS/mailto; Data-URIs für PNG, JPEG, GIF und BMP; vertrauenswürdige, vom Server aufgelöste Image-Map

Request-Vertrag

POST /api/export/docx
{
  "html": "<h1>Report</h1><p>Body</p>",
  "title": "Report",
  "fileName": "report.docx",
  "headerHtml": "<p>Private report</p>",
  "footerHtml": "<p>Page <span data-page-number="current"></span></p>",
  "page": { "size": "a4", "orientation": "landscape",
            "margin": { "top": 1080, "right": 900, "bottom": 1080, "left": 900 } },
  "imageMap": { "https://trusted.example/chart.png": "data:image/png;base64,..." }
}

Ränder werden in Zwanzigstelpunkt (Twips) angegeben und sind auf 360 bis 2880 begrenzt. Der Request ist auf 1 MiB begrenzt. Eine Image-Map nimmt höchstens acht HTTP(S)-Schlüssel an, nur Werte mit Bild-Data-URIs und insgesamt 768 KiB dekodiert.

Konventionen für semantisches HTML

<ins data-author="Ada" data-date="2026-07-16T12:00:00Z">added</ins>
<del data-author="Ada">removed</del>
<span data-comment="Check the source" data-comment-author="Reviewer">claim</span>
<sup data-footnote="Source citation"></sup>
<span data-endnote="Appendix detail"></span>
<hr class="page-break">

DOCX importieren

Der Import läuft vollständig im Browser, ohne Bibliothek und ohne Umweg über den Server. Eine .docx ist ein ZIP mit XML: Das zentrale Verzeichnis des ZIP wird direkt gelesen, und DecompressionStream("deflate-raw") übernimmt das Entpacken. Nichts wird irgendwohin hochgeladen.

Importiert	Wie, und was ein naiver Konverter verliert
Hyperlink-URLs	`w:hyperlink` enthält nur eine `r:id`; die Adresse steht in `word/_rels/document.xml.rels`. Wird aufgelöst – ohne das kommt jeder Link als reiner Text an, und die URL geht verloren.
Bilder	`w:drawing` → `a:blip` → `word/media/*`, als Data-URIs eingebettet. Setzen Sie `documentImportImages: false`, um sie bei bildlastigen Dateien zu überspringen.
Nummerierte und Aufzählungslisten	`document.xml` speichert jede Liste gleich; nur `word/numbering.xml` unterscheidet sie. Wird gelesen, sodass nummerierte Listen `<ol>` bleiben, statt zu Aufzählungen zu werden.
Verschachtelte Listen	`w:ilvl` ergibt echte Verschachtelung, und die Unterliste wird innerhalb ihres übergeordneten `<li>` platziert, damit das Markup gültig ist.
Fuß- & Endnoten	Word speichert den Text der Anmerkungen in separaten Teilen `word/footnotes.xml` und `word/endnotes.xml`; `document.xml` enthält nur eine ID. Alle werden gelesen und als lebendige Anmerkungen neu aufgebaut – fügen Sie eine über einer importierten Anmerkung ein, wird alles neu nummeriert. Die beiden Teile teilen ein Schema, aber keinen Elementnamen (`w:footnote` und `w:endnote`), sodass ein für den einen geschriebener Parser für den anderen stillschweigend nichts liefert. Die Trennzeichen-Einträge von Word werden übersprungen.
Textfelder	Der Inhalt von Textfeldern ist sechs Ebenen unterhalb des Runs verschachtelt (`w:pict` → `v:shape` → `v:textbox` → `w:txbxContent`), sodass ein Konverter, der nur direkte Kindelemente liest, jedes Wort davon verliert. Wird als Block `.rte-imported-textbox` in Dokumentreihenfolge wiederhergestellt, Absätze und Tabellen intakt. Ein Block `mc:AlternateContent` enthält dasselbe Feld zweimal – eine DrawingML-Version und einen VML-Fallback –, und nur eines davon wird ausgegeben.
Verfolgte Änderungen & Kommentare	`w:ins` und `w:del` werden als `<ins>`/`<del>` mit Autor und Datum importiert – dieselben Konventionen, die der Export ausgibt, sodass Review-Markup den Hin- und Rückweg übersteht. Gelöschter Text steht in `w:delText`, nicht in `w:t`. Kommentarbereiche werden zu `data-comment`-Spans, deren Text aus `word/comments.xml` stammt.
Formeln	Word speichert Formeln als `m:oMath`-Baum in einem eigenen math-Namespace, zwischen den Runs eingestreut – ein Konverter, der `w:r`-Elemente durchläuft, sieht ihn nie, und die Formel verschwindet, während der Satz um sie herum einwandfrei importiert wird. Wird in LaTeX übersetzt und als eigenes `rte-math-inline`-Span des Editors ausgegeben, sodass sie im Formeldialog bearbeitbar ist und mit dem Renderer dargestellt wird, den die Seite lädt. Brüche, Tief- und Hochstellungen, Wurzeln, n-äre Operatoren (der Operator ist ein Attribut, kein Text), Klammern, Funktionen, Grenzwerte, Akzente, Striche, Matrizen und ausgerichtete Arrays werden zugeordnet; alles Unbekannte behält seinen wörtlichen Text, statt zu verschwinden.
SmartArt	Die Zeichnung in `document.xml` enthält nur Beziehungs-IDs; jedes Wort des Diagramms steht in `word/diagrams/dataN.xml` unter einem eigenen Namespace, sodass ein Leser, der nach `a:blip` sucht, nichts findet und die Grafik ganz verwirft. Das Layout lässt sich in HTML nicht nachbilden, der Inhalt wird aber als Gliederung `.rte-imported-smartart` wiederhergestellt – ein Organigramm, das als Liste ankommt, ist brauchbar; eines, das als leere Fläche ankommt, ist ein Loch. Die Präsentations- und Verbindungspunkte von Word (`pres`, `parTrans`, `sibTrans`) tragen keinen Inhalt und werden übersprungen.
WMF/EMF-Bilder	Windows-Metadateien haben keine Form, die ein Browser darstellen kann, und lassen sich daher nicht einbetten. Statt spurlos zu verschwinden, hinterlässt jede einen benannten Platzhalter mit `data-source`, sodass der Leser weiß, dass dort eine Abbildung war und welche er im Original nachschlagen muss.
Zeichenformatierung	Farbe (`w:color`), Hervorhebung, Hoch- und Tiefstellung und Größe – `w:sz` ist in Halbpunkten angegeben, also wird 36 zu 18pt statt 36pt.
Struktur & Formatierung	Überschriften aus `w:pStyle`, Tabellen, Absatzausrichtung, fett, kursiv, unterstrichen, durchgestrichen, Tabulatoren und Zeilenumbrüche.

Markdown, HTML, reiner Text und das HTML-basierte .doc von Word werden genauso behandelt. Für alles darüber hinaus – oder um die Konvertierung über Ihren eigenen Dienst zu leiten – geben Sie config.documentImportResolver(file) an, das für jedes Format Vorrang hat.

Bekannte Grenzen – und zwar Grenzen der Form, nicht des Inhalts. Aus einer .docx wird jetzt nichts mehr stillschweigend verworfen. Was HTML nicht nachbilden kann, wird sichtbar vereinfacht und als solches gekennzeichnet: Textfelder kommen als Inhalt statt als schwebende Rahmen zurück (Browser-HTML hat keine Entsprechung zur absoluten Seitenverankerung von Word), SmartArt als Gliederung statt als gestaltete Grafik und WMF/EMF-Bilder als benannter Platzhalter. Formeln kommen als LaTeX an, das KaTeX oder MathJax auf der Seite braucht, um als Mathematik statt als Quelltext dargestellt zu werden. Das sind Lücken beim Import, nicht beim Export – die Tabelle oben zeigt, was heute den Hin- und Rückweg übersteht. Formeln werden als echte Schleife geprüft statt als zwei unabhängige Funktionen: Fünfzehn Formeln, nach OOXML exportiert und wieder importiert, kommen Byte für Byte identisch zurück, einschließlich der drei optisch identischen Unicode-Winkelklammern, die verschiedene Generatoren ausgeben.

Sicherheitsgrenze

Der Konverter ruft nie etwas über das Netzwerk ab. Eine URL in einem img-Element wird ignoriert, sofern der aufrufende Server nicht einen exakten Eintrag von URL zu Data-URI in imageMap mitliefert. Damit bleiben DNS, Weiterleitungen, private Adressen, Zugangsdaten und die Autorisierung von Mandanten außerhalb der Vertrauensgrenze des Konverters.

Bewusste Grenzen

Word ist seitenbasiert, Browser-HTML ist Fließlayout. Floats, CSS Grid, Filter, Skripte, Formulare, Animationen und beliebige Styles werden nicht übertragen.
Nur Standard-Kopf- und -Fußzeilen eines Abschnitts werden bereitgestellt; Varianten für die erste oder gerade Seiten und mehrere in HTML definierte Abschnitte erfordern eine anwendungsspezifische Vorlage.
Die automatisierte Testsuite prüft die erzeugten OOXML-Teile und -Beziehungen. Die visuelle Abnahme in Microsoft Word oder LibreOffice bleibt für Vorlagen mit eigenem Branding ein Schritt vor dem Release.