Tableaux

Les tableaux organisent le contenu en lignes et colonnes. Chaque cellule accepte n'importe quel nœud de contenu — paragraphes, en-têtes, listes, colonnes, images, canevas, codes-barres, voire même des tableaux imbriqués — suivant la sémantique de contenu de flux HTML5 <td>.

Galerie des cas limites

L'exemple ci-dessous parcourt tous les cas limites courants en un seul endroit — largeurs automatiques, largeurs proportionnelles, poids de flottaison, décalages nombre-colonnes/longueur-largeurs, longueurs de lignes variables, cellules vides, colspan/rowspan, imbrication et renvoi à la ligne de contenu long. Consultez-le avant de lire le reste si vous voulez simplement voir comment les tableaux se comportent.

Output
Template
Data

Try in Playground →

Structure de base

{
  "table": {
    "widths": [3, 2, 2],
    "rows": [
      [{ "p": "Column 1" }, { "p": "Column 2" }, { "p": "Column 3" }],
      [{ "p": "Row 2, Col 1" }, { "p": "Row 2, Col 2" }, { "p": "Row 2, Col 3" }]
    ]
  }
}

Propriétés

Propriété	Type	Obligatoire	Description
`widths`	number[]	Oui	Proportions relatives de la largeur des colonnes
`rows`	array[]	Oui	Tableau de lignes, chaque ligne étant un tableau d'éléments de contenu de cellule

Largeurs des colonnes

Le tableau widths définit les proportions relatives des colonnes, non les valeurs en pixels absolues. La largeur de page disponible est divisée selon ces ratios.

"widths": [1, 1, 1]

Trois colonnes de largeur égale.

"widths": [3, 1, 1]

La première colonne est trois fois plus large que la deuxième et la troisième.

"widths": [4, 1, 1, 1]

Quatre colonnes où la première occupe environ 57 % de la largeur.

Lignes

Chaque ligne est un tableau d'éléments de contenu. Le nombre d'éléments dans chaque ligne doit correspondre à la longueur du tableau widths.

Types de cellules

Chaque cellule d'une ligne est un élément de contenu. Les tableaux supportent trois types de cellules pour une clarté sémantique :

Type	Objectif	Exemple
`th`	Cellule d'en-tête de tableau — généralement en gras avec un fond sombre	`{ "th": "Product" }`
`td`	Cellule de données de tableau — contenu régulier	`{ "td": "$12,500" }`
`p`	Paragraphe général — fonctionne aussi comme cellule, plus flexible	`{ "p": "[b]Bold text[/b]" }`

Les trois types acceptent la même propriété style et les balises de formatage inline. Utilisez th et td pour la structure sémantique, et p lorsque vous avez besoin de codes courts comme les images ou les codes-barres à l'intérieur des cellules.

Cellules d'en-tête (`th`)

[
  { "th": "Product", "style": "th" },
  { "th": "Qty", "style": "th" },
  { "th": "Price", "style": "th" }
]

Cellules de données (`td`)

[
  { "td": "Cloud Platform License", "style": "td" },
  { "td": "5", "style": "td" },
  { "td": "$2,400", "style": "td" }
]

Codes courts dans les cellules

Tous les types de cellules (th, td, p, h1–h5) supportent la gamme complète des codes courts — images, codes-barres, gras, couleur, etc. :

[
  { "th": "[image, /assets/logo.png, 60|20] Company", "style": "th" },
  { "td": "[barcode, qrcode, SF-20260330, 50|50]", "style": "td" },
  { "p": "[color, #27AE60][b]Active[/b][/color]" }
]

Cellules de liste

[
  { "p": "Features" },
  {
    "ul": {
      "li": [
        { "p": "Real-time tracking" },
        { "p": "Multi-carrier support" }
      ]
    }
  }
]

Style de tableau

Appliquez un style nommé au conteneur de tableau lui-même (séparé des styles de cellule). Cela contrôle les propriétés au niveau du tableau comme la bordure :

{
  "table": {
    "style": "borderless",
    "widths": [1, 1],
    "rows": [...]
  }
}

Avec le style défini comme :

"borderless": { "border": "none" }

Style des cellules du tableau

Appliquez des styles nommés aux éléments de cellule individuels pour contrôler le formatage.

Style de la ligne d'en-tête

{
  "document": {
    "styles": {
      "tableHeader": {
        "fontSize": 10,
        "fontWeight": "bold",
        "color": "#FFFFFF",
        "backgroundColor": "#2D3A4A",
        "padding": 6
      },
      "tableCell": {
        "fontSize": 9,
        "color": "#333333",
        "padding": 4,
        "borderBottom": "0.5pt solid #E0E0E0"
      }
    },
    "content": [
      {
        "table": {
          "widths": [3, 2, 2],
          "rows": [
            [
              { "p": "Route", "style": "tableHeader" },
              { "p": "Carrier", "style": "tableHeader" },
              { "p": "Transit Time", "style": "tableHeader" }
            ],
            [
              { "p": "Dakar - Accra", "style": "tableCell" },
              { "p": "ShipForge Express", "style": "tableCell" },
              { "p": "3-5 days", "style": "tableCell" }
            ],
            [
              { "p": "Lagos - Nairobi", "style": "tableCell" },
              { "p": "Pan-Africa Freight", "style": "tableCell" },
              { "p": "5-7 days", "style": "tableCell" }
            ]
          ]
        }
      }
    ]
  }
}

