Úvod
Tento průvodce ukazuje, jak vytvořit nativní grafy Wordu pomocí Aspose.Words FOSS pro .NET — stejné kreslicí objekty, které Word sám vytváří při použití Insert > Chart — kompletně z kódu. Graf přidaný tímto způsobem není obrázek; jedná se o Chart objekt vložený do OOXML balíčku dokumentu, s modelem datových sérií, osami, legendou a tabulkou dat, kterou Word i po uložení souboru stále může otevřít a upravit. Tento příspěvek je detailním ponorem do toho Chart API: jak vytvořit graf, přidat data sérií a získat přístup k objektům os, legendy, popisků dat a formátování, které řídí jeho vykreslení.
Knihovna je licencována pod MIT a nemá žádné nativní závislosti. Cílí na .NET Standard 2.0, takže kód v tomto příspěvku běží beze změny na .NET Framework 4.6.2+ a .NET 6, 8 a 10. Nainstalujte ji pomocí NuGet, nebo ji sestavte ze zdrojového kódu — viz Rychlý start níže. Všechno, co je zde ukázáno, je stejný engine grafů, který používá komerční Aspose.Words pro .NET; tato edice zahrnuje kompletní model objektů grafu, ale ne rozvržení stránky ani vykreslování, takže pozice grafu na stránce se nepočítá a dokument nelze exportovat do PDF ani obrázku.
Co je součástí
Vytvoření grafu a přidání datové série
DocumentBuilder.InsertChart(chartType, width, height) vloží tvar grafu na aktuální pozici a vrátí Shape; jeho vlastnost Chart je vstupním bodem pro vše ostatní. Nově vložený graf již má výchozí sérii, takže většina kódu ji nejprve vymaže a přidá vlastní data pomocí Chart.Series, což je 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 má přetížení pro páry kategorie/hodnota (jak výše), páry X/Y, časové série a bublinové série s extra hodnotou velikosti. Na jednotlivém ChartSeries, Add(xValue), Add(xValue, yValue) a Add(xValue, yValue, bubbleSize) lze přidávat jednotlivé body, Insert umístí bod na zadaný index a Clear() / ClearValues() odstraňují data série, aniž by nutně odstraňovaly samotný objekt série.
Typy grafů a typy řad
ChartType — výčet předávaný do InsertChart — má zhruba 40 členů pokrývajících standardní rodiny grafů Wordu: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall a Funnel, plus vrstvené, procentuálně vrstvené a 3D varianty několika z nich (Bar3D, ColumnStacked, Area3DPercentStacked a tak dále).
Související, ale odlišný výčet, ChartSeriesType, se objevuje na ChartSeries.SeriesType a ChartSeriesGroup.SeriesType a popisuje typ jednotlivé řady nebo skupiny řad spíše než celý graf. Obsahuje stejné členy jako ChartType plus dva další — ParetoLine a RegionMap — které ChartType přímo neukazuje. ChartSeriesGroup je to, co umožňuje kombinované grafy: Chart.SeriesGroups (a ChartSeriesGroupCollection) obsahuje jednu skupinu pro každý typ řady v grafu, a každá skupina má svůj vlastní pár AxisX/AxisY a vlastnosti rozvržení jako Overlap, GapWidth, BubbleScale a DoughnutHoleSize.
Osy, mřížky a škálování
Chart.AxisX, AxisY a AxisZ (plus kolekce Axes) vracejí objekty ChartAxis. Každá osa má Type (ChartAxisType.Category, Series nebo Value), nastavení značek dělení (MajorTickMark, MinorTickMark — Cross, Inside, Outside nebo None), příznaky mřížky (HasMajorGridlines, HasMinorGridlines) a řízení jednotek (MajorUnit, MinorUnit a jejich *IsAuto protějšky). ChartAxis.Scaling vrací objekt AxisScaling, jehož Minimum a Maximum jsou hodnoty AxisBound — AxisBound.IsAuto uvádí, zda je mez vypočítána automaticky, a parametrizované konstruktory (AxisBound(value), AxisBound(datetime)) nastavují explicitní číselnou nebo datovou mez. Osa kategorie může být připevněna k textovým nebo časovým kategoriím prostřednictvím ChartAxis.CategoryType (AxisCategoryType.Automatic, Category nebo Time), a ChartAxis.Title odhaluje ChartAxisTitle se svými vlastními Text, Show a Font.
Legenda, datová tabulka a nadpis grafu
Chart.Legend vrací ChartLegend, jehož Position (a LegendPosition z None, Bottom, Left, Right, Top nebo TopRight) určuje, kde se vykresluje vzhledem k ploše grafu; LegendEntries je ChartLegendEntryCollection jednotlivých objektů ChartLegendEntry, z nichž každý má své vlastní Font a příznak IsHidden pro skrytí jedné řady v legendě bez odebrání z grafu. Chart.DataTable (a ChartDataTable) vykresluje hodnoty řad jako mřížku pod grafem, když je nastaveno Show, přičemž HasLegendKeys, HasHorizontalBorder, HasVerticalBorder a HasOutlineBorder řídí její vzhled. Chart.Title je ChartTitle s vlastnostmi Text a Show, následující stejný vzor jako názvy os.
Popisky dat, datové body a značky
ChartSeries.HasDataLabels zapíná popisky dat pro řadu a ChartSeries.DataLabels (a ChartDataLabelCollection) nebo jednotlivý ChartDataLabel z ní určuje, co každý popisek zobrazuje: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey a ShowBubbleSize jsou nezávislé příznaky a Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit a další) umisťuje popisek relativně k bodu. ChartSeries.DataPoints poskytuje přístup k jednotlivým bodům přes ChartDataPoint, který má vlastní Marker (a ChartMarker s Symbol z výčtu MarkerSymbol a Size), Explosion (pro vytažení plátku koláče) a Format. Každý prvek grafu, který může být vyplněn nebo obkreslen – řady, datové body, legenda, nadpis, datová tabulka – vystavuje ChartFormat přes svou vlastnost Format, s vlastnostmi Fill, Stroke a ShapeType (ChartShapeType) a metodou SetDefaultFill() pro jeho resetování. Jedna věc, kterou je dobré vědět: varianty výplně a barvy tahu spojené s motivem na ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor a jejich protějšky odstínů/tónů) nejsou v této edici implementovány – nastavte obyčejné barvy Fill/Stroke místo odkazů na barvu motivu. Chart.Style (a ChartStyle jako Muted, Saturated, Gradient, Outline nebo Black) použije předdefinovaný vzhled na celý graf v jednom kroku.
Rychlý start
Aspose.Words FOSS pro .NET je k dispozici prostřednictvím NuGet:
dotnet add package Aspose.Words.FOSSPro sestavení ze zdrojového kódu místo toho:
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
Poté přidejte referenci na projekt Aspose.Words.csproj z vaší aplikace. S referencí na místě tento kód vytvoří čárový graf s jednou řadou a uloží jej do 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");
Otevřete chart.docx ve Wordu a graf je plně upravitelný — klikněte na něj pravým tlačítkem a vyberte “Edit Data”, abyste viděli stejné tři kategorie a hodnoty uvedené výše.
Podporované formáty
| Formát | Přípona | Číst | Zapisovat |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (všechny varianty) | (různé) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Grafy vytvořené pomocí Chart API jsou objekty kreslení OOXML, takže procházejí napříč výše uvedenými formáty rodiny DOCX (DOCX, DOCM, DOTX, DOTM a Flat OPC). Tato edice neumí exportovat do PDF, XPS ani obrázků a neumí tisknout, takže nic neprovádí vykreslení grafu do bitmapy – graf zůstává živým, editovatelným objektem uvnitř souboru Word. Další konvertory formátů, které byly z této edice odstraněny (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 a WordML), jsou stejné subsystémy vyloučené jinde v knihovně, ne něco specifického pro grafy.
Open Source a licencování
Aspose.Words FOSS pro .NET je vydáno pod licencí MIT, zdarma pro komerční i osobní použití bez poplatků za autorská práva ani omezení šíření. Kompletní zdrojový kód, včetně tříd grafů zmíněných v tomto příspěvku, je dostupný na GitHub v Aspose.Words FOSS pro .NET úložišti.
