Vue d’ensemble

Les documents de type feuille de calcul sont des documents qui contiennent des données sous forme de tableau — sous forme de lignes et de colonnes. Ils sont également appelés carnets de travail. Il existe de nombreux formats de documents de feuille de calcul — Office Open XML (comme XLSX, XLSM, etc.), Microsoft Excel Binary File Format (XLS, XLT), format OpenDocument Spreadsheet (ODS, FODS, OTS), formats textuels à séparateur ( CSV, TSV etc.) et ainsi de suite. Tous forment ce que l’on appelle la famille des formats de feuilles de calcul. GroupDocs.Viewer prend en charge presque tous les formats de feuilles de calcul à l’import et permet de les rendre (convertir) en HTML, PDF, PNG et JPEG. Cet article explique comment le faire, quelles options sont disponibles, ainsi que quand et pourquoi les utiliser.

Rendu d’un classeur, ouvert dans MS Excel, au format HTML

Utilisation de base

Tout d’abord, il faut parler des options. Il existe une classe dédiée dans l’API publique : SpreadsheetOptions dans le namespace GroupDocs.Viewer.Options. Cette classe est spécialement conçue pour ajuster le rendu de la famille des formats de feuilles de calcul. Elle est accessible depuis les quatre options de vue via la propriété SpreadsheetOptions :

Lorsqu’elle n’est pas spécifiée explicitement, la propriété SpreadsheetOptions possède une valeur implicite par défaut : une instance de la classe SpreadsheetOptions, qui sera détaillée plus loin dans cet article.

En un clin d’œil, rendre un document de feuille de calcul avec GroupDocs.Viewer est très simple et comparable à tous les autres formats : créer une instance de ViewOptions, créer une instance de Viewer en indiquant le document de feuille de calcul d’entrée, puis appeler la méthode Viewer.View(viewOptions). L’exemple de code suivant montre le rendu d’un seul fichier de feuille de calcul vers les 4 formats de sortie : HTML, PDF, PNG et JPEG. Notez qu’en dehors de la création des instances des classes d’options, aucun réglage propre aux feuilles de calcul n’est effectué ; toutes les options de feuille de calcul conservent leurs valeurs par défaut.

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

HtmlViewOptions htmlOptions = HtmlViewOptions.ForEmbeddedResources("worksheet_{0}.html");
PdfViewOptions pdfOptions = new PdfViewOptions("Output_spreadsheet.pdf");
PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
JpgViewOptions jpegOptions = new JpgViewOptions("worksheet_{0}.jpeg");

using (Viewer viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(htmlOptions);
    viewer.View(pdfOptions);
    viewer.View(pngOptions);
    viewer.View(jpegOptions);
}

Passons maintenant aux feuilles de calcul. Chaque feuille de calcul possède au moins une feuille de travail. Dans la plupart des logiciels de traitement de tableaux comme Microsoft Excel, les feuilles sont représentées sous forme d’onglets. Certains formats de feuille de calcul ne contiennent qu’une seule feuille ; c’est le cas, par exemple, de tous les formats textuels à séparateur (CSV, TSV etc.).

Par défaut, GroupDocs.Viewer rend toutes les feuilles présentes dans le classeur fourni. Mais cela peut être modifié. La méthode Viewer.View() possède une surcharge qui accepte un tableau de numéros de pages en second paramètre : Int32[] pageNumbers. Lorsqu’on utilise ce paramètre, seules les pages indiquées sont rendues. Ce paramètre est universel et s’applique à tous les formats supportés disposant de pages, mais dans le contexte de la famille des formats de feuilles de calcul il correspond exactement aux numéros de feuilles à afficher.

À noter que le comptage des pages (et donc des feuilles) commence à 1, pas à 0.

L’exemple ci‑dessous montre comment rendre la 1ᵉʳᵉ et la 3ᵉᵉ feuille en PNG dans un classeur contenant 3 feuilles.

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

PngViewOptions pngOptions = new PngViewOptions("worksheet_{0}.png");
using (Viewer viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pngOptions, 1, 3);
}

Découpage des feuilles en pages

