SVG

Dessinez des formes, du texte et des images aux coordonnées précises — diagrammes, graphiques, icônes, sceaux, éléments de décoration. Vous les créez comme vous le connaissez déjà : en SVG. Les noms d'éléments et les propriétés reflètent SVG — cx/cy/r, x1/y1/x2/y2, d, fill, stroke, viewBox — de sorte qu'un extrait SVG se transfère avec une traduction minimale. Tout s'affiche en vecteur natif en PDF et DOCX — même JSON, même résultat, zéro image matricielle.

Exemple en direct

Un vrai diagramme d'architecture : un hexagone pour le service de périphérie, des rectangles arrondis pour le calcul, des cylindres ellipse-sur-rectangle pour les bases de données, des connecteurs codés par couleur. Ouvrez l'onglet Template pour voir le JSON.

Output

Try in Playground →

Template

Data

Le bloc svg

Un graphique SVG est un élément Content avec un bloc svg — un viewBox plus une liste de children. Il se lit comme un élément racine <svg> :

{
  "svg": {
    "viewBox": [0, 0, 24, 24],
    "children": [
      { "path":   { "d": "M12 2 C8 2 5 5 5 9 c0 5 7 13 7 13 s7-8 7-13 c0-4-3-7-7-7 Z", "style": "pin" } },
      { "circle": { "cx": 12, "cy": 9, "r": 2.5, "style": "hole" } }
    ]
  }
}

