Was macht DOCX-Erstellung, -Bearbeitung und -Analyse?
Übersicht
Eine .docx-Datei ist ein ZIP-Archiv, das XML-Dateien enthält.
Kurzreferenz
| Aufgabe | Vorgehen |
|---|---|
| Inhalt lesen/analysieren | markitdown oder entpacken für rohes XML |
| Neues Dokument erstellen | docx-js verwenden – siehe „Neue Dokumente erstellen“ unten |
| Bestehendes Dokument bearbeiten | Entpacken → XML bearbeiten → neu packen – siehe „Bestehende Dokumente bearbeiten“ unten |
Inhalt lesen
# Textextraktion
markitdown dokument.docx > ausgabe.md
# Direkter XML-Zugriff
python scripts/office/unpack.py dokument.docx entpackt/
Änderungen nachverfolgen und übernehmen
Um ein sauberes Dokument mit allen übernommenen Änderungen zu erhalten:
python scripts/accept_changes.py eingabe.docx ausgabe.docx
Neue Dokumente erstellen
Erzeuge .docx-Dateien mit JavaScript und validiere sie anschließend. Installation: npm install -g docx
Setup
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun,
Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
InternalHyperlink, Bookmark, FootnoteReferenceRun, PositionalTab,
PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader,
TabStopType, TabStopPosition, Column, SectionType,
TableOfContents, HeadingLevel, BorderStyle, WidthType, ShadingType,
VerticalAlign, PageNumber, PageBreak } = require('docx');
const doc = new Document({ sections: [{ children: [/* Inhalt */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("dok.docx", buffer));
Validierung
Nach der Erstellung die Datei validieren. Bei einem Fehler entpacken, XML korrigieren und neu packen.
python scripts/office/validate.py dok.docx
Seitengröße
// WICHTIG: docx-js verwendet standardmäßig A4, nicht US Letter
// Für konsistente Ergebnisse immer die Seitengröße explizit setzen
sections: [{
properties: {
page: {
size: {
width: 12240, // 8,5 Zoll in DXA
height: 15840 // 11 Zoll in DXA
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1-Zoll-Ränder
}
},
children: [/* Inhalt */]
}]
Gängige Seitengrößen (DXA-Einheiten, 1440 DXA = 1 Zoll):
| Papier | Breite | Höhe | Inhaltsbreite (1"-Ränder) |
|---|---|---|---|
| US Letter | 12.240 | 15.840 | 9.360 |
| A4 (Standard) | 11.906 | 16.838 | 9.026 |
Querformat: docx-js tauscht Breite/Höhe intern; daher Hochformat-Maße übergeben und die Vertauschung zulassen:
size: {
width: 12240, // KURZE Kante als Breite übergeben
height: 15840, // LANGE Kante als Höhe übergeben
orientation: PageOrientation.LANDSCAPE // docx-js tauscht sie im XML
},
// Inhaltsbreite = 15840 - linker Rand - rechter Rand (nutzt die lange Kante)
Stile (Integrierte Überschriften überschreiben)
Verwende Arial als Standardschriftart (universell unterstützt). Titel aus Lesbarkeitsgründen schwarz halten.
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt Standard
paragraphStyles: [
// WICHTIG: Exakte IDs verwenden, um integrierte Stile zu überschreiben
{ id: "Heading1", name: "Überschrift 1", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 32, bold: true, font: "Arial" },
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel für TOC erforderlich
{ id: "Heading2", name: "Überschrift 2", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 28, bold: true, font: "Arial" },
paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
]
},
sections: [{
children: [
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Titel")] }),
]
}]
});
Listen (NIEMALS Unicode-Aufzählungszeichen verwenden)
// ❌ FALSCH - niemals manuelle Aufzählungszeichen einfügen
new Paragraph({ children: [new TextRun("• Punkt")] }) // SCHLECHT
new Paragraph({ children: [new TextRun("\u2022 Punkt")] }) // SCHLECHT
// ✅ RICHTIG - Nummerierungskonfiguration mit LevelFormat.BULLET verwenden
const doc = new Document({
numbering: {
config: [
{ reference: "aufzaehlungen",
levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "nummerierungen",
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
]
},
sections: [{
children: [
new Paragraph({ numbering: { reference: "aufzaehlungen", level: 0 },
children: [new TextRun("Aufzählungspunkt")] }),
new Paragraph({ numbering: { reference: "nummerierungen", level: 0 },
children: [new TextRun("Nummerierter Punkt")] }),
]
}]
});
// ⚠️ Jede Referenz erzeugt UNABHÄNGIGE Nummerierung
// Gleiche Referenz = Fortsetzung (1,2,3 dann 4,5,6)
// Unterschiedliche Referenz = Neustart (1,2,3 dann 1,2,3)
Tabellen
WICHTIG: Tabellen benötigen doppelte Breitenangaben – sowohl columnWidths an der Tabelle als auch width an jeder Zelle. Ohne beides werden Tabellen auf manchen Plattformen falsch dargestellt.
// WICHTIG: Tabellenbreite immer für konsistente Darstellung setzen
// WICHTIG: ShadingType.CLEAR (nicht SOLID) verwenden, um schwarze Hintergründe zu vermeiden
const border = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const borders = { top: border, bottom: border, left: border, right: border };
new Table({
width: { size: 9360, type: WidthType.DXA }, // Immer DXA verwenden (Prozentangaben brechen in Google Docs)
columnWidths: [4680, 4680], // Müssen in der Summe der Tabellenbreite entsprechen (DXA: 1440 = 1 Zoll)
rows: [
new TableRow({
children: [
new TableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // Auch an jeder Zelle setzen
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR, nicht SOLID
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Zellenabstand (intern, wird nicht zur Breite addiert)
children: [new Paragraph({ children: [new TextRun("Zelle")] })]
})
]
})
]
})
Tabellenbreite berechnen:
Immer WidthType.DXA verwenden – WidthType.PERCENTAGE bricht in Google Docs.
// Tabellenbreite = Summe der columnWidths = Inhaltsbreite
// US Letter mit 1"-Rändern: 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // Müssen in der Summe der Tabellenbreite entsprechen
Breitenregeln:
- Immer
WidthType.DXAverwenden – niemalsWidthType.PERCENTAGE(nicht kompatibel mit Google Docs) - Tabellenbreite muss der Summe von
columnWidthsentsprechen - Zellen-
widthmuss der entsprechendencolumnWidthentsprechen - Zellen-
marginssind interner Abstand; sie verkleinern den Inhaltsbereich und werden nicht zur Zellenbreite addiert - Für Tabellen in voller Breite: Inhaltsbreite verwenden (Seitenbreite minus linke und rechte Ränder)
Bilder
// WICHTIG: type-Parameter ist ERFORDERLICH
new Paragraph({
children: [new ImageRun({
type: "png", // Erforderlich: png, jpg, jpeg, gif, bmp, svg
data: fs.readFileSync("bild.png"),
transformation: { width: 200, height: 150 },
altText: { title: "Titel", description: "Beschreibung", name: "Name" } // Alle drei erforderlich
})]
})
Seitenumbrüche
// WICHTIG: PageBreak muss innerhalb eines Paragraph stehen
new Paragraph({ children: [new PageBreak()] })
// Oder pageBreakBefore verwenden
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Neue Seite")] })
Hyperlinks
// Externer Link
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "Hier klicken", style: "Hyperlink" })],
link: "https://example.com",
})]
})
// Interner Link (Lesezeichen + Verweis)
// 1. Lesezeichen am Ziel erstellen
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
new Bookmark({ id: "kapitel1", children: [new TextRun("Kapitel 1")] }),
]})
// 2. Darauf verlinken
new Paragraph({ children: [new InternalHyperlink({
children: [new TextRun({ text: "Siehe Kapitel 1", style: "Hyperlink" })],
anchor: "kapitel1",
})]})
Fußnoten
const doc = new Document({
footnotes: {
1: { children: [new Paragraph("Quelle: Jahresbericht 2024")] },
2: { children: [new Paragraph("Siehe Anhang für Methodik")] },
},
sections: [{
children: [new Paragraph({
children: [
new TextRun("Der Umsatz stieg um 15%"),
new FootnoteReferenceRun(1),
new TextRun(" unter Verwendung bereinigter Kennzahlen"),
new FootnoteReferenceRun(2),
],
})]
}]
});
Tabulatorstopps
// Text rechtsbündig in derselben Zeile ausrichten (z. B. Datum gegenüber einem Titel)
new Paragraph({
children: [
new TextRun("Firmenname"),
new TextRun("\tJanuar 2025"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// Punktfüller (z. B. wie im Inhaltsverzeichnis)
new Paragraph({
children: [
new TextRun("Einleitung"),
new TextRun({ children: [
new PositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
Mehrspaltige Layouts
// Gleich breite Spalten
sections: [{
properties: {
column: {
count: 2, // Anzahl der Spalten
space: 720, // Abstand zwischen den Spalten in DXA (720 = 0,5 Zoll)
equalWidth: true,
separate: true, // vertikale Linie zwischen den Spalten
},
},
children: [/* Inhalt fließt automatisch über die Spalten */]
}]
// Benutzerdefinierte Spaltenbreiten (equalWidth muss false sein)
sections: [{
properties: {
column: {
equalWidth: false,
children: [
new Column({ width: 5400, space: 720 }),
new Column({ width: 3240 }),
],
},
},
children: [/* Inhalt */]
}]
Erzwinge einen Spaltenumbruch mit einem neuen Abschnitt durch type: SectionType.NEXT_COLUMN.
Inhaltsverzeichnis
// WICHTIG: Überschriften MÜSSEN ausschließlich HeadingLevel verwenden – keine benutzerdefinierten Stile
new TableOfContents("Inhaltsverzeichnis", { hyperlink: true, headingStyleRange: "1-3" })
Kopf-/Fußzeilen
sections: [{
properties: {
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 Zoll
},
headers: {
default: new Header({ children: [new Paragraph({ children: [new TextRun("Kopfzeile")] })] })
},
footers: {
default: new Footer({ children: [new Paragraph({
children: [new TextRun("Seite "), new TextRun({ children: [PageNumber.CURRENT] })]
})] })
},
children: [/* Inhalt */]
}]
Kritische Regeln für docx-js
- Seitengröße explizit setzen – docx-js verwendet standardmäßig A4; für US-Dokumente US Letter (12240 x 15840 DXA) verwenden
- Querformat: Hochformat-Maße übergeben – docx-js tauscht Breite/Höhe intern; kurze Kante als
width, lange Kante alsheightübergeben undorientation: PageOrientation.LANDSCAPEsetzen - Nie
\nverwenden – separate Paragraph-Elemente nutzen - Nie Unicode-Aufzählungszeichen verwenden –
LevelFormat.BULLETmit Nummerierungskonfiguration nutzen - PageBreak muss in Paragraph sein – alleinstehend erzeugt ungültiges XML
- ImageRun benötigt
type– immer png/jpg/etc. angeben - Tabellen-
widthimmer mit DXA setzen – niemalsWidthType.PERCENTAGE(bricht in Google Docs) - Tabellen benötigen doppelte Breiten –
columnWidths-Array UND Zellen-width, beide müssen übereinstimmen - Tabellenbreite = Summe der columnWidths – bei DXA sicherstellen, dass sie exakt addieren
- Immer Zellenabstände hinzufügen –
margins: { top: 80, bottom: 80, left: 120, right: 120 }für lesbare Abstände verwenden ShadingType.CLEARverwenden – niemals SOLID für Tabellenschattierungen- Tabellen niemals als Trennlinien verwenden – Zellen haben eine Mindesthöhe und werden als leere Kästchen dargestellt (auch in Kopf-/Fußzeilen); stattdessen
border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }an einem Paragraph verwenden. Für zweispaltige Fußzeilen Tabulatorstopps nutzen (siehe Abschnitt Tabulatorstopps), keine Tabellen - TOC erfordert ausschließlich HeadingLevel – keine benutzerdefinierten Stile für Überschriftenabsätze
- Integrierte Stile überschreiben – exakte IDs verwenden: "Heading1", "Heading2" etc.
outlineLeveleinfügen – erforderlich für TOC (0 für H1, 1 für H2, etc.)
Bestehende Dokumente bearbeiten
Alle 3 Schritte der Reihe nach befolgen.
Schritt 1: Entpacken
python scripts/office/unpack.py dokument.docx entpackt/
Extrahiert XML, formatiert es lesbar, führt benachbarte Läufe zusammen und wandelt typografische Anführungszeichen in XML-Entities um (“ etc.), damit sie die Bearbeitung überstehen. Mit --merge-runs false kann das Zusammenführen der Läufe übersprungen werden.
Schritt 2: XML bearbeiten
Dateien in entpackt/word/ bearbeiten. Siehe XML-Referenz unten für Muster.
„Claude" als Autor verwenden für nachverfolgte Änderungen und Kommentare, es sei denn, der Benutzer wünscht explizit einen anderen Namen.
Das Edit-Tool direkt für Zeichenkettenersetzungen verwenden. Keine Python-Skripte schreiben. Skripte fügen unnötige Komplexität hinzu. Das Edit-Tool zeigt genau, was ersetzt wird.
WICHTIG: Typografische Anführungszeichen für neuen Inhalt verwenden. Wenn Text mit Apostrophen oder Anführungszeichen hinzugefügt wird, XML-Entities für typografische Anführungszeichen verwenden:
<!-- Diese Entities für professionelle Typografie verwenden -->
<w:t>Hier’s ein Zitat: “Hallo”</w:t>
| Entity | Zeichen |
|---|---|
‘ | ‘ (einfach links) |
’ | ’ (einfach rechts / Apostroph) |
“ | “ (doppelt links) |
” | ” (doppelt rechts) |
Kommentare hinzufügen: comment.py verwenden, um den Boilerplate-Code über mehrere XML-Dateien zu verwalten (Text muss vorab als XML escaped sein):
python scripts/comment.py entpackt/ 0 "Kommentartext mit & und ’"
python scripts/comment.py entpackt/ 1 "Antworttext" --parent 0 # Antwort auf Kommentar 0
python scripts/comment.py entpackt/ 0 "Text" --author "Benutzerdefinierter Autor" # benutzerdefinierter Autorenname
Dann Markierungen in document.xml hinzufügen (siehe Kommentare in der XML-Referenz).
Schritt 3: Packen
python scripts/office/pack.py entpackt/ ausgabe.docx --original dokument.docx
Validiert mit automatischer Reparatur, komprimiert XML und erstellt die endgültige .docx-Datei.