Inleiding
Deze gids laat zien hoe je native Word-grafieken bouwt met Aspose.Words FOSS voor .NET — dezelfde tekenobjecten die Word zelf maakt wanneer je Invoegen > Grafiek gebruikt — volledig vanuit code. Een op deze manier toegevoegde grafiek is geen afbeelding; het is een Chart object ingebed in het OOXML-pakket van het document, met een gegevensreeksmodel, assen, een legenda en een gegevenstabel die Word nog steeds kan openen en bewerken nadat het bestand is opgeslagen. Dit bericht is een diepgaande duik in die Chart API: hoe je een grafiek maakt, reeksen toevoegt, en de as-, legenda-, gegevenslabel- en opmaakobjecten bereikt die bepalen hoe deze wordt gerenderd.
De bibliotheek is MIT-gelicentieerd en heeft geen native afhankelijkheden. Hij richt zich op .NET Standard 2.0, zodat de code in dit bericht ongewijzigd draait op .NET Framework 4.6.2+ en .NET 6, 8 en 10. Installeer hem via NuGet, of bouw hem vanuit de bron — zie Snelstart hieronder. Alles wat hier wordt getoond is dezelfde grafiekengine die wordt gebruikt door de commerciële Aspose.Words voor .NET; deze editie bevat het volledige grafiekobjectmodel maar niet paginalay-out of rendering, zodat de positie van een grafiek op de pagina niet wordt berekend en het document niet kan worden geëxporteerd naar PDF of een afbeelding.
Wat er inbegrepen is
Een grafiek maken en een gegevensreeks toevoegen
DocumentBuilder.InsertChart(chartType, width, height) voegt een grafiekvorm in op de huidige positie in en retourneert een Shape; zijn Chart eigenschap is het toegangspunt voor alles andere. Een nieuw ingevoegde grafiek heeft al een standaardreeks, dus de meeste code wist die eerst en voegt eigen gegevens toe via Chart.Series, een 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 heeft overloads voor categorie/waarde-paren (zoals hierboven), X/Y-waardeparen, datumreeksen en bubbelreeksen met een extra groottewaarde. Op een individuele ChartSeries, Add(xValue), Add(xValue, yValue) en Add(xValue, yValue, bubbleSize) kun je enkele punten toevoegen, Insert plaatst een punt op een gegeven index, en Clear() / ClearValues() verwijderen seriedata zonder noodzakelijkerwijs het serie-object zelf te verwijderen.
Grafiektype en serietypen
ChartType — de enum die wordt doorgegeven aan InsertChart — heeft ongeveer 40 leden die de standaard Word-grafiekfamilies dekken: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall en Funnel, plus gestapelde, procentueel gestapelde en 3D-varianten van verschillende daarvan (Bar3D, ColumnStacked, Area3DPercentStacked, enzovoort).
Een verwante maar aparte enum, ChartSeriesType, verschijnt op ChartSeries.SeriesType en ChartSeriesGroup.SeriesType en beschrijft het type van een individuele serie of seriegroep in plaats van de grafiek als geheel. Hij bevat dezelfde leden als ChartType plus twee extra — ParetoLine en RegionMap — die ChartType niet direct blootlegt. ChartSeriesGroup is wat combo-grafieken mogelijk maakt: Chart.SeriesGroups (een ChartSeriesGroupCollection) bevat één groep per serietype in de grafiek, en elke groep heeft zijn eigen AxisX/AxisY-paar en layouteigenschappen zoals Overlap, GapWidth, BubbleScale en DoughnutHoleSize.
Assen, rasterlijnen en schaalverdeling
Chart.AxisX, AxisY en AxisZ (plus de Axes collectie) retourneren ChartAxis-objecten. Elke as heeft een Type (ChartAxisType.Category, Series of Value), instellingen voor tick-markeringen (MajorTickMark, MinorTickMark — Cross, Inside, Outside of None), rasterlijn-vlaggen (HasMajorGridlines, HasMinorGridlines) en eenheid-controle (MajorUnit, MinorUnit en hun *IsAuto-tegenhangers). ChartAxis.Scaling retourneert een AxisScaling-object waarvan de Minimum en Maximum AxisBound-waarden zijn — AxisBound.IsAuto geeft aan of de grens automatisch wordt berekend, en de geparameteriseerde constructors (AxisBound(value), AxisBound(datetime)) stellen een expliciete numerieke of datumgrens in. Een categorische as kan worden vastgezet op tekst- of tijdcategorieën via ChartAxis.CategoryType (AxisCategoryType.Automatic, Category of Time), en ChartAxis.Title onthult een ChartAxisTitle met zijn eigen Text, Show en Font.
Legenda, datatabel en grafiektitel
Chart.Legend retourneert een ChartLegend, waarvan de Position (een LegendPosition van None, Bottom, Left, Right, Top of TopRight) bepaalt waar deze wordt gerenderd ten opzichte van het plotgebied; LegendEntries is een ChartLegendEntryCollection van individuele ChartLegendEntry-objecten, elk met zijn eigen Font en IsHidden-vlag om een enkele serie uit de legenda te verbergen zonder deze uit de grafiek te verwijderen. Chart.DataTable (een ChartDataTable) rendert de seriewaarden als een raster onder de grafiek wanneer Show is ingesteld, met HasLegendKeys, HasHorizontalBorder, HasVerticalBorder en HasOutlineBorder die het uiterlijk regelen. Chart.Title is een ChartTitle met Text en Show-eigenschappen, volgens hetzelfde patroon als de as-titels.
Gegevenslabels, gegevenspunten en markeringen
ChartSeries.HasDataLabels schakelt gegevenslabels in voor een serie, en ChartSeries.DataLabels (een ChartDataLabelCollection) of een individuele ChartDataLabel ervan bepaalt wat elk label toont: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey, en ShowBubbleSize zijn onafhankelijke vlaggen, en Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit, en andere) plaatst het label relatief ten opzichte van zijn punt. ChartSeries.DataPoints biedt per-punt toegang via ChartDataPoint, die zijn eigen Marker bevat (een ChartMarker met Symbol uit de MarkerSymbol enum en een Size), Explosion (voor het uittrekken van een taartpunt), en Format. Elk grafiekelement dat kan worden gevuld of omlijnd — series, gegevenspunten, de legenda, de titel, de gegevenstabel — biedt een ChartFormat via zijn Format eigenschap, met Fill, Stroke, en ShapeType (ChartShapeType) eigenschappen en een SetDefaultFill() methode om het te resetten. Een kanttekening die het waard is te weten: de thema-gekoppelde varianten van vul- en lijnkleur op ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor, en hun tint-/schaduw-tegenhangers) zijn niet geïmplementeerd in deze editie — stel gewone Fill/Stroke kleuren in plaats van thema-kleurreferenties. Chart.Style (een ChartStyle zoals Muted, Saturated, Gradient, Outline, of Black) past in één stap een vooraf gedefinieerde look toe op het gehele diagram.
Snelstart
Aspose.Words FOSS voor .NET is beschikbaar via NuGet:
dotnet add package Aspose.Words.FOSSOm in plaats daarvan vanuit de bron te bouwen:
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
Voeg vervolgens een projectreferentie naar Aspose.Words.csproj toe vanuit uw applicatie. Met de referentie op zijn plaats, maakt dit een lijndiagram met één serie en slaat het op 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");
Open chart.docx in Word en de grafiek is volledig bewerkbaar — klik er met de rechtermuisknop op en kies “Gegevens bewerken” om dezelfde drie categorieën en waarden te zien die hierboven zijn geschreven.
Ondersteunde formaten
| Formaat | Extensie | Lezen | Schrijven |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alle varianten) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Grafieken die zijn gemaakt met de Chart API zijn OOXML-tekenobjecten, zodat ze heen en weer kunnen worden verwerkt in de bovengenoemde DOCX-familieformaten (DOCX, DOCM, DOTX, DOTM en Flat OPC). Deze editie kan niet exporteren naar PDF, XPS of afbeeldingen en kan niet afdrukken, zodat er niets een grafiek naar een bitmap rendert — de grafiek blijft een live, bewerkbaar object binnen het Word-bestand. De extra formaatconverters die uit deze editie zijn verwijderd (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 en WordML) zijn dezelfde subsystemen die overal elders in de bibliotheek zijn uitgesloten, en geen specifieke beperking voor grafieken.
Open source & licenties
Aspose.Words FOSS voor .NET wordt uitgebracht onder de MIT-licentie, gratis voor commercieel en persoonlijk gebruik zonder royalty’s of beperkingen op herdistributie. De volledige broncode, inclusief de in dit bericht genoemde chart-klassen, is beschikbaar op GitHub in de Aspose.Words FOSS voor .NET repository.
