Contrat OOXML en direct

Fidélité et sécurité DOCX

Le point de terminaison d’export Next.js génère localement un package WordprocessingML natif. Cette matrice est liée au test de fidélité au niveau du package qui tourne dans le dépôt ; elle ne prétend pas que n’importe quel CSS de navigateur a un équivalent Word exact. Deux constructions ont leur propre article : les équations qui survivent à un aller-retour dans Word et ce que contient réellement un .docx.

Correspondances testées

Domaine	Sortie DOCX native
Structure du document	Titres, paragraphes, citations, listes à puces et listes décimales imbriquées, tableaux à disposition fixe
Mise en forme en ligne	Gras, italique, souligné, barré, code, police et taille, couleur du texte et de l’arrière-plan, indice et exposant
Disposition des paragraphes	Alignement, marges, interligne, retrait de première ligne, page-break-before et sauts de page explicites
Mise en page	Letter ou A4, portrait ou paysage, marges bornées, en-têtes et pieds de page par défaut, champs de page courante et de nombre total de pages
Tableaux	Grille DXA exacte, lignes d’en-tête répétées, fusion de colonnes, fusion de lignes, trame de cellule et alignement vertical
Sémantique de relecture	Insertions, suppressions, commentaires, notes de bas de page et notes de fin DOCX natifs
Équations	LaTeX converti en OMML natif — fractions, indices et exposants, radicaux, opérateurs n-aires, délimiteurs, fonctions, limites, accents, barres et cadres ; modifiables dans l’éditeur d’équations de Word, et non sous forme d’image
Liens et médias	Liens HTTP/HTTPS/mailto ; URI data PNG, JPEG, GIF et BMP ; table d’images de confiance résolue par le serveur

Contrat de requête

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,..." }
}

Les marges sont exprimées en vingtièmes de point (twips) et bornées entre 360 et 2880. La requête est plafonnée à 1 MiB. Une table d’images accepte au plus huit clés HTTP(S), uniquement des valeurs data d’image, et 768 KiB décodés au total.

Conventions HTML sémantiques

<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">

Importer du DOCX

L’import s’exécute entièrement dans le navigateur, sans bibliothèque ni aller-retour avec le serveur. Un .docx est un ZIP de XML : le répertoire central du ZIP est lu directement, et DecompressionStream("deflate-raw") se charge de la décompression. Rien n’est envoyé nulle part.

