Introduzione
Questa guida mostra come creare grafici Word nativi con Aspose.Words FOSS per .NET — gli stessi oggetti di disegno che Word crea quando si utilizza Inserisci > Grafico — interamente tramite codice. Un grafico aggiunto in questo modo non è un’immagine; è un oggetto Chart incorporato nel pacchetto OOXML del documento, con un modello di serie di dati, assi, una legenda e una tabella dati che Word può ancora aprire e modificare dopo che il file è stato salvato. Questo post è un’analisi approfondita di quel Chart API: come creare un grafico, aggiungere dati di serie e accedere agli oggetti asse, legenda, etichetta dati e formattazione che controllano il suo rendering.
La libreria è rilasciata con licenza MIT e non ha dipendenze native. Mira a .NET Standard 2.0, quindi il codice di questo post viene eseguito invariato su .NET Framework 4.6.2+ e .NET 6, 8 e 10. Installala tramite NuGet, o compilala dal sorgente — vedi Avvio rapido sotto. Tutto ciò che è mostrato qui è lo stesso motore di grafici usato dal commerciale Aspose.Words per .NET; questa edizione include l’intero modello di oggetti del grafico ma non il layout di pagina o il rendering, quindi la posizione del grafico nella pagina non viene calcolata e il documento non può essere esportato in PDF o in immagine.
Cosa è incluso
Creare un grafico e aggiungere una serie di dati
DocumentBuilder.InsertChart(chartType, width, height) inserisce una forma di grafico nella posizione corrente e restituisce un Shape; la sua proprietà Chart è il punto di ingresso per tutto il resto. Un grafico appena inserito ha già una serie predefinita, quindi la maggior parte del codice la elimina prima e aggiunge i propri dati tramite Chart.Series, un 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 dispone di overload per coppie categoria/valore (come sopra), coppie X/Y, serie datate e serie a bolle con un valore di dimensione aggiuntivo. Su un singolo ChartSeries, Add(xValue), Add(xValue, yValue) e Add(xValue, yValue, bubbleSize) aggiungono punti singoli, Insert posiziona un punto a un indice specifico, e Clear() / ClearValues() rimuovono i dati della serie senza necessariamente rimuovere l’oggetto serie stesso.
Tipi di grafico e tipi di serie
ChartType — l’enumerazione passata a InsertChart — ha circa 40 membri che coprono le famiglie standard di grafici Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall e Funnel, più le varianti impilate, impilate in percentuale e 3D di diverse di esse (Bar3D, ColumnStacked, Area3DPercentStacked, e così via).
Un enum correlato ma distinto, ChartSeriesType, compare su ChartSeries.SeriesType e ChartSeriesGroup.SeriesType e descrive il tipo di una singola serie o di un gruppo di serie piuttosto che del grafico nel suo complesso. Possiede gli stessi membri di ChartType più due aggiuntivi — ParetoLine e RegionMap — che ChartType non espone direttamente. ChartSeriesGroup è ciò che rende possibili i grafici combinati: Chart.SeriesGroups (un ChartSeriesGroupCollection) contiene un gruppo per tipo di serie nel grafico, e ogni gruppo ha la propria coppia AxisX/AxisY e proprietà di layout come Overlap, GapWidth, BubbleScale e DoughnutHoleSize.
Assi, linee della griglia e scala
Chart.AxisX, AxisY e AxisZ (oltre alla collezione Axes) restituiscono oggetti ChartAxis. Ogni asse ha un Type (ChartAxisType.Category, Series o Value), impostazioni dei segnapunti (MajorTickMark, MinorTickMark — Cross, Inside, Outside o None), flag delle linee della griglia (HasMajorGridlines, HasMinorGridlines) e controllo dell’unità (MajorUnit, MinorUnit e le loro controparti *IsAuto). ChartAxis.Scaling restituisce un oggetto AxisScaling il cui Minimum e Maximum sono valori AxisBound — AxisBound.IsAuto indica se il limite è calcolato automaticamente, e i costruttori parametrizzati (AxisBound(value), AxisBound(datetime)) impostano un limite numerico o di data esplicito. Un asse di categoria può essere fissato a categorie di testo o di tempo tramite ChartAxis.CategoryType (AxisCategoryType.Automatic, Category o Time), e ChartAxis.Title espone un ChartAxisTitle con i propri Text, Show e Font.
Legenda, tabella dati e titolo del grafico
Chart.Legend restituisce un ChartLegend, il cui Position (un LegendPosition di None, Bottom, Left, Right, Top o TopRight) controlla dove viene renderizzata rispetto all’area del grafico; LegendEntries è un ChartLegendEntryCollection di singoli oggetti ChartLegendEntry, ognuno con il proprio Font e flag IsHidden per nascondere una singola serie dalla legenda senza rimuoverla dal grafico. Chart.DataTable (un ChartDataTable) visualizza i valori delle serie come una griglia sotto il grafico quando Show è impostato, con HasLegendKeys, HasHorizontalBorder, HasVerticalBorder e HasOutlineBorder che controllano il suo aspetto. Chart.Title è un ChartTitle con proprietà Text e Show, seguendo lo stesso modello dei titoli degli assi.
Etichette dati, punti dati e marcatori
ChartSeries.HasDataLabels attiva le etichette dati per una serie, e ChartSeries.DataLabels (un ChartDataLabelCollection) o un singolo ChartDataLabel da essa controlla ciò che ogni etichetta mostra: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey e ShowBubbleSize sono flag indipendenti, e Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit e altri) posiziona l’etichetta rispetto al suo punto. ChartSeries.DataPoints fornisce accesso per punto tramite ChartDataPoint, che possiede il proprio Marker (un ChartMarker con Symbol dall’enum MarkerSymbol e un Size), Explosion (per estrarre una fetta di torta) e Format. Ogni elemento del grafico che può essere riempito o contornato — serie, punti dati, legenda, titolo, tabella dati — espone un ChartFormat tramite la sua proprietà Format, con le proprietà Fill, Stroke e ShapeType (ChartShapeType) e un metodo SetDefaultFill() per resettarlo. Un avvertimento da conoscere: le varianti collegate al tema di colore di riempimento e di tratto su ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor e i loro corrispondenti tinta/ombra) non sono implementate in questa edizione — impostare colori Fill/Stroke semplici invece di riferimenti a colori di tema. Chart.Style (un ChartStyle come Muted, Saturated, Gradient, Outline o Black) applica un aspetto predefinito all’intero grafico in un unico passaggio.
Avvio rapido
Aspose.Words FOSS per .NET è disponibile tramite NuGet:
dotnet add package Aspose.Words.FOSSPer compilare dal sorgente invece:
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
Quindi aggiungi un riferimento di progetto a Aspose.Words.csproj dalla tua applicazione. Con il riferimento in posizione, questo crea un grafico a linee con una serie e lo salva in 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");
Apri chart.docx in Word e il grafico è completamente modificabile — fai clic con il pulsante destro e scegli “Modifica dati” per vedere le stesse tre categorie e i valori scritti sopra.
Formati supportati
| Formato | Estensione | Leggi | Scrivi |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (tutte le varianti) | (vari) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
I grafici creati con il Chart API sono oggetti di disegno OOXML, quindi possono essere trasferiti senza perdita tra i formati della famiglia DOCX sopra (DOCX, DOCM, DOTX, DOTM e Flat OPC). Questa edizione non può esportare in PDF, XPS o immagini e non può stampare, quindi nulla rende un grafico in una bitmap — il grafico resta un oggetto vivo e modificabile all’interno del file Word. I convertitori di formato aggiuntivi rimossi da questa edizione (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 e WordML) sono gli stessi sottosistemi esclusi in tutti gli altri punti della libreria, non qualcosa di specifico per i grafici.
Open Source e Licenze
Aspose.Words FOSS per .NET è rilasciato sotto licenza MIT, gratuito per uso commerciale e personale senza royalty o restrizioni di redistribuzione. Il codice sorgente completo, incluse le classi dei grafici citate in questo post, è disponibile su GitHub nel Aspose.Words FOSS per .NET repository.
