Travailler avec les tableaux

Tableaux dans Aspose.Words FOSS pour .NET sont représentés par le Aspose.Words.Tables espace de noms : Table, Row, et Cell forment une hiérarchie de nœuds composites à trois niveaux qui se situe dans l’arborescence du document aux côtés des paragraphes. Cette page couvre la création de tableaux avec DocumentBuilder, le formatage des lignes et des cellules, le contrôle de la mise en page du tableau, et la fusion des cellules.

Modèle d’objet de tableau

Un Table est un CompositeNode contenant des nœuds Row, et chaque Row est un CompositeNode contenant des nœuds Cell; un Cell contient à son tour des paragraphes et, éventuellement, des tableaux imbriqués. Table.Rows renvoie un RowCollection, Row.Cells renvoie un CellCollection, et un Body ou autre Story expose chaque tableau de niveau supérieur qu’il contient via sa propriété Tables, un TableCollection. Les trois collections prennent en charge Add(), Insert(), Remove(), RemoveAt(), Contains() et IndexOf(). Table.EnsureMinimum(), Row.EnsureMinimum() et Cell.EnsureMinimum() remplissent chacun le contenu valide le plus petit qu’un nœud de ce type nécessite (une ligne vide, une cellule vide ou un paragraphe vide, respectivement) après que des modifications programmatiques en ont laissé un sans.

Création de tableaux avec DocumentBuilder

DocumentBuilder.StartTable() démarre un nouveau tableau à la position du curseur, InsertCell() ajoute une cellule à la ligne courante, EndRow() ferme la ligne courante, et EndTable() ferme le tableau. Définissez DocumentBuilder.CellFormat et DocumentBuilder.RowFormat avant d’appeler InsertCell() ou EndRow() pour appliquer le formatage par défaut aux cellules et aux lignes lors de leur création — ces propriétés servent de modèle pour le contenu que le constructeur insère ensuite, et ne modifient pas rétroactivement les cellules déjà présentes dans le document.

Formatage des cellules et des lignes

Cell.CellFormat est une instance CellFormat (Borders, Shading, Width, WrapText, FitText, HorizontalMerge, VerticalMerge, VerticalAlignment, PreferredWidth, LeftPadding, RightPadding, TopPadding, BottomPadding, HideMark, Orientation) avec ClearFormatting() pour la réinitialiser et SetPaddings() pour définir les quatre marges internes des cellules en une fois. Row.RowFormat est une instance RowFormat (Borders, Height, HeightRule, AllowBreakAcrossPages, HeadingFormat) avec son propre ClearFormatting().

Mise en forme de l’ensemble du tableau et AutoFit

Table expose lui-même des propriétés de mise en page – Alignment (TableAlignment), Bidi, LeftIndent, PreferredWidth, Style, StyleIdentifier, StyleName, StyleOptions (TableStyleOptions), TextWrapping, et des métadonnées d’accessibilité via Title et Description. Table.AutoFit(AutoFitBehavior) redimensionne le tableau et ses cellules selon le comportement indiqué. SetBorder() définit un côté de bordure et SetBorders() définit chaque bordure avec le même style de ligne, largeur et couleur sur l’ensemble du tableau; ClearBorders() et ClearShading() les réinitialisent. ConvertToHorizontallyMergedCells() convertit les cellules qui étaient fusionnées par largeur correspondante en cellules explicitement marquées avec HorizontalMerge.

Largeurs préférées et largeur des cellules

PreferredWidth représente une largeur et son unité, créée avec les méthodes d’usine statiques PreferredWidth.FromPercent() ou PreferredWidth.FromPoints(); PreferredWidthType identifie quel type de valeur (Auto, Percent ou Points) possède un PreferredWidth donné. Tant Table.PreferredWidth que CellFormat.PreferredWidth acceptent ces valeurs.

Cellules fusionnées

CellFormat.HorizontalMerge et CellFormat.VerticalMerge (CellMerge) indiquent comment une cellule participe à une fusion horizontale ou verticale avec ses voisines. CellVerticalAlignment contrôle la justification du contenu à l’intérieur d’une cellule verticalement, indépendamment de tout état de fusion.

Conseils et meilleures pratiques