Fusion de cellules — `colspan` et `rowspan`

À ne pas confondre avec [col, N]

colspan fusionne plusieurs colonnes de tableau en une cellule — comme HTML <td colspan="3">. [col, N] est le code court qui divise un paragraphe en N segments horizontaux pondérés à l'intérieur d'une seule cellule (ou n'importe où dans le corps du texte). Opérations inverses. Consultez Codes courts de mise en page pour les diviseurs de segment. L'exemple §11 de la galerie des cas limites montre les deux utilisés ensemble — colspan: 4 fusionne une ligne complète, et [col, 3][col, 1] divise son intérieur en une étiquette et un badge d'état aligné à droite.

Ceux-ci suivent le modèle de tableau HTML : colspan et rowspan sont des attributs de la cellule elle-même, pas des entrées dans un bloc de style. Ils contrôlent la structure (combien de colonnes ou de lignes la cellule occupe), donc ils sont placés sur la cellule à côté du contenu de la cellule — la même position que HTML les place sur <td> et <th>.

{ "p": "FY Totals", "style": "totals", "colspan": 3 }

La valeur par défaut est 1 (pas de fusion). N'importe où en dehors d'un contexte de cellule de tableau, ils sont inactifs — mettre colspan sur un paragraphe de haut niveau n'a aucun effet.

Colspan — fusion entre colonnes

{
  "table": {
    "widths": [1, 1, 1, 1],
    "rows": [
      [
        { "p": "Region", "style": "th" },
        { "p": "Q1",     "style": "th" },
        { "p": "Q2",     "style": "th" },
        { "p": "Q3",     "style": "th" }
      ],
      [
        { "p": "North",  "style": "td" },
        { "p": "182",    "style": "tdNum" },
        { "p": "201",    "style": "tdNum" },
        { "p": "218",    "style": "tdNum" }
      ],
      [
        { "p": "FY Totals", "style": "tdTotal", "colspan": 3 },
        { "p": "601",       "style": "tdNumTotal" }
      ]
    ]
  }
}

L'étiquette totales occupe les trois premières colonnes ; le total numérique remplit la quatrième.

Rowspan — fusion entre lignes

Quand une cellule s'étend sur plusieurs lignes, les lignes suivantes ne répètent pas cette colonne. Elles ne déclarent que les cellules restantes de la ligne ; le moteur les place dans les colonnes à droite de la cellule fusionnée.

{
  "table": {
    "widths": [1, 3],
    "rows": [
      [{ "p": "Status",  "style": "th" }, { "p": "Description", "style": "th" }],
      [{ "p": "ACTIVE",  "style": "tdStatus", "rowspan": 3 }, { "p": "First entry — top of the merged group.",  "style": "td" }],
      [                                                       { "p": "Second entry — same status, no repeat label.", "style": "td" }],
      [                                                       { "p": "Third entry — closes out the merged group.",   "style": "td" }]
    ]
  }
}

Dans DOCX, le moteur insère automatiquement les cellules de continuation de fusion verticale sous la cellule fusionnée, de sorte que le document Word résultant s'ouvre avec une fusion propre — vous ne devez pas créer vous-même de cellules d'espace réservé.

Les deux à la fois

Un banneau d'en-tête à la fois large et tall :

{ "p": "QUARTERLY REVIEW · Q1 2026", "style": "banner", "colspan": 4, "rowspan": 2 }

Pourquoi pas dans le bloc de style ?

colspan / rowspan sont structurels — ils décident de l'empreinte de grille de la cellule, non de son apparence. Les placer sur la cellule garde le bloc de style concentré sur le style visuel (et permet qu'un style unique soit réutilisé pour les cellules fusionnées et non fusionnées sans duplication). Cela reflète HTML, où colspan="3" est un attribut sur <td>, pas une propriété CSS.

Tableaux imbriqués

Une cellule peut contenir un autre tableau, permettant des mises en page complexes.

{
  "table": {
    "widths": [1, 1],
    "rows": [
      [
        { "p": "[b]Sender[/b]" },
        { "p": "[b]Recipient[/b]" }
      ],
      [
        {
          "table": {
            "widths": [1, 2],
            "rows": [
              [{ "p": "Name:" }, { "p": "ShipForge Ltd" }],
              [{ "p": "City:" }, { "p": "London, UK" }]
            ]
          }
        },
        {
          "table": {
            "widths": [1, 2],
            "rows": [
              [{ "p": "Name:" }, { "p": "Meridian Logistics" }],
              [{ "p": "City:" }, { "p": "Accra, Ghana" }]
            ]
          }
        }
      ]
    ]
  }
}

Utilisation du formatage inline dans les cellules

Les cellules supportent la gamme complète des balises de formatage inline.