Élément importé	Comment, et ce que perd un convertisseur naïf
URL des liens	`w:hyperlink` ne porte qu’un `r:id` ; l’adresse se trouve dans `word/_rels/document.xml.rels`. Résolue — sans cela, chaque lien est importé comme texte brut et l’URL est perdue.
Images	`w:drawing` → `a:blip` → `word/media/*`, intégrées sous forme d’URI data. Définissez `documentImportImages: false` pour les ignorer dans les fichiers riches en images.
Listes numérotées ou à puces	`document.xml` stocke toutes les listes de façon identique ; seul `word/numbering.xml` les distingue. Ce fichier est lu : les listes numérotées restent donc des `<ol>` au lieu de devenir des listes à puces.
Imbrication des listes	`w:ilvl` produit une vraie imbrication, et la sous-liste est placée à l’intérieur de son `<li>` parent pour que le balisage soit valide.
Notes de bas de page et de fin	Word conserve le corps des notes dans des parties séparées, `word/footnotes.xml` et `word/endnotes.xml` ; `document.xml` ne contient qu’un identifiant. Toutes sont lues et reconstruites sous forme de notes vivantes — insérez-en une au-dessus d’une note importée, et tout se renumérote. Les deux parties partagent un schéma mais pas un nom d’élément (`w:footnote` ou `w:endnote`) : un analyseur écrit pour l’un ne renvoie silencieusement rien pour l’autre. Les entrées de séparateur de Word sont ignorées.
Zones de texte	Le contenu d’une zone de texte est imbriqué six niveaux sous le run (`w:pict` → `v:shape` → `v:textbox` → `w:txbxContent`) : un convertisseur qui ne lit que les enfants directs en perd chaque mot. Il est récupéré sous forme de bloc `.rte-imported-textbox` dans l’ordre du document, avec ses paragraphes et tableaux intacts. Un bloc `mc:AlternateContent` porte deux fois la même zone — une version DrawingML et un repli VML — et une seule est émise.
Suivi des modifications et commentaires	`w:ins` et `w:del` sont importés en `<ins>`/`<del>` avec auteur et date — les mêmes conventions que celles qu’émet l’export, si bien que le balisage de relecture fait l’aller-retour. Le texte supprimé se trouve dans `w:delText`, et non dans `w:t`. Les plages de commentaires deviennent des spans `data-comment`, dont le corps est tiré de `word/comments.xml`.
Équations	Word stocke les équations sous forme d’arbre `m:oMath` dans son propre espace de noms math, intercalé entre les runs — un convertisseur qui parcourt les éléments `w:r` ne le voit jamais, et l’équation disparaît alors que la phrase qui l’entoure s’importe correctement. Elles sont traduites en LaTeX et émises sous forme de span `rte-math-inline` propre à l’éditeur : elles sont donc modifiables dans la boîte de dialogue mathématique et s’affichent avec le moteur de rendu chargé par la page. Fractions, indices et exposants, radicaux, opérateurs n-aires (l’opérateur est un attribut, pas du texte), délimiteurs, fonctions, limites, accents, barres, matrices et tableaux alignés sont pris en charge ; tout élément non reconnu conserve son texte littéral au lieu de disparaître.
SmartArt	Le dessin dans `document.xml` ne contient que des identifiants de relations ; chaque mot du diagramme se trouve dans `word/diagrams/dataN.xml`, sous un espace de noms distinct : un lecteur qui cherche `a:blip` ne trouve rien et abandonne entièrement le graphique. La disposition ne peut pas être reproduite en HTML, mais le contenu est récupéré sous forme de plan `.rte-imported-smartart` — un organigramme importé sous forme de liste est utilisable ; un organigramme importé sous forme d’espace vide est un trou. Les points de présentation et de connexion de Word (`pres`, `parTrans`, `sibTrans`) ne portent aucun contenu et sont ignorés.
Images WMF/EMF	Les métafichiers Windows n’ont aucune forme affichable par un navigateur : ils ne peuvent donc pas être intégrés. Au lieu de disparaître sans laisser de trace, chacun laisse un espace réservé nommé portant `data-source`, pour que le lecteur sache qu’une figure se trouvait là et laquelle consulter dans l’original.
Mise en forme des caractères	Couleur (`w:color`), surlignage, exposant/indice et taille — `w:sz` est en demi-points : 36 devient donc 18pt et non 36pt.
Structure et mise en forme	Titres issus de `w:pStyle`, tableaux, alignement des paragraphes, gras, italique, souligné, barré, tabulations et sauts de ligne.

Le Markdown, le HTML, le texte brut et le .doc de Word au format HTML sont traités de la même façon. Pour tout ce qui va au-delà — ou pour faire passer la conversion par votre propre service —, fournissez config.documentImportResolver(file), qui a la priorité pour tous les formats.

Limites connues — et ce sont des limites de forme, pas de contenu. Plus rien dans un .docx n’est abandonné silencieusement. Ce que le HTML ne peut pas reproduire se dégrade de façon visible et le signale : les zones de texte reviennent sous forme de contenu plutôt que de cadres flottants (le HTML des navigateurs n’a pas d’équivalent de l’ancrage absolu sur la page de Word), le SmartArt sous forme de plan plutôt que de graphique mis en page, et les images WMF/EMF sous forme d’espace réservé nommé. Les équations arrivent en LaTeX, qui nécessite KaTeX ou MathJax sur la page pour s’afficher en notation mathématique plutôt qu’en source. Ce sont des lacunes de l’import, pas de l’export — le tableau ci-dessus couvre ce qui fait l’aller-retour aujourd’hui. Les équations sont vérifiées comme une véritable boucle, et non comme deux fonctionnalités indépendantes : quinze formules exportées en OOXML puis réimportées reviennent identiques à l’octet près, y compris les trois chevrons Unicode visuellement identiques qu’émettent différents générateurs.

Frontière de sécurité

Le convertisseur n’effectue jamais de requête réseau. Une URL dans un élément img est ignorée, sauf si le serveur appelant fournit dans imageMap une entrée exacte associant cette URL à une URI data. Cela laisse le DNS, les redirections, les adresses privées, les identifiants et l’autorisation des locataires en dehors de la frontière de confiance du convertisseur.

Limites voulues

Word est paginé et le HTML des navigateurs est en disposition fluide. Les flottants, la grille CSS, les filtres, les scripts, les formulaires, les animations et les styles arbitraires ne sont pas traduits.
Seuls les en-têtes et pieds de page de section par défaut sont exposés ; les variantes première page / pages paires et les sections multiples définies en HTML nécessitent un modèle propre à l’application.
La suite automatisée inspecte les parties et les relations OOXML générées. La validation visuelle dans Microsoft Word ou LibreOffice reste une étape de publication pour les modèles à l’image de marque.