Introduction
Ce guide montre comment créer des graphiques Word natifs avec Aspose.Words FOSS pour .NET — les mêmes objets de dessin que Word crée lui-même lorsque vous utilisez Insertion > Graphique — entièrement à partir du code. Un graphique ajouté de cette façon n’est pas une image; c’est un objet Chart intégré dans le paquet OOXML du document, avec un modèle de séries de données, des axes, une légende et un tableau de données que Word peut toujours ouvrir et modifier après l’enregistrement du fichier. Cet article constitue une plongée approfondie dans ce API de graphique: comment créer un graphique, ajouter des données de séries, et accéder aux objets d’axe, de légende, d’étiquette de données et de mise en forme qui contrôlent son rendu.
La bibliothèque est sous licence MIT et n’a aucune dépendance native. Elle cible .NET Standard 2.0, de sorte que le code de cet article s’exécute tel quel sur .NET Framework 4.6.2+ et .NET 6, 8 et 10. Installez-la via NuGet, ou compilez-la à partir des sources — voir le démarrage rapide ci-dessous. Tout ce qui est présenté ici utilise le même moteur de graphiques que le Aspose.Words commercial pour .NET ; cette édition comprend le modèle complet d’objet graphique mais pas la mise en page ou le rendu, de sorte que la position du graphique sur la page n’est pas calculée et que le document ne peut pas être exporté en PDF ou en image.
Ce qui est inclus
Création d’un graphique et ajout d’une série de données
DocumentBuilder.InsertChart(chartType, width, height) insère une forme de graphique à la position actuelle et renvoie un Shape; sa propriété Chart est le point d’entrée pour tout le reste. Un graphique nouvellement inséré possède déjà une série par défaut, ainsi la plupart du code la supprime d’abord et ajoute ses propres données via Chart.Series, un ChartSeriesCollection.
using Aspose.Words;
using Aspose.Words.Drawing.Charts;
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;
// Delete default generated series.
chart.Series.Clear();
string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });
ChartSeriesCollection.Add propose des surcharges pour les paires catégorie/valeur (comme ci-dessus), les paires X/Y, les séries datées et les séries à bulles avec une valeur de taille supplémentaire. Sur un ChartSeries individuel, Add(xValue), Add(xValue, yValue) et Add(xValue, yValue, bubbleSize) ajoutent des points uniques, Insert place un point à un indice donné, et Clear()/ClearValues() suppriment les données de la série sans nécessairement supprimer l’objet série lui-même.
Types de graphiques et types de séries
ChartType — l’énumération passée à InsertChart — comporte environ 40 membres couvrant les familles de graphiques Word standard: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall et Funnel, ainsi que des variantes empilées, empilées en pourcentage et 3D de plusieurs d’entre elles (Bar3D, ColumnStacked, Area3DPercentStacked, etc.).
Une énumération apparentée mais distincte, ChartSeriesType, apparaît sur ChartSeries.SeriesType et ChartSeriesGroup.SeriesType et décrit le type d’une série individuelle ou d’un groupe de séries plutôt que celui du graphique dans son ensemble. Elle possède les mêmes membres que ChartType plus deux supplémentaires — ParetoLine et RegionMap — que ChartType n’expose pas directement. ChartSeriesGroup est ce qui rend les graphiques combinés possibles: Chart.SeriesGroups (un ChartSeriesGroupCollection) contient un groupe par type de série dans le graphique, et chaque groupe possède sa propre paire AxisX/AxisY ainsi que des propriétés de mise en page telles que Overlap, GapWidth, BubbleScale et DoughnutHoleSize.
Axes, quadrillages et mise à l’échelle
Chart.AxisX, AxisY et AxisZ (plus la collection Axes) renvoient des objets ChartAxis. Chaque axe possède un Type (ChartAxisType.Category, Series ou Value), des paramètres de marques de graduation (MajorTickMark, MinorTickMark — Cross, Inside, Outside ou None), des indicateurs de quadrillage (HasMajorGridlines, HasMinorGridlines) et un contrôle d’unité (MajorUnit, MinorUnit et leurs équivalents *IsAuto). ChartAxis.Scaling renvoie un objet AxisScaling dont les Minimum et Maximum sont des valeurs AxisBound — AxisBound.IsAuto indique si la limite est calculée automatiquement, et les constructeurs paramétrés (AxisBound(value), AxisBound(datetime)) définissent une limite numérique ou de date explicite. Un axe de catégorie peut être fixé à des catégories de texte ou de temps via ChartAxis.CategoryType (AxisCategoryType.Automatic, Category ou Time), et ChartAxis.Title expose un ChartAxisTitle avec son propre Text, Show et Font.
Légende, tableau de données et titre du graphique
Chart.Legend renvoie un ChartLegend, dont le Position (un LegendPosition de None, Bottom, Left, Right, Top ou TopRight) contrôle où il s’affiche par rapport à la zone de tracé; LegendEntries est un ChartLegendEntryCollection d’objets ChartLegendEntry individuels, chacun disposant de son propre Font et d’un indicateur IsHidden pour masquer une série unique de la légende sans la supprimer du graphique. Chart.DataTable (un ChartDataTable) rend les valeurs des séries sous forme de grille sous le graphique lorsque Show est activé, HasLegendKeys, HasHorizontalBorder, HasVerticalBorder et HasOutlineBorder contrôlant son apparence. Chart.Title est un ChartTitle avec des propriétés Text et Show, suivant le même modèle que les titres d’axes.
Étiquettes de données, points de données et marqueurs
ChartSeries.HasDataLabels active les étiquettes de données pour une série, et ChartSeries.DataLabels (un ChartDataLabelCollection) ou un ChartDataLabel individuel provenant de celle-ci contrôle ce que chaque étiquette affiche: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey et ShowBubbleSize sont des indicateurs indépendants, et Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit et d’autres) place l’étiquette relative à son point. ChartSeries.DataPoints donne un accès point par point via ChartDataPoint, qui possède son propre Marker (un ChartMarker avec Symbol de l’énumération MarkerSymbol et un Size), Explosion (pour extraire une tranche de camembert), et Format. Chaque élément du graphique qui peut être rempli ou contourné — séries, points de données, légende, titre, tableau de données — expose un ChartFormat via sa propriété Format, avec les propriétés Fill, Stroke et ShapeType (ChartShapeType) ainsi qu’une méthode SetDefaultFill() pour le réinitialiser. Une mise en garde utile: les variantes liées au thème des couleurs de remplissage et de trait sur ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor et leurs équivalents teinte/ombre) ne sont pas implémentées dans cette édition — utilisez des couleurs Fill/Stroke simples au lieu de références de couleur de thème. Chart.Style (un ChartStyle tel que Muted, Saturated, Gradient, Outline ou Black) applique un style prédéfini à l’ensemble du graphique en une seule étape.
Démarrage rapide
Aspose.Words FOSS pour .NET est disponible via NuGet:
dotnet add package Aspose.Words.FOSSPour construire à partir du code source à la place:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Ajoutez ensuite une référence de projet à Aspose.Words.csproj depuis votre application. Une fois la référence en place, cela crée un graphique en lignes avec une série et l’enregistre au format DOCX:
using Aspose.Words;
using Aspose.Words.Drawing.Charts;
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;
// Delete default generated series.
chart.Series.Clear();
string[] categories = new string[] { "AW Category 1", "AW Category 2", "AW Category 3" };
chart.Series.Add("AW Series 1", categories, new double[] { 4.3, 2.5, 3.5 });
doc.Save("chart.docx");
Console.WriteLine("Saved chart.docx");
Ouvrez chart.docx dans Word et le graphique est entièrement modifiable — faites un clic droit dessus et choisissez “Edit Data” pour voir les mêmes trois catégories et valeurs indiquées ci-dessus.
Formats pris en charge
| Format | Extension | Lire | Écrire |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (toutes les variantes) | (divers) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Les graphiques créés avec le Chart API sont des objets de dessin OOXML, ils sont donc compatibles en aller-retour avec les formats de la famille DOCX mentionnés ci-dessus (DOCX, DOCM, DOTX, DOTM et Flat OPC). Cette édition ne peut pas exporter en PDF, XPS ou images et ne peut pas imprimer, ainsi aucun rendu de graphique en bitmap n’est effectué — le graphique reste un objet vivant et modifiable à l’intérieur du fichier Word. Les convertisseurs de formats supplémentaires supprimés de cette édition (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 et WordML) sont les mêmes sous-systèmes exclus partout ailleurs dans la bibliothèque, et ne sont pas spécifiques aux graphiques.
Open Source & Licence
Aspose.Words FOSS pour .NET est publié sous la licence MIT, gratuit pour une utilisation commerciale et personnelle sans redevances ni restrictions de redistribution. Le code source complet, y compris les classes de graphiques référencées dans cet article, est disponible sur GitHub dans le Aspose.Words FOSS pour .NET repository.