GroupDocs.Viewer rend les documents sous forme de pages, où l’on entend par « page » une zone rectangulaire de taille relativement petite, comparable à l’affichage à l’écran ou à une feuille A4. En revanche, les feuilles de calcul peuvent être très volumineuses. Par exemple, le format maintenant obsolète XLS ne supporte que 256 colonnes et 65 536 lignes ; le format plus récent XLSX (Office Open XML Workbook) ainsi que Microsoft Excel supportent jusqu’à 16 384 colonnes et 1 048 576 lignes. « Adapter » les feuilles à des pages est donc une étape cruciale du rendu avec GroupDocs.Viewer. Pour ce faire, le Viewer effectue un découpage de la feuille : la feuille est divisée en plusieurs blocs rectangulaires, chacun étant placé sur une page distincte. Cinq méthodes de découpage sont proposées ci‑après.

L’essentiel : toutes ces méthodes de découpage sont obtenues de la même façon — en appelant une méthode statique (factory) qui crée une instance de la classe SpreadsheetOptions.

Rendre toute la feuille sur une page unique

SpreadsheetOptions.ForOnePagePerSheet()

La façon la plus simple : désactiver le découpage et ajuster la taille de la page afin qu’elle contienne l’intégralité du contenu de la feuille. C’est une bonne option lorsqu’on sait d’avance que la feuille est petite. En revanche, si la feuille est très grande, cette approche peut générer des résultats catastrophiques. Par exemple, le rendu HTML peut produire un fichier de plusieurs dizaines voire centaines de MiB, ce qui rend son affichage difficile dans les navigateurs. En JPEG, le rendu peut échouer si la largeur ou la hauteur dépasse la limite maximale de 65 535 pixels. Utilisez donc ce mode en connaissance de cause.

Rendu de la feuille sur une page unique

Découper la feuille selon les sauts de page

SpreadsheetOptions.ForRenderingByPageBreaks()

Microsoft Excel insère automatiquement des sauts de page en fonction du format de papier et des paramètres de mise en page (orientation, marges, etc.). En basculant sur l’onglet « Affichage » puis « Aperçu des sauts de page », on voit des lignes bleues qui divisent la zone de la feuille en blocs rectangulaires, chacun étant étiqueté « Page 1», « Page 2», etc. C’est ainsi qu’Excel « suggère » de découper la feuille.

Cette méthode fait en sorte que GroupDocs.Viewer suive Excel et découpe les feuilles selon les sauts de page définis dans le classeur.

À noter que cette option — découper selon les sauts de page — est l’option par défaut de la propriété BaseViewOptions.SpreadsheetOptions. Ainsi, dès la création d’une instance d’options de vue, l’option [ForRenderingByPageBreaks()] est sélectionnée automatiquement.

Rendre uniquement la zone d’impression

SpreadsheetOptions.ForRenderingPrintArea()

En plus des sauts de page, Excel possède le concept de Zone d’impression. Il s’agit d’un ou plusieurs intervalles de cellules désignés pour l’impression ; tout le contenu hors de cette zone n’est pas imprimé. Pour ajouter une plage à la zone d’impression, ouvrez l’onglet « Mise en page », cliquez sur le bouton « Zone d’impression », puis choisissez « Définir la zone d’impression ». Pour ajouter une autre plage, sélectionnez‑la, cliquez à nouveau sur « Zone d’impression » et choisissez « Ajouter à la zone d’impression ». En mode « Aperçu des sauts de page », toutes les zones sont visibles.

Rendu de la zone d’impression uniquement

Rendre la zone d’impression et découper selon les sauts de page

SpreadsheetOptions.ForRenderingPrintAreaAndPageBreaks()

GroupDocs.Viewer propose une fonctionnalité unique : combiner la zone d’impression et les sauts de page dans un seul mode. Le Viewer prend en compte à la fois les intervalles de la zone d’impression et les sauts de page, puis les applique simultanément pour découper la feuille.

Dans la capture d’écran suivante, la ligne rouge indique la zone d’impression, tandis que les lignes bleues montrent les sauts de page.

Rendu de la zone d’impression et découpage par sauts de page

Découper la feuille manuellement par lignes et colonnes

SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage)
SpreadsheetOptions.ForSplitSheetIntoPages(int countRowsPerPage, int countColumnsPerPage)