[
  { "p": "[color, #27AE60][b]Delivered[/b][/color]" },
  { "p": "[color, #E74C3C][b]Delayed[/b][/color]" },
  { "p": "[color, #F39C12][b]In Transit[/b][/color]" }
]

Tableaux pilotés par les données

Les tableaux peuvent être remplis dynamiquement à partir de données en utilisant source et map. Consultez Source de données pour les détails complets.

Liaison de données de base

{
  "table": {
    "source": "$data.items",
    "map": ["description", "qty", "amount"],
    "widths": [3, 1, 1],
    "rows": [
      [
        { "th": "Description", "style": "th" },
        { "th": "Qty", "style": "th" },
        { "th": "Amount", "style": "th" }
      ]
    ]
  }
}

Le chemin source pointe vers un tableau dans votre objet de données. Le tableau map spécifie quelles clés de chaque objet deviennent des valeurs de cellule, mappées de gauche à droite aux colonnes. La ligne d'en-tête est préservée ; les lignes de données sont ajoutées après.

Modèles `$item.*` dans la carte

Au lieu de simples noms de clés, les entrées map peuvent être des chaînes de modèle qui composent des valeurs à partir de plusieurs champs :

{
  "table": {
    "source": "$data.lineItems",
    "map": ["$item.sku", "$item.description", "$item.qty × $item.unit", "CAD $item.subtotal"],
    "widths": [2, 3, 2, 2],
    "rows": [
      [
        { "th": "SKU", "style": "th" },
        { "th": "Description", "style": "th" },
        { "th": "Quantity", "style": "th" },
        { "th": "Subtotal", "style": "th" }
      ]
    ]
  }
}

La troisième colonne compose "$item.qty × $item.unit" en valeurs comme "12 × box". La quatrième colonne ajoute un préfixe de devise : "CAD 1,450.00".

Exemple complet : rapport de dépenses

Modèle :

{
  "document": {
    "styles": {
      "title": { "fontSize": 16, "fontWeight": "bold" },
      "th": {
        "fontSize": 9, "fontWeight": "bold", "color": "#FFFFFF", "backgroundColor": "#1A1A2E",
        "paddingTop": 5, "paddingRight": 8, "paddingBottom": 5, "paddingLeft": 8
      },
      "td": {
        "fontSize": 9, "color": "#333333",
        "paddingTop": 4, "paddingRight": 8, "paddingBottom": 4, "paddingLeft": 8,
        "borderBottom": "0.5pt solid #E0E0E0"
      },
      "total": { "fontSize": 11, "fontWeight": "bold", "marginTop": 8 }
    },
    "content": [
      { "p": "Expense Report — $data.report.period", "style": "title" },
      { "p": "Employee: $data.employee.name  |  Department: $data.employee.department" },
      {
        "table": {
          "source": "$data.expenses",
          "map": ["$item.date", "$item.description", "$item.category", "$data.currency $item.amount"],
          "widths": [2, 3, 2, 2],
          "rows": [
            [
              { "th": "Date", "style": "th" },
              { "th": "Description", "style": "th" },
              { "th": "Category", "style": "th" },
              { "th": "Amount", "style": "th" }
            ]
          ]
        }
      },
      { "p": "Total: $data.currency $data.total", "style": "total" }
    ]
  }
}

Données :

{
  "report": { "period": "Q1 2026" },
  "employee": { "name": "Sarah Mitchell", "department": "Engineering" },
  "currency": "USD",
  "expenses": [
    { "date": "Jan 15", "description": "Conference registration", "category": "Training", "amount": "850.00" },
    { "date": "Jan 16", "description": "Flight YYZ → SFO", "category": "Travel", "amount": "1,240.00" },
    { "date": "Jan 17", "description": "Hotel (3 nights)", "category": "Accommodation", "amount": "960.00" },
    { "date": "Jan 18", "description": "Team dinner", "category": "Meals", "amount": "185.00" }
  ],
  "total": "3,235.00"
}

Résultat attendu :

Date	Description	Category	Amount
Jan 15	Conference registration	Training	USD 850.00
Jan 16	Flight YYZ → SFO	Travel	USD 1,240.00
Jan 17	Hotel (3 nights)	Accommodation	USD 960.00
Jan 18	Team dinner	Meals	USD 185.00

Remarquez comment "$data.currency $item.amount" dans la carte mélange une valeur $data au niveau du document avec des valeurs $item par ligne — le préfixe de devise vient des données racine, tandis que le montant vient de chaque ligne de dépenses.

Galerie des cas limites​

Structure de base​

Propriétés​

Largeurs des colonnes​

Lignes​

Types de cellules​

Cellules d'en-tête (th)​

Cellules de données (td)​

Codes courts dans les cellules​

Cellules de liste​

Style de tableau​

Style des cellules du tableau​

Style de la ligne d'en-tête​

Fusion de cellules — colspan et rowspan​

Colspan — fusion entre colonnes​

Rowspan — fusion entre lignes​

Les deux à la fois​

Pourquoi pas dans le bloc de style ?​

Tableaux imbriqués​

Utilisation du formatage inline dans les cellules​

Tableaux pilotés par les données​

Liaison de données de base​

Modèles $item.* dans la carte​

Exemple complet : rapport de dépenses​