Introduktion
Denna guide visar hur man bygger inbyggda Word-diagram med Aspose.Words FOSS för .NET — samma ritobjekt som Word själv skapar när du använder Infoga > Diagram — helt från kod. Ett diagram som läggs till på detta sätt är inte en bild; det är ett Chart-objekt som är inbäddat i dokumentets OOXML-paket, med en dataseriemodell, axlar, en legend och en datatabell som Word fortfarande kan öppna och redigera efter att filen sparats. Detta inlägg är en djupdykning i den Diagram API: hur man skapar ett diagram, lägger till seriedata och når axel-, legend-, datamärkes- och formateringsobjekten som styr hur det renderas.
Biblioteket har MIT-licens och har inga inhemska beroenden. Det riktar sig mot .NET Standard 2.0, så koden i detta inlägg körs oförändrad på .NET Framework 4.6.2+ och .NET 6, 8 och 10. Installera det via NuGet, eller bygg det från källkod — se Snabbstart nedan. Allt som visas här är samma diagrammotor som används av den kommersiella Aspose.Words för .NET; denna utgåva innehåller hela diagramobjektmodellen men inte sidlayout eller rendering, så diagrammets position på sidan beräknas inte och dokumentet kan inte exporteras till PDF eller en bild.
Vad som ingår
Skapa ett diagram och lägga till en dataserie
DocumentBuilder.InsertChart(chartType, width, height) infogar en diagramform på den aktuella positionen och returnerar en Shape; dess Chart-egenskap är ingångspunkten för allt annat. Ett nyinfogat diagram har redan en standardserie, så de flesta kod rensar den först och lägger till egen data via Chart.Series, en 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 har överlagringar för kategori/värde-par (som ovan), X/Y-värde-par, daterade serier och bubbelseerier med ett extra storleksvärde. På en enskild ChartSeries, Add(xValue), Add(xValue, yValue) och Add(xValue, yValue, bubbleSize) läggs enstaka punkter till, Insert placerar en punkt på ett givet index, och Clear() / ClearValues() tar bort seriedata utan nödvändigtvis att ta bort serieobjektet självt.
Diagramtyper och Serietyper
ChartType — enumen som skickas till InsertChart — har cirka 40 medlemmar som täcker de standardiserade Word-diagramfamiljerna: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall och Funnel, samt staplade, procentstaplade och 3D-varianter av flera av dem (Bar3D, ColumnStacked, Area3DPercentStacked och så vidare).
En relaterad men distinkt enum, ChartSeriesType, visas på ChartSeries.SeriesType och ChartSeriesGroup.SeriesType och beskriver typen av en enskild serie eller serieguppe snarare än diagrammet som helhet. Den har samma medlemmar som ChartType plus två till — ParetoLine och RegionMap — som ChartType inte exponerar direkt. ChartSeriesGroup är det som möjliggör kombinationsdiagram: Chart.SeriesGroups (en ChartSeriesGroupCollection) innehåller en grupp per serietyp i diagrammet, och varje grupp har sitt eget AxisX/AxisY-par samt layout-egenskaper såsom Overlap, GapWidth, BubbleScale och DoughnutHoleSize.
Axlar, Rutnätlinjer och Skalning
Chart.AxisX, AxisY och AxisZ (plus Axes-samlingen) returnerar ChartAxis-objekt. Varje axel har en Type (ChartAxisType.Category, Series eller Value), inställningar för staplar (MajorTickMark, MinorTickMark — Cross, Inside, Outside eller None), flaggor för rutnätlinjer (HasMajorGridlines, HasMinorGridlines) och enhetskontroll (MajorUnit, MinorUnit samt deras *IsAuto-motsvarigheter). ChartAxis.Scaling returnerar ett AxisScaling-objekt vars Minimum och Maximum är AxisBound-värden — AxisBound.IsAuto visar om gränsen beräknas automatiskt, och de parametriserade konstruktorerna (AxisBound(value), AxisBound(datetime)) anger en explicit numerisk eller datumgräns. En kategori-axel kan fästas på text- eller tidskategorier via ChartAxis.CategoryType (AxisCategoryType.Automatic, Category eller Time), och ChartAxis.Title exponerar en ChartAxisTitle med sina egna Text, Show och Font.
Legenda, Datatabell och Diagramtitel
Chart.Legend returnerar en ChartLegend, vars Position (en LegendPosition av None, Bottom, Left, Right, Top eller TopRight) styr var den renderas i förhållande till plotområdet; LegendEntries är en ChartLegendEntryCollection av enskilda ChartLegendEntry-objekt, var och en med sin egen Font och IsHidden-flagga för att dölja en enskild serie i legenden utan att ta bort den från diagrammet. Chart.DataTable (en ChartDataTable) renderar serievärdena som ett rutnät under diagrammet när Show är satt, med HasLegendKeys, HasHorizontalBorder, HasVerticalBorder och HasOutlineBorder som styr dess utseende. Chart.Title är en ChartTitle med Text och Show-egenskaper, enligt samma mönster som axeltitlarna.
Datamärkningar, Datapunkter och Markörer
ChartSeries.HasDataLabels slår på datamärkningar för en serie, och ChartSeries.DataLabels (en ChartDataLabelCollection) eller en enskild ChartDataLabel från den styr vad varje etikett visar: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey och ShowBubbleSize är oberoende flaggor, och Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit och andra) placerar etiketten relativt till dess punkt. ChartSeries.DataPoints ger åtkomst per punkt via ChartDataPoint, som har sin egen Marker (en ChartMarker med Symbol från MarkerSymbol-enumet och en Size), Explosion (för att dra ut en pajskiva) och Format. Varje diagramobjekt som kan fyllas eller kontureras — serier, datapunkter, legenden, titeln, datatabellen — exponerar en ChartFormat via sin Format-egenskap, med Fill, Stroke och ShapeType (ChartShapeType) egenskaper samt en SetDefaultFill()-metod för att återställa den. En sak att känna till: de temalänkade varianterna av fyllnings- och linjefärg på ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor och deras nyans-/skuggtillägg) är inte implementerade i denna version — ange enkla Fill/Stroke-färger istället för temafärgreferenser. Chart.Style (en ChartStyle såsom Muted, Saturated, Gradient, Outline eller Black) applicerar ett fördefinierat utseende på hela diagrammet i ett steg.
Snabbstart
Aspose.Words FOSS för .NET är tillgänglig via NuGet:
dotnet add package Aspose.Words.FOSSFör att bygga från källkod istället:
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
Lägg sedan till en projektreferens till Aspose.Words.csproj från din applikation. När referensen är på plats skapar detta ett linjediagram med en serie och sparar det som 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");
Öppna chart.docx i Word så är diagrammet fullt redigerbart — högerklicka på det och välj “Edit Data” för att se samma tre kategorier och värden som skrivits ovan.
Supportade format
| Format | Filändelse | Läs | Skriv |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (alla varianter) | (olika) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Diagram som byggts med Chart API är OOXML-ritobjekt, så de kan gå fram och tillbaka mellan DOCX-familjens format ovan (DOCX, DOCM, DOTX, DOTM och Flat OPC). Denna utgåva kan inte exportera till PDF, XPS eller bilder och kan inte skriva ut, så inget renderar ett diagram till en bitmap – diagrammet förblir ett levande, redigerbart objekt i Word-filen. De extra formatkonverterarna som har tagits bort från denna utgåva (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 och WordML) är samma delsystem som exkluderas överallt annars i biblioteket, inte något som är specifikt för diagram.
Öppen källkod & licensiering
Aspose.Words FOSS för .NET är släppt under MIT-licensen, gratis för kommersiell och personlig användning utan royalties eller restriktioner för vidaredistribution. Den fullständiga källkoden, inklusive de diagramklasser som refereras i detta inlägg, finns tillgänglig på GitHub i Aspose.Words FOSS för .NET-arkivet.