Dans certains cas, aucune des méthodes précédentes ne convient, ou le format du classeur ne supporte ni les sauts de page ni les zones d’impression (par exemple les fichiers CSV). Dans ces situations, GroupDocs.Viewer permet de spécifier manuellement le nombre de lignes et/ou de colonnes devant figurer sur chaque page. En bref, la différence entre le découpage uniquement par lignes et le découpage par lignes + colonnes est illustrée ci‑dessous.

Si la première surcharge de ForSplitSheetIntoPages est utilisée (un seul paramètre), le découpage se fait uniquement par lignes. Si la deuxième surcharge est utilisée (deux paramètres), le découpage s’effectue à la fois par lignes et par colonnes.

Découpage manuel de la feuille par lignes et colonnes

Ajustement d’options supplémentaires

Tout ce qui a été décrit jusqu’ici constitue l’essentiel pour rendre des feuilles de calcul avec GroupDocs.Viewer. Néanmoins, de nombreuses options supplémentaires existent ; elles ne sont pas obligatoires, mais permettent de personnaliser davantage le résultat du rendu.

Certaines de ces options sont exposées sous forme de propriétés de la classe SpreadsheetOptions, qui est elle‑même accessible via la propriété SpreadsheetOptions des classes d’options de vue. D’autres se trouvent dans la classe abstraite ViewOptions, commune à tous les quatre modes de rendu.

Rendre les en‑têtes de lignes et de colonnes

Lorsque MS Excel (ou un logiciel similaire) ouvre un classeur, il affiche les en‑têtes : les colonnes sont libellées (A, B, C, AA, AB, …) et les lignes sont numérotées (1, 2, 3, …, 1 048 576). Par défaut, GroupDocs.Viewer ne les affiche pas, car elles font partie de l’interface du tableur, pas du document lui‑même. Cette logique peut être modifiée grâce à la propriété booléenne RenderHeadings. Désactivée (false) par défaut, elle devient active (true) lorsqu’on souhaite que les en‑têtes apparaissent dans le document rendu, comme le montre la capture d’écran ci‑après.

Rendu des en‑têtes de lignes et de colonnes

Rendre les lignes de quadrillage de la feuille

Le principe est similaire au précédent. Par défaut, le Viewer ne trace pas les lignes de quadrillage entre les cellules, car elles ne font pas partie du fichier mais seulement de l’affichage du tableur. En définissant la propriété booléenne RenderGridLines à true, les quadrillages seront visibles dans le résultat, comme le montre l’exemple suivant.

Rendu des lignes de quadrillage

Contrôler le débordement du texte dans les cellules

Il arrive fréquemment qu’une cellule contienne plus de texte que sa largeur ne le permet. Comment gérer ce débordement ? GroupDocs.Viewer propose la propriété SpreadsheetOptions.TextOverflowMode pour régler ce comportement. Cette propriété utilise l’énumération TextOverflowMode, qui comporte quatre valeurs :

OverlayIfNextIsEmpty

Valeur par défaut. Le texte déborde dans les cellules adjacentes uniquement si celles‑ci sont vides. Si une cellule voisine contient déjà des données, le texte est tronqué.

Valeur d’énumération OverlayIfNextIsEmpty

Dans la capture ci‑dessus, la cellule B2 possède un texte long qui est tronqué parce que C2 n’est pas vide. En revanche, le texte de C3 déborde sur D2 et E2, qui sont vides.

Overlay

Le mode Overlay est plus agressif : le texte déborde toujours dans les cellules adjacentes, quelles que soient leurs contenances, et écrase d’éventuelles données présentes.

Valeur d’énumération Overlay

Ici, le texte de B2 se répand dans C2, D2, E2, F2, écrasant le contenu original de C2 et F2.

HideText

HideText fait exactement l’inverse du mode Overlay : le texte qui ne tient pas dans sa cellule est simplement tronqué, même si des cellules voisines sont vides.

Valeur d’énumération HideText

Dans l’exemple, le texte de C3 est tronqué malgré la présence d’un espace libre dans D3, E3, etc.

AutoFitColumn

