Communitygithub.com

DOCX-Erstellung, -Bearbeitung und -Analyse

Ein Skill zur Erstellung, Bearbeitung und Analyse von .docx-Dateien mit JavaScript- und Python-Werkzeugen.

Was ist DOCX-Erstellung, -Bearbeitung und -Analyse?

Dieser Skill befähigt AI-Agenten (wie Claude Code, Cursor oder Codex), umfassend mit .docx-Dateien zu arbeiten. Da eine .docx-Datei ein ZIP-Archiv mit XML-Dateien ist, bietet der Skill zwei Hauptpfade: Die Erstellung neuer Dokumente mit der 'docx'-Bibliothek in JavaScript und die Bearbeitung bestehender Dokumente durch Entpacken, direktes Editieren des XML und erneutes Packen. Der Skill enthält detaillierte Referenzen für alle gängigen Aufgaben wie Tabellen, Bilder, Kopf- und Fußzeilen, Verzeichnisse und mehr. Besonderer Wert wird auf die Einhaltung von Plattformstandards gelegt (z. B. Seitenränder, Schriftarten). Er wird über die integrierten Werkzeuge des Agenten (Edit-Tool, Terminal) sowie über bereitgestellte Python-Skripte (z. B. zum Entpacken, Packen, Validieren und für Kommentare) gesteuert.

Funktioniert mit✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add hankunpeng/skills

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht DOCX-Erstellung, -Bearbeitung und -Analyse?

Übersicht

Eine .docx-Datei ist ein ZIP-Archiv, das XML-Dateien enthält.

Kurzreferenz

AufgabeVorgehen
Inhalt lesen/analysierenmarkitdown oder entpacken für rohes XML
Neues Dokument erstellendocx-js verwenden – siehe „Neue Dokumente erstellen“ unten
Bestehendes Dokument bearbeitenEntpacken → 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):

PapierBreiteHöheInhaltsbreite (1"-Ränder)
US Letter12.24015.8409.360
A4 (Standard)11.90616.8389.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.DXA verwenden – niemals WidthType.PERCENTAGE (nicht kompatibel mit Google Docs)
  • Tabellenbreite muss der Summe von columnWidths entsprechen
  • Zellen-width muss der entsprechenden columnWidth entsprechen
  • Zellen-margins sind 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 als height übergeben und orientation: PageOrientation.LANDSCAPE setzen
  • Nie \n verwenden – separate Paragraph-Elemente nutzen
  • Nie Unicode-Aufzählungszeichen verwenden – LevelFormat.BULLET mit Nummerierungskonfiguration nutzen
  • PageBreak muss in Paragraph sein – alleinstehend erzeugt ungültiges XML
  • ImageRun benötigt type – immer png/jpg/etc. angeben
  • Tabellen-width immer mit DXA setzen – niemals WidthType.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.CLEAR verwenden – 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.
  • outlineLevel einfü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&#x2019;s ein Zitat: &#x201C;Hallo&#x201D;</w:t>
EntityZeichen
&#x2018;‘ (einfach links)
&#x2019;’ (einfach rechts / Apostroph)
&#x201C;“ (doppelt links)
&#x201D;” (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 &amp; und &#x2019;"
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.

Verwandte Skills