Création, édition et analyse de fichiers DOCX
Aperçu
Un fichier .docx est une archive ZIP contenant des fichiers XML.
Référence rapide
| Tâche | Approche |
|---|---|
| Lire/analyser le contenu | markitdown ou décompresser pour le XML brut |
| Créer un nouveau document | Utiliser docx-js - voir Création de nouveaux documents ci-dessous |
| Modifier un document existant | Décompresser → éditer le XML → recompresser - voir Modification de documents existants ci-dessous |
Lecture du contenu
# Extraction de texte
markitdown document.docx > output.md
# Accès brut au XML
python scripts/office/unpack.py document.docx unpacked/
Accepter les modifications suivies
Pour obtenir un document propre avec toutes les modifications suivies acceptées :
python scripts/accept_changes.py input.docx output.docx
Création de nouveaux documents
Générer des fichiers .docx avec JavaScript, puis valider. Installer : npm install -g docx
Configuration
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: [/* contenu */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer));
Validation
Après avoir créé le fichier, validez-le. Si la validation échoue, décompressez, corrigez le XML et recompressez.
python scripts/office/validate.py doc.docx
Taille de page
// CRITIQUE : docx-js utilise A4 par défaut, pas US Letter
// Toujours définir la taille de page explicitement pour des résultats cohérents
sections: [{
properties: {
page: {
size: {
width: 12240, // 8,5 pouces en DXA
height: 15840 // 11 pouces en DXA
},
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // Marges d'1 pouce
}
},
children: [/* contenu */]
}]
Tailles de page courantes (en unités DXA, 1440 DXA = 1 pouce) :
| Papier | Largeur | Hauteur | Largeur du contenu (marges d'1 pouce) |
|---|---|---|---|
| US Letter | 12 240 | 15 840 | 9 360 |
| A4 (par défaut) | 11 906 | 16 838 | 9 026 |
Orientation paysage : docx-js échange largeur/hauteur en interne, donc transmettez les dimensions portrait et laissez-le gérer l'échange :
size: {
width: 12240, // Transmettre le bord COURT comme largeur
height: 15840, // Transmettre le bord LONG comme hauteur
orientation: PageOrientation.LANDSCAPE // docx-js les échange dans le XML
},
// Largeur du contenu = 15840 - marge gauche - marge droite (utilise le bord long)
Styles (Remplacer les titres intégrés)
Utiliser Arial comme police par défaut (universellement prise en charge). Garder les titres en noir pour une meilleure lisibilité.
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt par défaut
paragraphStyles: [
// IMPORTANT : Utiliser des identifiants exacts pour remplacer les styles intégrés
{ id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 32, bold: true, font: "Arial" },
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel requis pour la TDM
{ id: "Heading2", name: "Heading 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("Titre")] }),
]
}]
});
Listes (NE JAMAIS utiliser de puces Unicode)
// ❌ INCORRECT - ne jamais insérer manuellement de caractères de puce
new Paragraph({ children: [new TextRun("• Élément")] }) // MAUVAIS
new Paragraph({ children: [new TextRun("\u2022 Élément")] }) // MAUVAIS
// ✅ CORRECT - utiliser la configuration de numérotation avec LevelFormat.BULLET
const doc = new Document({
numbering: {
config: [
{ reference: "puces",
levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "nombres",
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
]
},
sections: [{
children: [
new Paragraph({ numbering: { reference: "puces", level: 0 },
children: [new TextRun("Élément de liste à puces")] }),
new Paragraph({ numbering: { reference: "nombres", level: 0 },
children: [new TextRun("Élément numéroté")] }),
]
}]
});
// ⚠️ Chaque référence crée une numérotation INDÉPENDANTE
// Même référence = continue (1,2,3 puis 4,5,6)
// Référence différente = redémarre (1,2,3 puis 1,2,3)
Tableaux
CRITIQUE : Les tableaux nécessitent des largeurs doubles - définir à la fois columnWidths sur le tableau ET width sur chaque cellule. Sans les deux, les tableaux s'affichent incorrectement sur certaines plates-formes.
// CRITIQUE : Toujours définir la largeur du tableau pour un rendu cohérent
// CRITIQUE : Utiliser ShadingType.CLEAR (pas SOLID) pour éviter les arrière-plans noirs
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 }, // Toujours utiliser DXA (les pourcentages ne fonctionnent pas dans Google Docs)
columnWidths: [4680, 4680], // Doit totaliser la largeur du tableau (DXA : 1440 = 1 pouce)
rows: [
new TableRow({
children: [
new TableCell({
borders,
width: { size: 4680, type: WidthType.DXA }, // Également définir sur chaque cellule
shading: { fill: "D5E8F0", type: ShadingType.CLEAR }, // CLEAR pas SOLID
margins: { top: 80, bottom: 80, left: 120, right: 120 }, // Remplissage de cellule (interne, ne s'ajoute pas à la largeur)
children: [new Paragraph({ children: [new TextRun("Cellule")] })]
})
]
})
]
})
Calcul de la largeur du tableau :
Toujours utiliser WidthType.DXA — WidthType.PERCENTAGE ne fonctionne pas dans Google Docs.
// Largeur du tableau = somme des columnWidths = largeur du contenu
// US Letter avec marges d'1 pouce : 12240 - 2880 = 9360 DXA
width: { size: 9360, type: WidthType.DXA },
columnWidths: [7000, 2360] // Doit totaliser la largeur du tableau
Règles de largeur :
- Toujours utiliser
WidthType.DXA— jamaisWidthType.PERCENTAGE(incompatible avec Google Docs) - La largeur du tableau doit être égale à la somme des
columnWidths - La
widthde la cellule doit correspondre à lacolumnWidthcorrespondante - Les
marginsde la cellule sont un remplissage interne ; elles réduisent la zone de contenu et ne s'ajoutent pas à la largeur de la cellule - Pour les tableaux pleine largeur : utiliser la largeur du contenu (largeur de page moins les marges gauche et droite)
Images
// CRITIQUE : le paramètre type est OBLIGATOIRE
new Paragraph({
children: [new ImageRun({
type: "png", // Obligatoire : png, jpg, jpeg, gif, bmp, svg
data: fs.readFileSync("image.png"),
transformation: { width: 200, height: 150 },
altText: { title: "Titre", description: "Desc", name: "Nom" } // Les trois sont obligatoires
})]
})
Sauts de page
// CRITIQUE : PageBreak doit être à l'intérieur d'un Paragraphe
new Paragraph({ children: [new PageBreak()] })
// Ou utiliser pageBreakBefore
new Paragraph({ pageBreakBefore: true, children: [new TextRun("Nouvelle page")] })
Hyperliens
// Lien externe
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "Cliquez ici", style: "Hyperlink" })],
link: "https://example.com",
})]
})
// Lien interne (signet + référence)
// 1. Créer un signet à la destination
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [
new Bookmark({ id: "chapitre1", children: [new TextRun("Chapitre 1")] }),
]})
// 2. Lien vers celui-ci
new Paragraph({ children: [new InternalHyperlink({
children: [new TextRun({ text: "Voir le Chapitre 1", style: "Hyperlink" })],
anchor: "chapitre1",
})]})
Notes de bas de page
const doc = new Document({
footnotes: {
1: { children: [new Paragraph("Source : Rapport annuel 2024")] },
2: { children: [new Paragraph("Voir l'annexe pour la méthodologie")] },
},
sections: [{
children: [new Paragraph({
children: [
new TextRun("Le chiffre d'affaires a augmenté de 15 %"),
new FootnoteReferenceRun(1),
new TextRun(" en utilisant des mesures ajustées"),
new FootnoteReferenceRun(2),
],
})]
}]
});
Taquets de tabulation
// Aligner le texte à droite sur la même ligne (par exemple, date en face d'un titre)
new Paragraph({
children: [
new TextRun("Nom de l'entreprise"),
new TextRun("\tJanvier 2025"),
],
tabStops: [{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }],
})
// Points de suite (style TDM)
new Paragraph({
children: [
new TextRun("Introduction"),
new TextRun({ children: [
new PositionalTab({
alignment: PositionalTabAlignment.RIGHT,
relativeTo: PositionalTabRelativeTo.MARGIN,
leader: PositionalTabLeader.DOT,
}),
"3",
]}),
],
})
Mises en page multi-colonnes
// Colonnes de largeur égale
sections: [{
properties: {
column: {
count: 2, // nombre de colonnes
space: 720, // espace entre les colonnes en DXA (720 = 0,5 pouce)
equalWidth: true,
separate: true, // ligne verticale entre les colonnes
},
},
children: [/* le contenu s'écoule naturellement entre les colonnes */]
}]
// Colonnes de largeur personnalisée (equalWidth doit être false)
sections: [{
properties: {
column: {
equalWidth: false,
children: [
new Column({ width: 5400, space: 720 }),
new Column({ width: 3240 }),
],
},
},
children: [/* contenu */]
}]
Forcer un saut de colonne avec une nouvelle section utilisant type: SectionType.NEXT_COLUMN.
Table des matières
// CRITIQUE : Les titres doivent utiliser UNIQUEMENT HeadingLevel - pas de styles personnalisés
new TableOfContents("Table des matières", { hyperlink: true, headingStyleRange: "1-3" })
En-têtes/Pieds de page
sections: [{
properties: {
page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } // 1440 = 1 pouce
},
headers: {
default: new Header({ children: [new Paragraph({ children: [new TextRun("En-tête")] })] })
},
footers: {
default: new Footer({ children: [new Paragraph({
children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })]
})] })
},
children: [/* contenu */]
}]
Règles critiques pour docx-js
- Définir la taille de page explicitement - docx-js utilise A4 par défaut ; utiliser US Letter (12240 x 15840 DXA) pour les documents américains
- Paysage : transmettre les dimensions portrait - docx-js échange largeur/hauteur en interne ; transmettre le bord court comme
width, le bord long commeheight, et définirorientation: PageOrientation.LANDSCAPE - Ne jamais utiliser
\n- utiliser des éléments Paragraphe séparés - Ne jamais utiliser de puces Unicode - utiliser
LevelFormat.BULLETavec la configuration de numérotation - PageBreak doit être dans un Paragraphe - autonome crée un XML invalide
- ImageRun nécessite
type- toujours spécifier png/jpg/etc. - Toujours définir la
widthdu tableau avec DXA - ne jamais utiliserWidthType.PERCENTAGE(ne fonctionne pas dans Google Docs) - Les tableaux nécessitent des largeurs doubles - tableau
columnWidthsETwidthde la cellule, les deux doivent correspondre - Largeur du tableau = somme des columnWidths - pour DXA, s'assurer qu'elles s'additionnent exactement
- Toujours ajouter les marges de cellule - utiliser
margins: { top: 80, bottom: 80, left: 120, right: 120 }pour un remplissage lisible - Utiliser
ShadingType.CLEAR- jamais SOLID pour l'ombrage du tableau - Ne jamais utiliser de tableaux comme séparateurs/règles - les cellules ont une hauteur minimale et s'affichent comme des boîtes vides (y compris dans les en-têtes/pieds de page) ; utiliser
border: { bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E75B6", space: 1 } }sur un Paragraphe à la place. Pour les pieds de page à deux colonnes, utiliser les taquets de tabulation (voir la section Taquets de tabulation), pas de tableaux - TDM nécessite uniquement HeadingLevel - pas de styles personnalisés sur les paragraphes de titre
- Remplacer les styles intégrés - utiliser des identifiants exacts : "Heading1", "Heading2", etc.
- Inclure
outlineLevel- requis pour la TDM (0 pour H1, 1 pour H2, etc.)
Modification de documents existants
Suivre les 3 étapes dans l'ordre.
Étape 1 : Décompresser
python scripts/office/unpack.py document.docx unpacked/
Extrait le XML, l'imprime joliment, fusionne les passages adjacents et convertit les guillemets intelligents en entités XML (“ etc.) afin qu'ils survivent à l'édition. Utiliser --merge-runs false pour ignorer la fusion de passages.
Étape 2 : Modifier le XML
Modifier les fichiers dans unpacked/word/. Voir la Référence XML ci-dessous pour les modèles.
Utiliser "Claude" comme auteur pour les modifications suivies et les commentaires, sauf si l'utilisateur demande explicitement d'utiliser un autre nom.
Utiliser directement l'outil Edit pour le remplacement de chaînes. Ne pas écrire de scripts Python. Les scripts introduisent une complexité inutile. L'outil Edit montre exactement ce qui est remplacé.
CRITIQUE : Utiliser les guillemets intelligents pour le nouveau contenu. Lors de l'ajout de texte avec des apostrophes ou des guillemets, utiliser des entités XML pour produire des guillemets intelligents :
<!-- Utiliser ces entités pour une typographie professionnelle -->
<w:t>Voici’une citation : “Bonjour”</w:t>
| Entité | Caractère |
|---|---|
‘ | ' (guillemet simple gauche) |
’ | ' (guillemet simple droite / apostrophe) |
“ | " (guillemet double gauche) |
” | " (guillemet double droite) |
Ajout de commentaires : Utiliser comment.py pour gérer le code passe-partout sur plusieurs fichiers XML (le texte doit être pré-échappé en XML) :
python scripts/comment.py unpacked/ 0 "Texte du commentaire avec & et ’"
python scripts/comment.py unpacked/ 1 "Texte de réponse" --parent 0 # répondre au commentaire 0
python scripts/comment.py unpacked/ 0 "Texte" --author "Auteur personnalisé" # nom d'auteur personnalisé
Ensuite, ajouter des marqueurs dans document.xml (voir Commentaires dans la Référence XML).
Étape 3 : Recompresser
python scripts/office/pack.py unpacked/ output.docx --original document.docx
Valide avec réparation automatique, condense le XML et crée le fichier de sortie. Le paramètre --original préserve les métadonnées et les propriétés du document original.
Référence XML
Ajouter du contenu
<w:p>
<w:pPr>
<w:pStyle w:val="Heading1"/>
</w:pPr>
<w:r>
<w:rPr/>
<w:t>Nouveau titre</w:t>
</w:r>
</w:p>
Modifications suivies (insertion)
<w:ins w:id="1" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:r>
<w:rPr/>
<w:t>Nouveau texte</w:t>
</w:r>
</w:ins>
Modifications suivies (suppression)
<w:del w:id="2" w:author="Claude" w:date="2025-01-01T00:00:00Z">
<w:r>
<w:delText xml:space="preserve">Ancien texte</w:delText>
</w:r>
</w:del>
Commentaires
Ajouter d'abord les commentaires avec comment.py, puis les marqueurs dans document.xml :
<w:commentRangeStart w:id="0"/>
<w:r><w:t>Texte commenté</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:rPr/><w:commentReference w:id="0"/></w:r>
Images (encodées en base64 stockées dans le XML)
<w:drawing>
<wp:inline distT="0" distB="0" distL="0" distR="0">
<wp:extent cx="1828800" cy="1371600"/>
<wp:effectExtent l="0" t="0" r="0" b="0"/>
<wp:docPr id="1" name="Image1" descr="Description"/>
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:nvPicPr>
<pic:cNvPr id="1" name="Image1" descr="Description"/>
<pic:cNvPicPr/>
</pic:nvPicPr>
<pic:blipFill>
<a:blip r:embed="rId1"/>
<a:stretch><a:fillRect/></a:stretch>
</pic:blipFill>
<pic:spPr>
<a:xfrm><a:off x="0" y="0"/><a:ext cx="1828800" cy="1371600"/></a:xfrm>
<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
</pic:spPr>
</pic:pic>
</a:graphicData>
</a:graphic>
</wp:inline>
</w:drawing>
Le fichier image séparé est stocké dans media/image1.png. Les dimensions sont en EMU (914400 EMU = 1 pouce). Convertir comme suit : pouces * 914400, cm * 360000.
Splice de contenu (fusionner des documents complets)
Pour combiner plusieurs documents .docx en un seul document :
python scripts/office/splice.py --input "input1.docx" --input "input2.docx" --output "merged.docx"
L'ordre suit les options --input.
Cela gère la fusion correcte des relations et des espaces de noms.
Dépannage
| Problème | Solution |
|---|---|
| Validation échoue | Décompresser → vérifier le XML → corriger les balises non fermées |
| Les tableaux semblables à boîtes vides | Utilisé à mauvais escient comme séparateur ; utiliser plutôt border sur un Paragraphe |
| Google Docs affiche mal le tableau | Vérifier que la largeur utilise WidthType.DXA (pas PERCENTAGE) |
| Les images ne s'affichent pas | Vérifier que type est défini et que les données binaires sont valides |
| La TDM est vide | Vérifier que les titres utilisent HeadingLevel AVEC outlineLevel |
| Les listes à puces sont des caractères Unicode | Remplacer par LevelFormat.BULLET avec configuration de numérotation |
| Les notes de bas de page manquent | Ajouter les références avec FootnoteReferenceRun(numéro) dans le texte |