Wprowadzenie
Ten przewodnik pokazuje, jak tworzyć natywne wykresy Word przy użyciu Aspose.Words FOSS dla .NET — tych samych obiektów rysunkowych, które Word tworzy, gdy używasz Wstaw > Wykres — w pełni z kodu. Wykres dodany w ten sposób nie jest obrazem; jest to obiekt Chart osadzony w pakiecie OOXML dokumentu, z modelem serii danych, osiami, legendą i tabelą danych, które Word nadal może otworzyć i edytować po zapisaniu pliku. Ten wpis to dogłębne zanurzenie w API wykresu: jak utworzyć wykres, dodać dane serii i uzyskać dostęp do obiektów osi, legendy, etykiet danych i formatowania, które kontrolują jego renderowanie.
Biblioteka jest licencjonowana na licencji MIT i nie ma zależności natywnych. Celuje w .NET Standard 2.0, więc kod w tym wpisie działa niezmieniony na .NET Framework 4.6.2+ oraz .NET 6, 8 i 10. Zainstaluj ją za pomocą NuGet lub zbuduj ze źródeł — zobacz sekcję Szybki start poniżej. Wszystko, co tutaj pokazano, to ten sam silnik wykresów używany przez komercyjne Aspose.Words dla .NET; ta edycja zawiera pełny model obiektów wykresu, ale nie układ strony ani renderowanie, więc pozycja wykresu na stronie nie jest obliczana i dokument nie może być wyeksportowany do PDF ani obrazu.
Co jest w zestawie
Tworzenie wykresu i dodawanie serii danych
DocumentBuilder.InsertChart(chartType, width, height) wstawia kształt wykresu w bieżącej pozycji i zwraca Shape; jego właściwość Chart jest punktem wejścia dla wszystkiego innego. Nowo wstawiony wykres ma już domyślną serię, więc większość kodu najpierw ją usuwa i dodaje własne dane przez Chart.Series, czyli 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 ma przeciążenia dla par kategoria/wartość (jak wyżej), par wartości X/Y, serii datowanych oraz serii bąbelkowych z dodatkową wartością rozmiaru. Na pojedynczym ChartSeries, Add(xValue), Add(xValue, yValue) i Add(xValue, yValue, bubbleSize) można dołączać pojedyncze punkty, Insert umieszcza punkt pod określonym indeksem, a Clear() / ClearValues() usuwają dane serii, niekoniecznie usuwając sam obiekt serii.
Typy wykresów i typy serii
ChartType — wyliczenie przekazywane do InsertChart — zawiera około 40 elementów obejmujących standardowe rodziny wykresów Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall i Funnel, plus wersje skumulowane, skumulowane procentowo i 3D kilku z nich (Bar3D, ColumnStacked, Area3DPercentStacked i tak dalej).
Powiązane, lecz odrębne wyliczenie, ChartSeriesType, pojawia się w ChartSeries.SeriesType i ChartSeriesGroup.SeriesType i opisuje typ pojedynczej serii lub grupy serii, a nie wykresu jako całości. Zawiera te same elementy co ChartType plus dwa dodatkowe — ParetoLine i RegionMap — które ChartType nie udostępnia bezpośrednio. ChartSeriesGroup to element umożliwiający wykresy kombinowane: Chart.SeriesGroups (a ChartSeriesGroupCollection) przechowuje jedną grupę na każdy typ serii w wykresie, a każda grupa ma własną parę AxisX/AxisY oraz właściwości układu, takie jak Overlap, GapWidth, BubbleScale i DoughnutHoleSize.
Osie, linie siatki i skalowanie
Chart.AxisX, AxisY i AxisZ (plus kolekcja Axes) zwracają obiekty ChartAxis. Każda oś posiada Type (ChartAxisType.Category, Series lub Value), ustawienia znaczników podziałki (MajorTickMark, MinorTickMark — Cross, Inside, Outside lub None), flagi linii siatki (HasMajorGridlines, HasMinorGridlines) oraz kontrolę jednostek (MajorUnit, MinorUnit i ich odpowiedniki *IsAuto). ChartAxis.Scaling zwraca obiekt AxisScaling, którego Minimum i Maximum są wartościami AxisBound — AxisBound.IsAuto informuje, czy granica jest obliczana automatycznie, a konstruktory parametryzowane (AxisBound(value), AxisBound(datetime)) ustawiają explicite granicę numeryczną lub datową. Oś kategorii może być przypięta do kategorii tekstowych lub czasowych poprzez ChartAxis.CategoryType (AxisCategoryType.Automatic, Category lub Time), a ChartAxis.Title udostępnia ChartAxisTitle ze swoimi własnymi Text, Show i Font.
Legenda, tabela danych i tytuł wykresu
Chart.Legend zwraca ChartLegend, którego Position (a LegendPosition None, Bottom, Left, Right, Top lub TopRight) kontroluje, gdzie jest renderowany względem obszaru wykresu; LegendEntries to ChartLegendEntryCollection poszczególnych obiektów ChartLegendEntry, z których każdy ma własny Font oraz flagę IsHidden umożliwiającą ukrycie jednej serii w legendzie bez usuwania jej z wykresu. Chart.DataTable (a ChartDataTable) wyświetla wartości serii jako siatkę pod wykresem, gdy Show jest ustawione, przy czym HasLegendKeys, HasHorizontalBorder, HasVerticalBorder i HasOutlineBorder kontrolują jej wygląd. Chart.Title jest ChartTitle z właściwościami Text i Show, zgodnie z tym samym schematem co tytuły osi.
Etykiety danych, punkty danych i markery
ChartSeries.HasDataLabels włącza etykiety danych dla serii, a ChartSeries.DataLabels (a ChartDataLabelCollection) lub pojedynczy ChartDataLabel z niej kontroluje, co każda etykieta wyświetla: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey i ShowBubbleSize są niezależnymi flagami, a Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit i inne) umieszcza etykietę względem jej punktu. ChartSeries.DataPoints zapewnia dostęp do poszczególnych punktów poprzez ChartDataPoint, który posiada własny Marker (a ChartMarker z Symbol z wyliczenia MarkerSymbol oraz Size), Explosion (do wydobycia fragmentu koła) i Format. Każdy element wykresu, który może być wypełniony lub obrysowany — serie, punkty danych, legenda, tytuł, tabela danych — udostępnia ChartFormat poprzez swoją właściwość Format, z właściwościami Fill, Stroke i ShapeType (ChartShapeType) oraz metodą SetDefaultFill() do jej resetowania. Jedna uwaga warta poznania: warianty wypełnienia i koloru obrysu powiązane z motywem w ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor i ich odpowiedniki odcieni) nie są zaimplementowane w tej edycji — ustaw zwykłe kolory Fill/Stroke zamiast odwołań do kolorów motywu. Chart.Style (a ChartStyle taki jak Muted, Saturated, Gradient, Outline lub Black) nakłada predefiniowany wygląd na cały wykres w jednym kroku.
Szybki start
Aspose.Words FOSS dla .NET jest dostępny poprzez NuGet:
dotnet add package Aspose.Words.FOSSAby zbudować ze źródeł:
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
Następnie dodaj odwołanie do projektu Aspose.Words.csproj z aplikacji. Po dodaniu odwołania, to tworzy wykres liniowy z jedną serią i zapisuje go 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");
Otwórz chart.docx w Wordzie, a wykres będzie w pełni edytowalny — kliknij go prawym przyciskiem i wybierz “Edit Data”, aby zobaczyć te same trzy kategorie i wartości wymienione powyżej.
Obsługiwane formaty
| Format | Rozszerzenie | Odczyt | Zapis |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (wszystkie warianty) | (różne) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Wykresy tworzone przy użyciu Chart API są obiektami rysunków OOXML, więc zachowują się w formatach rodziny DOCX wymienionych powyżej (DOCX, DOCM, DOTX, DOTM i Flat OPC). Ta edycja nie może eksportować do PDF, XPS ani obrazów i nie może drukować, więc nic nie renderuje wykresu do bitmapy — wykres pozostaje żywym, edytowalnym obiektem wewnątrz pliku Word. Dodatkowe konwertery formatów usunięte z tej edycji (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 i WordML) są tymi samymi podsystemami wykluczonymi wszędzie w bibliotece, a nie czymś specyficznym dla wykresów.
Open Source i licencjonowanie
Aspose.Words FOSS dla .NET jest wydany na licencji MIT, darmowy do użytku komercyjnego i prywatnego bez opłat licencyjnych ani ograniczeń w dystrybucji. Pełne źródło, w tym klasy wykresów wymienione w tym poście, jest dostępne na GitHub w Aspose.Words FOSS dla .NET repozytorium.