AutoFitColumn ajuste la largeur de la colonne afin que le texte tienne entièrement. Quelle que soit la longueur du texte, la colonne contenant la cellule est élargie pour l’accueillir.

Valeur d’énumération AutoFitColumn

Ce mode peut toutefois rendre la page très large, entraînant un défilement horizontal fastidieux.

Rendre les lignes et colonnes masquées

Excel et d’autres tableurs permettent de masquer certaines lignes ou colonnes. Par défaut, GroupDocs.Viewer ne les rend pas, mais ce comportement est modifiable. Les propriétés ViewOptions.SpreadsheetOptions.RenderHiddenRows et ViewOptions.SpreadsheetOptions.RenderHiddenColumns, lorsqu’on les met à true, affichent les lignes/colonnes cachées dans le résultat HTML, PDF, PNG ou JPEG.

Rendre les feuilles masquées

De même que pour les lignes/colonnes, un classeur peut contenir des feuilles masquées. Par défaut, le Viewer ne les rend pas. Il suffit d’activer la propriété RenderHiddenPages (mise à true). Cette propriété se trouve dans la classe abstraite BaseViewOptions, et non pas dans SpreadsheetOptions.

Ignorer les lignes et colonnes vides

Certaines feuilles sont « sparse » : elles contiennent beaucoup d’espaces vides qui alourdissent le rendu. En activant les propriétés booléennes SpreadsheetOptions.SkipEmptyRows et SpreadsheetOptions.SkipEmptyColumns, ces lignes/colonnes vides sont omises du résultat final.

Ignorer les lignes et colonnes vides

La capture montre que les deux options sont activées.

Rendre ou masquer les commentaires de cellules

Les cellules peuvent contenir des commentaires. Par défaut, le Viewer les rend tous. Il est possible de les désactiver en utilisant la propriété BaseViewOptions.RemoveComments. En la mettant à true, aucun commentaire ne sera présent dans le rendu. Cette propriété appartient également à la classe BaseViewOptions.

Rendu ou masquage des commentaires de cellules

Dans l’exemple, le fichier XLSX contenant des commentaires est rendu en PNG ; le commentaire de la cellule E2 apparaît dans le PNG.

Définir les marges des feuilles dans les pages PDF de sortie

Lors du rendu en PDF, il est possible de contrôler les marges de page (distance en centimètres entre le bord de la page et le contenu). Quatre propriétés permettent de régler les marges haut, droite, bas et gauche :

Par défaut, ces quatre propriétés sont négatives, ce qui indique que les marges par défaut du Viewer sont utilisées. Elles peuvent toutefois être définies explicitement. Notez que les marges ne s’appliquent que lorsque le format cible est le PDF.

Exemple de code :

using GroupDocs.Viewer;
using GroupDocs.Viewer.Options;
// ...

PdfViewOptions pdfViewOptions = new PdfViewOptions("Output.pdf");
pdfViewOptions.SpreadsheetOptions = SpreadsheetOptions.ForOnePagePerSheet();
pdfViewOptions.SpreadsheetOptions.TopMargin = 2;
pdfViewOptions.SpreadsheetOptions.BottomMargin = 4;
pdfViewOptions.SpreadsheetOptions.LeftMargin = 8;
pdfViewOptions.SpreadsheetOptions.RightMargin = 0;

using (var viewer = new Viewer("spreadsheet.xlsx"))
{
    viewer.View(pdfViewOptions);
}

Résultat visuel :

Définir les marges des feuilles dans le PDF

Conclusion

Les formats de feuilles de calcul sont complexes ; les documents qu’ils contiennent peuvent varier largement en type et en taille. Dans de nombreux cas, il est impossible d’obtenir un rendu satisfaisant avec les options par défaut. C’est pourquoi GroupDocs.Viewer propose un ensemble complet de propriétés ; elles permettent à chaque utilisateur d’ajuster le rendu selon ses besoins spécifiques.

Voir aussi

Essayez gratuitement

Vous pouvez télécharger une version d’essai gratuite de GroupDocs.Viewer pour .NET depuis releases.groupdocs.com. Vous pouvez également obtenir une licence temporaire pour tester toutes les fonctionnalités sans restriction ici.