Travailler avec les graphiques

Travailler avec les graphiques

Aspose.Words FOSS pour .NET peut insérer des graphiques Word natifs — les mêmes graphiques DrawingML que Word crée — sous forme de forme dans le calque de dessin. DocumentBuilder.InsertChart crée la forme et la renvoie ; la propriété Chart de la forme expose les séries, les axes, la légende et le formatage. Ce guide couvre la création d’un graphique, le choix d’un type de graphique, le travail avec les séries et les points de données, les axes et les quadrillages, ainsi que le formatage des éléments du graphique.

Créer un graphique

Appelez DocumentBuilder.InsertChart(chartType, width, height) pour insérer une forme de graphique au curseur et récupérer le Shape contenant. Sa propriété Chart est l’objet Chart que vous configurez. Un graphique fraîchement inséré est fourni avec des séries de démonstration factices, donc videz Chart.Series avant d’ajouter des données réelles avec ChartSeriesCollection.Add(seriesName, categories, values) :

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");

Cet exemple construit un Document, utilise DocumentBuilder.InsertChart(ChartType.Line, 432, 252) pour insérer une forme de graphique en ligne, lit shape.Chart pour obtenir l’objet Chart, appelle chart.Series.Clear() pour supprimer la série factice, ajoute une série réelle avec chart.Series.Add(seriesName, categories, values), et écrit le résultat avec Document.Save.

Types de graphiques

ChartType couvre les familles de graphiques Word standard — Line, Bar, Column (plus leurs variantes Stacked, PercentStacked et 3D), Pie, PieOfPie, Doughnut, Area, Scatter, Bubble, Radar, Stock, Surface, et les types de graphiques Word 2016 plus récents Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker et Waterfall. Passez la valeur souhaitée comme argument chartType à InsertChart ; il n’existe aucun moyen de changer le type d’un graphique existant après insertion autre que remplacer la forme.

Séries et points de données

Chart.Series est un ChartSeriesCollection d’objets ChartSeries. Au-delà de la surcharge Add(seriesName, categories, values) utilisée ci-dessus, ChartSeriesCollection propose également des surcharges pour les paires de valeurs X/Y, les dates et les tailles de bulles, ainsi que Insert, Remove(index) et Clear(). Chaque ChartSeries expose DataPoints (un ChartDataPointCollection) pour le formatage point par point — Format, Marker, Explosion et InvertIfNegative — et HasDataLabels / DataLabels pour activer et configurer un ChartDataLabelCollection (ShowValue, ShowCategoryName, ShowPercentage, Position).

Axes et lignes de grille

Chart.AxisX, AxisY et AxisZ sont des objets ChartAxis (avec Chart.Axes comme ChartAxisCollection pour itérer sur tous). Chaque axe possède HasMajorGridlines / HasMinorGridlines, MajorUnit / MinorUnit (avec des indicateurs *IsAuto correspondants), Crosses / CrossesAt, CategoryType, et un objet TickLabels (AxisTickLabels) pour la police et l’orientation des libellés. ChartAxis.Title (ChartAxisTitle) définit le texte de la légende de l’axe via ses propriétés Text et Show.

Légende, titre et tableau de données

Chart.Title (ChartTitle) définit la légende globale du graphique — Text, Show et Font. Chart.Legend (ChartLegend) contrôle si et où la légende apparaît via Position (une valeur LegendPosition telle que Bottom, Right ou Top) et expose les LegendEntries individuels. Chart.DataTable (ChartDataTable) peut afficher les valeurs de séries sous-jacent sous forme de tableau sous la zone du tracé, avec les bascules Show, HasLegendKeys et bascules de bordure.

Mise en forme des éléments du graphique

La plupart des éléments du graphique — séries, points de données, axes, le titre et la légende — exposent une propriété Format de type ChartFormat, qui expose à son tour Fill et Stroke pour les couleurs de cet élément, ainsi qu’un ShapeType (ChartShapeType) pour les formes des marqueurs de points de données. ChartFormat.SetDefaultFill() réinitialise un élément à son apparence par défaut dictée par le thème.

Conseils et bonnes pratiques

• Supprimez toujours ou remplacez la série d’espace réservé (chart.Series.Clear()) avant d’ajouter des données réelles — un graphique fraîchement inséré contient déjà des données d’exemple.
• Utilisez les surcharges ChartSeriesCollection.Add qui correspondent à la forme de vos données (catégories, paires X/Y, dates ou tailles de bulles) plutôt que d’obliger tout à passer par des paires catégorie/valeur.
• Définissez HasDataLabels = true sur une série avant de configurer sa collection DataLabels — les propriétés d’affichage de la collection n’ont aucun effet visible tant que les libellés sont désactivés.
• Lisez Chart.ChartSpace ou vérifiez le ChartType spécifique avant de vous fier au comportement des quadrillages ou des axes qui diffère entre les graphiques classiques et ceux de style Word-2016.
• Privilégiez ChartFormat.SetDefaultFill() plutôt que de supprimer manuellement chaque propriété de remplissage lorsque vous souhaitez réinitialiser l’apparence d’un élément.

Problèmes courants

FAQ

Comment insérer un graphique dans un document ?

Appelez DocumentBuilder.InsertChart(chartType, width, height). Il renvoie le Shape contenant ; lisez sa propriété Chart pour configurer le graphique.

Comment ajouter des données à un graphique ?

Effacez la série d’espace réservé avec chart.Series.Clear(), puis appelez chart.Series.Add(seriesName, categories, values) (ou l’une des autres surcharges Add pour les données X/Y, date ou bulle).

Quels types de graphiques sont disponibles ?

ChartType comprend les familles classiques (Line, Bar, Column, Pie, Area, Scatter, Bubble, Radar, Stock, Surface, ainsi que leurs variantes empilées et 3D) et les types de graphiques Word 2016 (Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall).

Comment modifier l’emplacement de la légende ?

Définissez Chart.Legend.Position sur une valeur LegendPosition, comme LegendPosition.Bottom ou LegendPosition.Right.

Puis-je formater un point de données individuel différemment du reste de sa série?

Oui — indexez dans ChartSeries.DataPoints (un ChartDataPointCollection) et définissez le Format, le Marker ou le Explosion de ce ChartDataPoint indépendamment du formatage au niveau de la série.

API Reference Résumé

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation