Einleitung
Dieser Leitfaden zeigt, wie man native Word-Diagramme mit Aspose.Words FOSS für .NET — dieselben Zeichenobjekte, die Word selbst erzeugt, wenn Sie Einfügen > Diagramm verwenden — vollständig aus dem Code erstellt. Ein auf diese Weise hinzugefügtes Diagramm ist kein Bild; es ist ein Chart-Objekt, das im OOXML-Paket des Dokuments eingebettet ist, mit einem Datenreihenmodell, Achsen, einer Legende und einer Datentabelle, die Word nach dem Speichern der Datei weiterhin öffnen und bearbeiten kann. Dieser Beitrag ist ein tiefgehender Einblick in dieses Diagramm-API: wie man ein Diagramm erstellt, Datenreihen hinzufügt und auf die Achsen-, Legenden-, Datenbeschriftungs- und Formatierungsobjekte zugreift, die die Darstellung steuern.
Die Bibliothek ist unter der MIT-Lizenz veröffentlicht und hat keine nativen Abhängigkeiten. Sie richtet sich an .NET Standard 2.0, sodass der Code in diesem Beitrag unverändert auf .NET Framework 4.6.2+ und .NET 6, 8 und 10 läuft. Installieren Sie sie über NuGet oder bauen Sie sie aus dem Quellcode — siehe Schnellstart unten. Alles, was hier gezeigt wird, ist dieselbe Diagramm-Engine, die von der kommerziellen Aspose.Words für .NET verwendet wird; diese Ausgabe enthält das vollständige Diagramm-Objektmodell, jedoch nicht das Seitenlayout oder Rendering, sodass die Position eines Diagramms auf der Seite nicht berechnet wird und das Dokument nicht in PDF oder ein Bild exportiert werden kann.
Was enthalten ist
Ein Diagramm erstellen und eine Datenreihe hinzufügen
DocumentBuilder.InsertChart(chartType, width, height) fügt an der aktuellen Position eine Diagrammform ein und gibt ein Shape zurück; seine Chart-Eigenschaft ist der Einstiegspunkt für alles Weitere. Ein neu eingefügtes Diagramm besitzt bereits eine Standardreihe, sodass der meiste Code sie zunächst löscht und eigene Daten über Chart.Series, ein ChartSeriesCollection, hinzufügt.
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 verfügt über Überladungen für Kategorie/Wert-Paare (wie oben), X/Y-Wert-Paare, datierte Reihen und Blasendiagramme mit einem zusätzlichen Größenwert. Bei einem einzelnen ChartSeries, Add(xValue), Add(xValue, yValue) und Add(xValue, yValue, bubbleSize) fügen Sie einzelne Punkte hinzu, Insert setzt einen Punkt an einem bestimmten Index, und Clear() / ClearValues() entfernen Reihen-Daten, ohne notwendigerweise das Reihen-Objekt selbst zu entfernen.
Diagrammtypen und Serienarten
ChartType — die Aufzählung, die an InsertChart übergeben wird — hat etwa 40 Mitglieder, die die standardmäßigen Word-Diagrammfamilien abdecken: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall und Funnel, plus gestapelte, prozentual gestapelte und 3D-Varianten mehrerer davon (Bar3D, ColumnStacked, Area3DPercentStacked usw.).
Ein verwandtes, aber separates Enum, ChartSeriesType, erscheint in ChartSeries.SeriesType und ChartSeriesGroup.SeriesType und beschreibt den Typ einer einzelnen Serie oder Seriengruppe statt des Diagramms als Ganzes. Es enthält dieselben Mitglieder wie ChartType plus zwei weitere — ParetoLine und RegionMap — die ChartType nicht direkt bereitstellt. ChartSeriesGroup ist das, was Kombinationsdiagramme ermöglicht: Chart.SeriesGroups (ein ChartSeriesGroupCollection) enthält eine Gruppe pro Serientyp im Diagramm, und jede Gruppe hat ihr eigenes AxisX/AxisY-Paar sowie Layout-Eigenschaften wie Overlap, GapWidth, BubbleScale und DoughnutHoleSize.
Achsen, Gitternetzlinien und Skalierung
Chart.AxisX, AxisY und AxisZ (plus die Axes-Sammlung) geben ChartAxis-Objekte zurück. Jede Achse hat ein Type (ChartAxisType.Category, Series oder Value), Tick-Mark-Einstellungen (MajorTickMark, MinorTickMark — Cross, Inside, Outside oder None), Gitternetz-Flags (HasMajorGridlines, HasMinorGridlines) und Einheit-Steuerung (MajorUnit, MinorUnit und ihre *IsAuto-Gegenstücke). ChartAxis.Scaling gibt ein AxisScaling-Objekt zurück, dessen Minimum und Maximum AxisBound-Werte sind — AxisBound.IsAuto gibt an, ob die Grenze automatisch berechnet wird, und die parametrisierten Konstruktoren (AxisBound(value), AxisBound(datetime)) setzen eine explizite numerische oder datumsbasierte Grenze. Eine Kategorienachse kann über ChartAxis.CategoryType (AxisCategoryType.Automatic, Category oder Time) an Text- oder Zeitkategorien angeheftet werden, und ChartAxis.Title stellt ein ChartAxisTitle mit eigenen Text, Show und Font bereit.
Legende, Datentabelle und Diagrammtitel
Chart.Legend gibt ein ChartLegend zurück, dessen Position (ein LegendPosition von None, Bottom, Left, Right, Top oder TopRight) steuert, wo es relativ zum Plot-Bereich gerendert wird; LegendEntries ist ein ChartLegendEntryCollection einzelner ChartLegendEntry-Objekte, jedes mit eigenem Font und IsHidden-Flag zum Ausblenden einer einzelnen Serie aus der Legende, ohne sie aus dem Diagramm zu entfernen. Chart.DataTable (ein ChartDataTable) rendert die Serienwerte als Raster unterhalb des Diagramms, wenn Show gesetzt ist, wobei HasLegendKeys, HasHorizontalBorder, HasVerticalBorder und HasOutlineBorder das Aussehen steuern. Chart.Title ist ein ChartTitle mit Text- und Show-Eigenschaften und folgt dem gleichen Muster wie die Achsentitel.
Datenbeschriftungen, Datenpunkte und Marker
ChartSeries.HasDataLabels aktiviert Datenbeschriftungen für eine Serie, und ChartSeries.DataLabels (ein ChartDataLabelCollection) oder ein einzelnes ChartDataLabel davon steuert, was jede Beschriftung anzeigt: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey und ShowBubbleSize sind unabhängige Flags, und Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit und weitere) positioniert die Beschriftung relativ zu ihrem Punkt. ChartSeries.DataPoints bietet pro-Punkt-Zugriff über ChartDataPoint, das sein eigenes Marker (ein ChartMarker mit Symbol aus dem MarkerSymbol-Enum und einem Size), Explosion (zum Herausziehen eines Kuchensegments) und Format enthält. Jedes Diagrammelement, das gefüllt oder umrissen werden kann – Serien, Datenpunkte, Legende, Titel, Datentabelle – stellt über seine Format-Eigenschaft ein ChartFormat bereit, mit den Eigenschaften Fill, Stroke und ShapeType (ChartShapeType) sowie einer SetDefaultFill()-Methode zum Zurücksetzen. Ein Hinweis, der beachtet werden sollte: Die themenverbundenen Varianten von Füll- und Strichfarbe bei ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor und deren Tönungs-/Abschattungs-Gegenstücke) sind in dieser Ausgabe nicht implementiert – setzen Sie stattdessen einfache Fill/Stroke-Farben anstelle von Theme-Color-Referenzen. Chart.Style (ein ChartStyle wie Muted, Saturated, Gradient, Outline oder Black) wendet in einem Schritt ein vordefiniertes Aussehen auf das gesamte Diagramm an.
Schnellstart
Aspose.Words FOSS für .NET ist über NuGet verfügbar:
dotnet add package Aspose.Words.FOSSUm stattdessen aus dem Quellcode zu bauen:
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
Fügen Sie dann Ihrer Anwendung eine Projektreferenz zu Aspose.Words.csproj hinzu. Sobald die Referenz vorhanden ist, erzeugt dies ein Liniendiagramm mit einer Serie und speichert es als 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");
Öffnen Sie chart.docx in Word und das Diagramm ist vollständig bearbeitbar – klicken Sie mit der rechten Maustaste darauf und wählen Sie „Daten bearbeiten“, um dieselben drei Kategorien und Werte wie oben angezeigt zu sehen.
Unterstützte Formate
| Format | Erweiterung | Lesen | Schreiben |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle Varianten) | (verschiedene) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Diagramme, die mit dem Chart API erstellt werden, sind OOXML-Zeichnungsobjekte, sodass sie über die oben genannten DOCX-Familienformate (DOCX, DOCM, DOTX, DOTM und Flat OPC) hinweg round-tripfähig sind. Diese Edition kann nicht nach PDF, XPS oder Bildern exportieren und nicht drucken, sodass kein Diagramm in ein Bitmap gerendert wird – das Diagramm bleibt ein lebendes, editierbares Objekt innerhalb der Word-Datei. Die zusätzlichen Formatkonverter, die aus dieser Edition entfernt wurden (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 und WordML), sind dieselben Subsysteme, die überall sonst in der Bibliothek ausgeschlossen sind, und nicht etwas Spezifisches für Diagramme.
Open Source & Lizenzierung
Aspose.Words FOSS für .NET wird unter der MIT-Lizenz veröffentlicht, kostenlos für kommerzielle und private Nutzung ohne Lizenzgebühren oder Weiterverbreitungsbeschränkungen. Der vollständige Quellcode, einschließlich der in diesem Beitrag erwähnten Diagrammklassen, ist auf GitHub im Aspose.Words FOSS für .NET Repository verfügbar.