Propriété	Type	Par défaut	Description
viewBox	[W, H] ou [minX, minY, W, H]	auto à partir des enfants	Étendue des coordonnées sous forme de tableau numérique — la même convention que les widths des tables / colonnes. Omettez pour dériver la boîte serrée à partir des enfants (courbes comprises).
width	number	échelle du viewBox	Largeur d'affichage en points. Le viewBox reste l'espace de coordonnées des enfants ; width met le graphique à cette taille. Omettez pour un rendu à 1 unité = 1 point.
height	number	dérivée du ratio	Hauteur d'affichage en points. Indiquez width ou height pour une mise à l'échelle uniforme (l'autre suit le ratio du viewBox), ou les deux.
children	array	—	Éléments de dessin (voir ci-dessous).

Coller une vraie icône ? Gardez ses données d et son viewBox tels quels, convertissez la chaîne viewBox en tableau, et ajoutez width pour la taille voulue — p. ex. un glyphe 0 0 1024 1024 avec "width": 24 s'affiche en icône de 24 pt. Aucun calcul de coordonnées.

Chaque enfant est { "<élément>": { …props } } — un élément de dessin nommé, exactement comme SVG imbrique les éléments dans <svg>. Chaque élément porte une référence style vers document.styles pour son fill / stroke / etc.

Les coordonnées sont relatives à la boîte, origine en haut à gauche — x augmente vers la droite, y vers le bas. Un viewBox à 4 nombres ([minX, minY, W, H]) décale l'origine comme le fait SVG, de sorte que des coordonnées auteur négatives tombent dans la boîte.

Gardez les coordonnées locales. Le graphique est sa propre boîte de coordonnées — n'y utilisez jamais de positions absolues de page. Avec viewBox omis, la boîte est dérivée des enfants : un seul y de la taille d'une page gonfle la boîte dérivée et le graphique entier rétrécit vers rien. Positionnez le bloc sur la page comme tout autre élément de contenu ; positionnez les enfants dans la boîte.

Centrer le bloc

Un bloc svg occupe sa propre boîte et ignore les marges et le textAlign des styles de paragraphe. Pour centrer (ou aligner à droite) un graphique dans la largeur de contenu, donnez au viewBox la pleine largeur de contenu et décalez les enfants avec un translate de g :

{
  "svg": {
    "viewBox": [512, 160],
    "children": [
      { "g": { "translate": [176, 0], "children": [ { "circle": { "cx": 80, "cy": 80, "r": 78, "style": "seal" } } ] } }
    ]
  }
}

(512 − 160) / 2 = 176 centre un graphique de 160 unités dans une boîte de 512 unités ; un translate de 352 l'aligne à droite.

Éléments

Chaque élément s'affiche de manière identique en PDF et DOCX — même JSON, même résultat.

Output

Try in Playground →

Template

Data

Le vocabulaire est du SVG standard plus quelques commodités DocPayload :

Catégorie	Éléments
Primitives SVG	rect, circle, ellipse, line, polygon, path	SVG standard.
Contenu SVG	text, textPath, image	SVG standard.
Groupement SVG	g, use	SVG standard — grouper sous une transformation ; instancier un symbole réutilisable.
Raccourcis de formes (extension)	arc, triangle, diamond, pentagon, hexagon, octagon, plus, parallelogram, trapezoid, rightArrow, leftArrow, upArrow, downArrow, chevron	Formes de commodité que SVG n'exprime qu'avec des points polygon calculés à la main ou des arcs path. Chacune s'adapte à une boîte width × height que vous fournissez ; les sommets sont dérivés pour vous.
Code-barres (extension)	barcode	Un générateur de code-barres au moment du rendu — aucun équivalent SVG. Encode une charge utile (souvent liée à $data) en vecteur natif.

Vocabulaire SVG + extensions DocPayload. Tout ce qui figure dans les trois premières lignes est du SVG standard. Les raccourcis de formes et barcode sont des ajouts DocPayload superposés — ils vivent aux côtés des éléments SVG dans les mêmes children, de sorte que vous ne quittez jamais le modèle SVG pour les atteindre. Utilisez path / polygon quand vous voulez du SVG strict ; recourez aux raccourcis et à barcode quand ils vous épargnent l'arithmétique.

Les éléments path / textPath acceptent les chaînes SVG d brutes, ce qui en fait les primitives les plus flexibles — tout ce que vous pouvez dessiner en SVG (courbes de Bézier, arcs, chemins composés, ornements décoratifs) se transfère directement. Voir le tutoriel Galerie de motifs pour une référence complète des compositions décoratives (mandala, rayonnement, clé grecque, Lissajous, guilloché).

Éléments de dessin

Chaque élément est { "<nom>": { …props } }. Chaque élément porte une référence style vers document.styles.

Primitives géométriques

Rectangle

{ "rect": { "x": 100, "y": 100, "width": 150, "height": 80, "rx": 6, "ry": 6, "style": "card" } }

rx / ry sont des rayons de coin optionnels — omettez-les pour des coins carrés.

Cercle

{ "circle": { "cx": 200, "cy": 100, "r": 30, "style": "node" } }

Ellipse

{ "ellipse": { "cx": 200, "cy": 100, "rx": 55, "ry": 6, "style": "dbCap" } }

Raccourcis de formes (extension)

triangle, diamond, pentagon, hexagon, octagon, plus, parallelogram, trapezoid. Tous prennent x, y, width, height ; les sommets s'adaptent à cette boîte. (En SVG strict, ce serait un <polygon> avec des points calculés à la main.)

{ "triangle":      { "x": 0,   "y": 0,   "width": 80, "height": 80, "style": "shape" } }
{ "diamond":       { "x": 110, "y": 0,   "width": 80, "height": 80, "style": "shape" } }
{ "pentagon":      { "x": 220, "y": 0,   "width": 80, "height": 80, "style": "shape" } }
{ "hexagon":       { "x": 330, "y": 0,   "width": 80, "height": 80, "style": "shape" } }
{ "octagon":       { "x": 0,   "y": 100, "width": 80, "height": 80, "style": "shape" } }
{ "plus":          { "x": 110, "y": 100, "width": 80, "height": 80, "style": "shape" } }
{ "parallelogram": { "x": 220, "y": 100, "width": 80, "height": 80, "style": "shape" } }
{ "trapezoid":     { "x": 330, "y": 100, "width": 80, "height": 80, "style": "shape" } }

Les flèches directionnelles suivent la même règle — rightArrow, leftArrow, upArrow, downArrow, chevron. L'orientation est encodée dans le nom ; le moteur de rendu ajuste les mathématiques des sommets.

{ "rightArrow": { "x": 0,   "y": 0, "width": 90, "height": 60 } }
{ "leftArrow":  { "x": 110, "y": 0, "width": 90, "height": 60 } }
{ "upArrow":    { "x": 220, "y": 0, "width": 60, "height": 90 } }
{ "downArrow":  { "x": 290, "y": 0, "width": 60, "height": 90 } }
{ "chevron":    { "x": 360, "y": 0, "width": 80, "height": 60 } }

Groupe g

Regroupe des enfants sous une transformation partagée et un style par défaut en cascade, exactement comme le <g> de SVG. Les enfants sont dessinés dans les coordonnées locales du groupe.

Propriété	Type	Description
children	tableau	Éléments enfants, tout le vocabulaire de cette page — les groupes s'imbriquent.
translate	[tx, ty]	Décalage en points.
rotate	nombre	Rotation en degrés.
skew	[x] ou [x, y]	Inclinaison en degrés.
scale	[sx, sy]	Facteurs d'échelle — non négatifs ; le miroir via une échelle négative n'est pas supporté.
transform	[a, b, c, d, e, f]	Matrice affine brute, appliquée en dernier.
style	chaîne	Style nommé en cascade vers les enfants qui n'en déclarent pas.

Les transformations se composent dans l'ordre SVG : translate → rotate → skew → scale, puis la matrice brute.

Note DOCX. Les groupes Word portent translate, scale et rotate (pivotant sur le centre du groupe). skew et la matrice transform brute ne sont pas exprimables sur un groupe Word et y sont ignorés — le PDF les honore intégralement. Quand un graphique doit correspondre dans les deux formats, composez uniquement avec translate / rotate / scale.

Nœuds étiquetés (regrouper une forme + étiquette)

Un nœud de diagramme — une forme avec une étiquette centrée — est un groupe g : la forme plus un text centré dans la même boîte. Les enfants se dessinent dans les coordonnées locales du groupe, donc translate place le nœud et le style du groupe se propage en cascade aux enfants qui ne déclarent pas le leur (ici, la forme hérite du remplissage du nœud tandis que l'étiquette conserve son propre style de texte blanc).

{ "g": {
    "translate": [30, 85],
    "style": "node",
    "children": [
      { "hexagon": { "x": 0, "y": 0, "width": 110, "height": 50 } },
      { "text": { "x": 0, "y": 20.5, "width": 110, "text": "API Gateway", "style": "nodeLabel" } }
    ]
} }

Centrez l'étiquette verticalement avec y = height/2 − fontSize/2. Quand le même nœud réapparaît à travers un diagramme (le cas courant), définissez-le une fois comme un symbole et use le avec params par instance — voir order-lifecycle-states.json et org-chart.json.

Exemple en direct — architecture-diagram.json (un nœud de périphérie hexagone en tant que g, plus quatre symboles arch-node instanciés via use).

Polygone

Polygone fermé défini par N points. Utile pour les étoiles, les badges, les formes de diagramme de flux personnalisées. Auto-fermé (dernier sommet revenant au premier).

{
  "polygon": {
    "points": [
      { "x": 100, "y": 10 },
      { "x": 140, "y": 40 },
      { "x": 125, "y": 90 },
      { "x": 75,  "y": 90 },
      { "x": 60,  "y": 40 }
    ],
    "style": "star"
  }
}

Lignes et arcs

Ligne

{ "line": { "x1": 50, "y1": 50, "x2": 200, "y2": 150, "style": "connector" } }

Arc (extension)

Balayage de startAngle à endAngle (degrés, CCW depuis +x) autour de (cx, cy). Un raccourci pour un path avec une commande A quand vous préférez donner un centre et des angles plutôt que calculer les extrémités de l'arc.

{ "arc": { "cx": 200, "cy": 200, "r": 60, "startAngle": 0, "endAngle": 180, "style": "arc" } }

Chemins et texte sur chemin

Chemin

Données SVG path arbitraires via l'attribut d. Supporte les commandes SVG standard : M/m (moveto), L/l (lineto), H/h / V/v (horizontal/vertical lineto), C/c / S/s (courbe de Bézier cubique + lisse), Q/q / T/t (courbe de Bézier quadratique + lisse), A/a (arc elliptique), Z/z (fermer le chemin). Traits et/ou remplissages basés sur les propriétés de couleur fournies par le style (stroke → trait, fill → remplissage, les deux → remplissage+trait).

{ "path": { "d": "M 0 50 Q 100 0 200 50 T 400 50", "style": "wave" } }

Cercle complet comme deux arcs semi-circulaires :

{ "path": { "d": "M 100 6 A 94 94 0 0 1 100 194 A 94 94 0 0 1 100 6", "style": "outerRing" } }

textPath

Coule du texte le long d'un chemin avec rotation par glyphe. Le chemin lui-même n'est pas dessiné — appairez avec un élément path utilisant le même d si vous voulez une courbe visible aussi.

Propriété	Type	Description
d	string	Données SVG path (même syntaxe que path).
text	string	Texte à couler ; supporte les Codes courts ([b], [i], [u], [s], [sub], [sup], [mark], [color], [fontsize], [caps], [font, Family], …) et le multi-ligne via [br] / [br, n] — le texte svg ne se replie jamais, les sauts explicites sont donc les seules limites de ligne et chaque ligne s'aligne indépendamment. Façonné au moment du rendu — les scripts complexes se joignent/empilent correctement (voir Texte multi-script et sceaux).
alignment	enum	start (par défaut) · middle · end — ancre le texte le long du chemin.
startOffset	number	Distance en points depuis le début du chemin avant le premier glyphe.
side	enum	above (par défaut) — ligne de base sur le chemin ; below — le glyphe pend sous le chemin.
style	string	Style de texte.

{
  "textPath": {
    "d": "M 24 100 A 76 76 0 0 1 176 100",
    "text": "OFFICIAL · [color, #7A1F2E]STATE CORPORATION COMMISSION[/color]",
    "alignment": "middle",
    "style": "sealTopText"
  }
}

Un texte plus large que son chemin n'est jamais tronqué. Sur un arc circulaire avec alignment: middle — le cas des anneaux de sceau — la chaîne entière est réduite uniformément pour tenir sur l'arc ; partout ailleurs le texte se prolonge au-delà des extrémités du chemin à sa taille naturelle. Les deux formats concordent, et un diagnostic de rendu signale le dépassement dans tous les cas. Dimensionnez néanmoins vos arcs généreusement : une légende ajustée reste plus lisible quand la réduction est légère.

L'arc peut se placer à n'importe quel angle — d est libre : un arc couvrant n'importe quelle portion de cercle y place son texte (alignment: middle centre la chaîne sur le milieu de l'arc). Les demi-cercles à extrémités horizontales des exemples de sceaux sont une convention, pas une contrainte.

Contenu

Texte

{ "text": { "x": 150, "y": 200, "text": "Section header", "style": "label" } }

Quand width est défini, (x, y) est le coin supérieur gauche d'une boîte de texte et le textAlign du style centre/aligne à droite le texte dans cette boîte. Sans width, l'ancre est le pivot d'alignement — l'alignement au centre pivote sur (x, y), l'alignement à droite se termine à cet endroit.

{ "text": { "x": 0, "y": 10, "width": 180, "text": "EDGE", "style": "laneHeader" } }

Ancrage vertical — baseline. Par défaut, y est le haut du texte. Définissez baseline pour changer ce que y signifie verticalement (c'est un champ de l'élément, aux côtés de x/y) :

baseline	y est…
(omis)	le haut du texte (défaut DocPayload)
middle / central	le centre vertical
alphabetic	la ligne de base (défaut de SVG lui-même)
hanging / text-before-edge	le haut
text-after-edge / ideographic	le bas

baseline: "middle" est la façon propre de centrer verticalement une étiquette dans une forme : écrivez y à mi-hauteur de la boîte au lieu de calculer y = hauteur/2 − fontSize/2. Le PDF le place exactement à partir des métriques de police ; Word l'approxime via le décalage de la boîte de texte.

{ "text": { "x": 55, "y": 25, "baseline": "middle", "text": "42", "style": "gaugeValue" } }

Définissez fontFamily sur le style de texte pour utiliser une police personnalisée intégrée, et changez de police au milieu de la chaîne avec le Code court [font, Family] — à la fois text et textPath sont façonnés au moment du rendu (voir Texte multi-script et sceaux).

Image

{ "image": { "x": 50, "y": 30, "width": 100, "height": 40, "href": "images/logos/acme.png" } }

Code-barres (extension)

Placez n'importe quelle symbologie de code-barres prise en charge aux coordonnées exactes — PDF417, DataMatrix, QR, Code128, Code39, MaxiCode et les codes spécialisés 2D. Il n'y a aucun équivalent SVG : l'encodeur s'exécute au moment du rendu et émet du vecteur natif, donc la valeur codée peut être une référence $data.*.

{
  "barcode": {
    "x": 80, "y": 56,
    "width": 40, "height": 40,
    "spec": { "type": "datamatrix", "code": "$data.credential.payload" }
  }
}

Propriété	Type	Description
x, y	number	Coin supérieur gauche du code-barres dans les coordonnées locales.
width, height	number	Dimensions de rendu en points. Pour les codes 2D carrés, définissez les deux égaux. Omettez pour utiliser les valeurs par défaut par symbologie.
spec.type	string	Symbologie — datamatrix, qrcode, pdf417, code128, code39, aztec, maxicode, microqr, rmqr, micropdf417, dotcode, hanxin, code16k, codablockf, ultracode, gridmatrix, upnqr et tous les types linéaires 1D. Voir Symbologies.
spec.code	string	La charge utile à encoder. Supporte les références $data.* et $item.*.

Ceci est la primitive de code-barres positionnée — distincte du Code court [barcode, …] qui s'affiche en ligne avec le flux de texte. Utilisez cette forme quand vous avez besoin du code-barres à un emplacement précis aux côtés d'autres éléments (le centre d'un sceau, un coin d'un formulaire, une barre latérale de bord).

Exemples en direct — official-seal.json (enregistrement de vérification PDF417 à côté des numéros de contrôle), graduation-certificate.json et achievement-certificate.json (DataMatrix au centre visuel d'un sceau académique), stock-certificate.json (badge de vérification DataMatrix), void-check.json (filigrane Code128 monté sur bord).

Texte multi-script et sceaux

text et textPath sont façonnés avec le même moteur qui façonne les paragraphes coulants — au moment du rendu. L'arabe et l'hébreu se joignent dans leurs formes contextuelles et s'affichent de droite à gauche, le Devanagari construit des conjonctifs, le thaï empile les marques de voyelle et de ton, et le chinois/japonais/coréen s'affichent à partir d'une famille CJK. Choisissez la police avec fontFamily sur le style de texte, et changez de polices par passage avec le Code court [font, Family]. Chaque anneau textPath peut donc porter un script différent — ce qui rend un sceau multi-script possible.

Exemples en direct — world-languages-proclamation.json (un sceau portant l'arabe, le latin, le grec et le Devanagari sur des anneaux textPath concentriques autour d'un caractère CJK) et multilingual-device-guide.json (anneaux extérieurs latin + CJK, anneaux intérieurs Devanagari + thaï autour d'un caractère CJK gras). Voir Polices personnalisées pour les détails de façonnage et de sous-ensemble.

Le text multi-script est sans configuration : une ligne mêlant latin et arabe, hébreu, indien ou thaï se découpe en tranches par écriture, chacune routée vers une police qui la couvre, et les segments droite-à-gauche — nombres compris — s'ordonnent correctement sans aucune déclaration. Gardez chaque textPath sur une seule écriture : le texte sur un chemin est façonné selon les règles d'une seule écriture — donnez à chaque anneau la sienne, exactement comme le font les exemples de sceaux.

Styles SVG

Les éléments SVG utilisent un schéma de propriété différent des styles de paragraphe. Utilisez les clés ci-dessous — color/backgroundColor/border sont des propriétés de paragraphe et seront silencieusement ignorées sur les éléments de dessin.

La nomenclature s'aligne avec les attributs de présentation SVG. Mêmes sémantiques que SVG, camelCase de style JSON.

L'état de dessin est séquentiel. Un trait, un remplissage, un motif de tirets ou une opacité définis pour un enfant persistent pour les enfants suivants jusqu'à être remplacés — comme l'héritage SVG, aplati dans l'ordre du document. Quand un élément ultérieur ne doit pas hériter, définissez la propriété explicitement : strokeDasharray: [0] revient au trait plein, opacity: 1 à l'opacité totale.

Propriété	S'applique à	Description
fill	formes	Remplissage intérieur — une couleur, ou un objet dégradé.
stroke	formes, lignes, chemins	Couleur de bordure / ligne / trait.
strokeWidth	formes, lignes, chemins	Largeur du trait en points.
strokeDasharray	formes, lignes, chemins	Motif de tiret en tant que tableau numérique : [on, off] pour tiret simple, [a, b, c, d, …] pour tiret-point, [0.5, 2.5] associé à strokeLinecap: "round" pour pointillé. Utilisez [0] ou [] pour réinitialiser explicitement à solide — l'état de dessin est collant, donc un motif de tiret défini plus tôt dans le flux persiste jusqu'à ce qu'il soit remplacé.
strokeDashoffset	chemins	Décalage de départ dans le motif de tiret (par défaut 0).
strokeLinecap	formes, lignes, chemins	butt (par défaut) / round / square — forme de terminaison de ligne. Combiné avec strokeDasharray, round transforme les minuscules segments activés en points ronds au lieu de carrés de pixels.
strokeLinejoin	chemins	miter (par défaut) / round / bevel — style de jointure d'angle aux sommets des polylignes.
strokeMiterlimit	chemins	Flottant positif — contrôle la longueur d'une pointe d'onglet avant d'être coupée à un biseau.
dropShadow	formes, chemins	Objet { dx, dy, blur, color, opacity } — ombre portée derrière la forme (dy positif la fait descendre). Relief de carte, de sceau, de badge. Seules les parties peintes projettent une ombre : une forme sans remplissage projette l'ombre de son contour. La douceur du bord diffère légèrement entre les deux formats.
opacity	tous	0.0–1.0 transparence.
fillOpacity	formes	0.0–1.0 transparence du remplissage uniquement. Remplace opacity pour le remplissage : un remplissage translucide sous un trait opaque (l'idiome classique de la boîte de surbrillance).
strokeOpacity	formes, lignes, chemins	0.0–1.0 transparence du trait uniquement. Remplace opacity pour le trait.
vectorEffect	formes, lignes, chemins	non-scaling-stroke garde la largeur du trait constante quand la forme est à l'intérieur d'un symbole mis à l'échelle : un filet reste un filet quelle que soit la taille de rendu du use, au lieu de s'épaissir avec la géométrie.
color	texte, textPath	Couleur de remplissage du texte.
fontSize	texte, textPath	Taille du texte en points.
fontWeight / fontStyle	texte, textPath	Poids (bold, normal, 100…900) et style (italic, normal).
fontFamily	texte, textPath	Famille de polices pour les polices personnalisées intégrées.
letterSpacing	texte, textPath	Suivi inter-caractères en points (positif élargit, négatif resserre).
textAlign	texte	left / center / right — le domaine est le width du texte quand défini, le point d'ancrage sinon.
textRenderingMode	texte, textPath	fill (par défaut) / stroke / fillstroke / invisible / fillclip / strokeclip / fillstrokeclip / clip.
skew	chemins	[skewX] ou [skewX, skewY] en degrés — applique une transformation d'inclinaison 2D.
transform	chemins	Matrice affine à 6 éléments [a, b, c, d, e, f] — ConcatMatrix brut.
rotate	formes	Rotation en degrés autour du centre de la forme.

{
  "styles": {
    "card":       { "fill": "#1E40AF", "stroke": "#1E3A8A", "strokeWidth": 0.5 },
    "cardLabel":  { "fontSize": 9, "fontWeight": "bold", "color": "#FFFFFF", "textAlign": "center" },
    "connector":  { "stroke": "#16A34A", "strokeWidth": 1.5 }
  }
}

Formes cliquables

Rendez une forme dessinée cliquable — un bouton d'appel à l'action, un logo pointant vers votre site, un nœud de diagramme ouvrant une référence — avec link sur l'élément (la forme aplatie de l'enveloppe SVG <a href>) :

{ "rect": { "x": 0, "y": 8, "width": 160, "height": 42, "rx": 8, "style": "cta",
            "link": "https://docpayload.com/docs" } }

link est disponible sur rect, circle, ellipse, polygon, path, text et image (où il complète href, la source de l'image). Toute la forme devient la zone cliquable, dans les deux formats (pour polygon/path, la boîte englobante de la forme). Seules les URL absolues http, https et mailto sont acceptées — tout le reste est refusé avec un diagnostic et la forme est rendue sans le lien.

Dans un en-tête ou un pied de page, la forme est toujours dessinée, mais les liens n'y sont pas cliquables en PDF. Placez les graphiques cliquables dans le corps.

Rogner une image sur une forme

Photos de collaborateurs circulaires, cadres façonnés, hublots de couverture — posez clip sur l'élément image avec une géométrie en ligne (mêmes coordonnées viewBox que l'image) :

{ "image": { "x": 150, "y": 0, "width": 120, "height": 120, "href": "images/photos/portrait.jpg",
             "clip": { "circle": { "cx": 210, "cy": 60, "r": 58 } } } }

La forme de rognage est l'une de circle, ellipse, rect ou path (contour arbitraire via des données de chemin SVG), positionnée dans les mêmes coordonnées viewBox que l'image elle-même. Dessinez un anneau ou un cadre après l'image rognée pour habiller le bord. Les deux formats rognent exactement sur le même contour ; gardez le rognage dans la boîte de l'image.

Ajuster le texte à un emplacement fixe — textLength sur l'élément text force le texte rendu à une largeur exacte (unités du viewBox) : un nom de longueur variable remplissant toujours le même emplacement de badge. lengthAdjust choisit le mécanisme : spacing (par défaut — les espaces entre glyphes s'étirent ou se resserrent) ou spacingAndGlyphs (les glyphes se mettent aussi à l'échelle, pour un rendu condensé/étendu). Mono-ligne uniquement — ignoré avec un diagnostic quand le texte contient [br].

{ "text": { "x": 4, "y": 15, "baseline": "middle", "text": "MAXIMILIENNE DE LONGCHAMP",
            "style": "name", "textLength": 172, "lengthAdjust": "spacingAndGlyphs" } }

Ajustement des proportions — preserveAspectRatio sur l'élément image contrôle la rencontre entre une photo et une boîte de proportions différentes : meet la met en boîte aux lettres (image entière visible, centrée), slice couvre la boîte (centrée, débordement rogné). Omettez-le pour étirer. Préférez un meet/slice explicite dès que les proportions diffèrent — c'est aussi le seul mode garanti identique entre les deux formats de sortie.

Marqueurs — pointes de flèche sur lignes et polylignes

Chaque connecteur, légende et ligne de cote a besoin d'une pointe de flèche — déclarez-la sur l'élément au lieu de calculer des polygones à la main :

{ "line": { "x1": 100, "y1": 27, "x2": 218, "y2": 27,
            "markerEnd": { "shape": "triangle", "size": 7 }, "style": "connector" } }

• line prend markerStart / markerEnd ; polyline ajoute markerMid (un marqueur par sommet intérieur — points de données sur un tracé).
• shape vaut triangle (pointe de flèche, pointe sur le sommet), diamond ou circle (centré sur le sommet) ; size est la longueur/le diamètre en unités du viewBox (6 par défaut).
• Le marqueur se remplit avec la couleur stroke du style de l'élément — aucun style séparé nécessaire.
• markerStart pointe vers l'arrière le long de la ligne : markerStart + markerEnd sur une même ligne donne une flèche de cote à deux têtes.

Les deux formats de sortie dessinent des têtes identiques. Pour une tête personnalisée au-delà des trois intégrées, composez un symbole réutilisable.

Remplissages en dégradé

fill accepte aussi un objet dégradé — linéaire ou radial — rendu en ombrage vectoriel natif dans les deux formats :

{
  "styles": {
    "ribbon": { "fill": { "linearGradient": { "angle": 90, "stops": [
      { "offset": 0, "color": "#0F766E" },
      { "offset": 1, "color": "#134E4A" }
    ] } } },
    "glow": { "fill": { "radialGradient": { "stops": [
      { "offset": 0, "color": "#FDE68A" },
      { "offset": 0.6, "color": "#F59E0B" },
      { "offset": 1, "color": "#B45309" }
    ] } } }
  }
}

• linearGradient — angle en degrés, sens horaire depuis gauche→droite : 0 court →, 90 court ↓, 135 court ↙. stops est une liste ordonnée de { offset, color } où offset est une fraction 0–1 le long du dégradé et color prend le vocabulaire hexadécimal/nom habituel. Deux arrêts minimum ; ajoutez-en pour des rubans multi-bandes.
• radialGradient — rayonne depuis le centre de la forme (offset: 0) vers ses coins (offset: 1). Même forme de stops.

Les dégradés se projettent sur la boîte englobante de la forme elle-même : un même style nommé teinte indifféremment un rect, un cercle, un path ou un polygone — et chaque forme d'un groupe reçoit sa propre étendue de dégradé. Se combine librement avec stroke (le contour reste une couleur unie) et fillOpacity. Un dégradé couvrant plusieurs formes séparées d'un seul lavis n'est pas exprimable — fusionnez-les en un seul path, ou donnez à chaque forme son propre dégradé.

Liaison de données dans le SVG

Les références $data.* / $item.* se résolvent dans un bloc svg dans les emplacements de valeur : text.text, textPath.text, image.href et barcode.spec.code — y compris dans les groupes g imbriqués. La géométrie et les valeurs de style ne sont pas liées aux données ; pour rendre dynamique la position ou la taille d'une instance, déclarez-la comme symbole et passez x / y / width / height / rotate via use.params.

Symboles et réutilisation — use

Dessinez un graphique une fois, instanciez-le plusieurs fois. Un symbole est un document dont le contenu est un seul graphique SVG ; un élément use l'estampe dans un autre graphique dans une boîte de destination, le mise à l'échelle à partir du viewBox du symbole et en liant les données par instance — exactement comme le <use> de SVG.

Déclaration d'un symbole

Un symbole est un fichier de document ordinaire avec un handle metadata.name et une charge utile SVG. Le name est ce que les auteurs référencent — il est indépendant du nom du fichier et du dossier.

{
  "component": {
    "metadata": { "name": "quality-seal" },
    "styles": {
      "sealOuter": { "stroke": "#10243E", "strokeWidth": 2 },
      "sealGrade": { "fontSize": 46, "fontWeight": "bold", "color": "#10243E", "textAlign": "center" }
    },
    "content": [
      {
        "svg": {
          "viewBox": [150, 150],
          "children": [
            { "circle": { "cx": 75, "cy": 75, "r": 72, "style": "sealOuter" } },
            { "text": { "x": 0, "y": 45, "width": 150, "text": "$data.grade", "style": "sealGrade" } }
          ]
        }
      }
    ]
  }
}

$data.grade est un placeholder rempli par instance (voir Liaison de données). Les styles nommés du symbole voyagent avec lui — ils se résolvent dans quel que soit le document qui le use.

Instanciation avec use

À l'intérieur de n'importe quel graphique SVG, un élément use nomme le symbole et donne une boîte de destination. width/height mettent à l'échelle le symbole à partir de son viewBox ; params fournit les valeurs de cette instance.

{
  "svg": {
    "viewBox": [472, 175],
    "children": [
      { "use": { "name": "quality-seal", "x": 16,  "y": 12, "width": 150, "height": 150, "params": { "grade": "A" } } },
      { "use": { "name": "quality-seal", "x": 206, "y": 27, "width": 120, "height": 120, "params": { "grade": "B" } } },
      { "use": { "name": "quality-seal", "x": 372, "y": 39, "width": 100, "height": 100, "params": { "grade": "A+" } } }
    ]
  }
}

Une définition, trois tailles, trois notes — pas de géométrie dupliquée. Les anneaux, le texte et les formes imbriquées s'échellent en tant qu'unité.

Output

Try in Playground →

Template

Data

Champ use	Signification
name	Le metadata.name du symbole (le handle que les auteurs écrivent).
id	Épingle GUID optionnelle ; gagne sur name quand les deux sont présents.
x / y	Coin supérieur gauche de destination, dans les coordonnées du graphique hôte.
width / height	Taille de destination ; l'échelle est dérivée par rapport au viewBox du symbole.
params	Valeurs par instance liées aux placeholders $data.* du symbole. Peut aussi porter x/y/width/height/rotate pour rendre la géométrie de ce use dynamique — une valeur ici gagne sur le champ littéral du même nom.
rotate / skew / transform	Transformations optionnelles appliquées à l'instance (degrés / degrés / matrice 6 éléments).
style	Style nommé en cascade vers les formes de l'instance qui ne déclarent rien.

Les transformations se composent dans l'ordre SVG (translate → rotate → skew → scale, puis la matrice transform brute). Les symboles peuvent use d'autres symboles ; l'imbrication est limitée en profondeur avec une garde de cycle.

Note DOCX. Dans la sortie Word, un use devient un groupe imbriqué portant translate, scale et rotate. Les transformations skew et raw-matrix ne sont pas exprimables sur un groupe Word et sont supprimées (le PDF les honore dans leur intégralité), et un groupe pivoté pivote sur son centre plutôt que sur son coin supérieur gauche.

Galerie de motifs — chemins, courbes et textPath

Un deuxième exemple en direct exerçant l'extrémité plus décorative de l'API : données SVG path, courbes de Bézier quadratiques et cubiques, arcs, textPath (texte coulé le long d'une courbe), formes polygon et compositions se chevauchant. Utile comme référence lors de la création de sceaux, de bordures ornementales, d'illustrations mathématiques/géométriques ou de n'importe quoi où le langage de mise en page est « placer ces courbes exactement ici ».

Output

Try in Playground →

Template

Data

Quand quelque chose ne se dessine pas

Des données de chemin malformées, une image introuvable, une famille de police non déclarée ou du texte dans une écriture qu'aucune police ne couvre dégradent tous poliment : l'élément est ignoré et le rendu continue. Activez les diagnostics de rendu pour voir chaque défaillance nommée dans le document, en marqueur sous l'élément concerné et dans l'appendice de fin de document.

Prochaines étapes

• Filigranes — superpositions de texte/image translucides qui se répètent sur les pages.
• Tableaux — mises en page tabulaires qui coulent avec les paragraphes.
• Colonnes — mises en page de flux multi-colonnes.