Fermez chaque StartTable() avec un EndRow() correspondant par ligne et un EndTable() final — une ligne ou un tableau non fermé laisse l’état interne du constructeur (et l’arbre de document résultant) malformé.
Définissez DocumentBuilder.CellFormat et DocumentBuilder.RowFormat avant chaque appel à InsertCell() ou EndRow() si des lignes ou des cellules différentes dans le même tableau nécessitent un formatage différent; le constructeur applique ce qui est actuellement défini au moment de l’insertion.
Appelez Table.EnsureMinimum(), Row.EnsureMinimum() ou Cell.EnsureMinimum() après avoir supprimé du contenu de manière programmatique afin que le nœud conserve la structure minimale valide attendue par Word.
Utilisez PreferredWidth.FromPercent() pour les tableaux qui doivent s’adapter à la largeur de page disponible, et PreferredWidth.FromPoints() pour une largeur de mise en page fixe.
AutoFitBehavior est appliqué lorsque vous appelez Table.AutoFit() — il ne se réexécute pas continuellement lorsque vous ajoutez ou supprimez du contenu, donc appelez-le de nouveau après des modifications importantes si vous avez besoin que le tableau soit réajusté.

Problèmes courants

Problème	Cause	Correction
Le tableau semble malformé ou génère une erreur lors de l’enregistrement	Une ligne ou le tableau n’a jamais été fermée avec `EndRow()` / `EndTable()`	Associez toujours `StartTable()` à un `EndTable()` final, et fermez chaque ligne avec `EndRow()`
Les nouvelles cellules ne reprennent pas le formatage que j’ai défini	`CellFormat` / `RowFormat` ont été modifiés dans le constructeur après que les cellules aient déjà été insérées	Définissez `DocumentBuilder.CellFormat` / `RowFormat` avant d’appeler `InsertCell()` / `EndRow()` pour ce contenu
Le tableau ne se redimensionne pas comme je l’attends après les modifications	`AutoFit()` reflète l’état du tableau au moment où il est appelé, pas de manière continue	Appelez `Table.AutoFit(AutoFitBehavior)` à nouveau après les modifications structurelles
Les cellules adjacentes qui semblent fusionnées se comportent comme des cellules séparées	Les cellules n’étaient associées que par largeur, sans être marquées avec `CellMerge`	Appelez `Table.ConvertToHorizontallyMergedCells()`, ou définissez explicitement `CellFormat.HorizontalMerge` / `VerticalMerge`

FAQ

Comment créer un tableau à partir de zéro avec DocumentBuilder?

Appelez StartTable(), puis InsertCell() pour chaque cellule d’une ligne, EndRow() pour fermer la ligne, répétez pour les lignes supplémentaires, et enfin EndTable() pour fermer le tableau.

Comment définir une largeur de tableau en pourcentage au lieu d’une largeur fixe?

Attribuez Table.PreferredWidth = PreferredWidth.FromPercent(value) au lieu de PreferredWidth.FromPoints(value).

Comment réinitialiser toute la mise en forme d’une cellule ou d’une ligne?

Appelez CellFormat.ClearFormatting() sur le CellFormat d’une cellule, ou RowFormat.ClearFormatting() sur le RowFormat d’une ligne.

Comment définir les bordures et l’ombrage pour l’ensemble du tableau en une seule fois?

Utilisez Table.SetBorders() pour une bordure uniforme sur chaque côté, Table.SetBorder() pour un côté à la fois, et Table.SetShading() pour un ombrage uniforme; ClearBorders() et ClearShading() les réinitialisent.

API Reference Résumé

Classe / Enum	Description
`Table`	Nœud de tableau ; `Rows`, `AutoFit()`, `SetBorders()`, `SetShading()`, `PreferredWidth`
`Row`	Nœud de ligne de tableau ; `Cells`, `RowFormat`, `EnsureMinimum()`
`Cell`	Nœud de cellule de tableau ; `CellFormat`, `EnsureMinimum()`
`TableCollection` / `RowCollection` / `CellCollection`	Collections typées de nœuds `Table` / `Row` / `Cell`
`CellFormat`	Mise en forme par cellule : bordures, ombrage, remplissage, état de fusion, alignement vertical
`RowFormat`	Mise en forme par ligne : bordures, hauteur, comportement de saut de page
`PreferredWidth` / `PreferredWidthType`	Valeur de largeur de tableau ou de cellule et son unité (auto, pourcentage, points)
`AutoFitBehavior`	Comment `Table.AutoFit()` redimensionne un tableau et ses cellules
`CellMerge` / `CellVerticalAlignment`	État de fusion de cellules horizontales/verticales et alignement vertical du contenu
`TableAlignment` / `TableStyleOptions` / `TextWrapping`	Alignement à l’échelle du tableau, application de style et comportement du retour à la ligne
`DocumentBuilder.StartTable` / `InsertCell` / `EndRow` / `EndTable`	Construction de tableau basée sur le curseur

Voir aussi

Aspose.Words for .NET — Enterprise Documentation