Introducere
Acest ghid arată cum să construiți diagrame native Word cu Aspose.Words FOSS pentru .NET — aceleași obiecte de desen pe care Word le creează când utilizați Inserare > Diagramă — integral din cod. O diagramă adăugată în acest mod nu este o imagine; este un obiect Chart încorporat în pachetul OOXML al documentului, cu un model de serie de date, axe, o legendă și un tabel de date pe care Word îl poate deschide și edita și după ce fișierul este salvat. Această postare este o analiză aprofundată a acelui Chart API: cum să creați o diagramă, să adăugați date de serie și să accesați obiectele de axă, legendă, etichetă de date și formatare care controlează modul în care este redată.
Biblioteca este licențiată sub MIT și nu are dependențe native. Vizează .NET Standard 2.0, astfel încât codul din această postare rulează neschimbat pe .NET Framework 4.6.2+ și .NET 6, 8 și 10. Instalați-o prin NuGet, sau construiți-o din sursă — vedeți Începe rapid mai jos. Tot ce este prezentat aici este același motor de diagrame utilizat de Aspose.Words comercial pentru .NET; această ediție include modelul complet de obiecte de diagramă, dar nu și aspectul paginii sau redarea, astfel încât poziția diagramei pe pagină nu este calculată și documentul nu poate fi exportat în PDF sau imagine.
Ce este inclus
Crearea unei diagrame și adăugarea unei serii de date
DocumentBuilder.InsertChart(chartType, width, height) inserează o formă de diagramă la poziția curentă și returnează un Shape; proprietatea sa Chart este punctul de intrare pentru tot restul. O diagramă inserată recent are deja o serie implicită, astfel că majoritatea codului o curăță mai întâi și adaugă propriile date prin 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 are supraîncărcări pentru perechi categorie/valoare (ca mai sus), perechi X/Y, serii datate și serii de bule cu o valoare suplimentară de dimensiune. Pe un ChartSeries individual, Add(xValue), Add(xValue, yValue) și Add(xValue, yValue, bubbleSize) adaugă puncte individuale, Insert plasează un punct la un index dat, iar Clear() / ClearValues() elimină datele seriei fără a elimina neapărat obiectul seriei în sine.
Tipuri de diagrame și tipuri de serii
ChartType — enumul transmis către InsertChart — are aproximativ 40 de membri care acoperă familiile standard de diagrame Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall și Funnel, plus variante stivuite, procentual-stivuite și 3D ale mai multora dintre ele (Bar3D, ColumnStacked, Area3DPercentStacked și altele).
Un enum înrudit, dar distinct, ChartSeriesType, apare pe ChartSeries.SeriesType și ChartSeriesGroup.SeriesType și descrie tipul unei serii individuale sau al unui grup de serii, mai degrabă decât al diagramei în ansamblu. Acesta conține aceiași membri ca ChartType plus încă doi — ParetoLine și RegionMap — pe care ChartType nu îi expune direct. ChartSeriesGroup este ceea ce face posibilă crearea diagramelor combinate: Chart.SeriesGroups (un ChartSeriesGroupCollection) conține un grup pentru fiecare tip de serie în diagramă, iar fiecare grup are propriul său cuplu AxisX/AxisY și proprietăți de aranjament precum Overlap, GapWidth, BubbleScale și DoughnutHoleSize.
Axe, linii de grilă și scalare
Chart.AxisX, AxisY și AxisZ (plus colecția Axes) returnează obiecte ChartAxis. Fiecare axă are un Type (ChartAxisType.Category, Series sau Value), setări pentru marcajele de scară (MajorTickMark, MinorTickMark — Cross, Inside, Outside sau None), flaguri pentru liniile de grilă (HasMajorGridlines, HasMinorGridlines) și control al unității (MajorUnit, MinorUnit și omologii lor *IsAuto). ChartAxis.Scaling returnează un obiect AxisScaling al cărui Minimum și Maximum sunt valori AxisBound — AxisBound.IsAuto indică dacă limita este calculată automat, iar constructorii parametrizați (AxisBound(value), AxisBound(datetime)) stabilesc o limită numerică sau de dată explicită. O axă de tip categorie poate fi fixată la categorii text sau timp prin ChartAxis.CategoryType (AxisCategoryType.Automatic, Category sau Time), iar ChartAxis.Title expune un ChartAxisTitle cu propriile sale Text, Show și Font.
Legendă, tabel de date și titlu diagramă
Chart.Legend returnează un ChartLegend, al cărui Position (un LegendPosition de None, Bottom, Left, Right, Top sau TopRight) controlează locul în care este redat relativ la zona de graficare; LegendEntries este un ChartLegendEntryCollection de obiecte ChartLegendEntry individuale, fiecare având propriul său Font și flagul IsHidden pentru ascunderea unei singure serii din legendă fără a o elimina din diagramă. Chart.DataTable (un ChartDataTable) redă valorile seriilor sub formă de grilă sub diagramă când Show este activat, cu HasLegendKeys, HasHorizontalBorder, HasVerticalBorder și HasOutlineBorder controlând aspectul său. Chart.Title este un ChartTitle cu proprietăți Text și Show, urmând același model ca titlurile axelor.
Etichete de date, puncte de date și marcatori
ChartSeries.HasDataLabels activează etichetele de date pentru o serie, iar ChartSeries.DataLabels (un ChartDataLabelCollection) sau un ChartDataLabel individual din aceasta controlează ce afișează fiecare etichetă: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey și ShowBubbleSize sunt semnale independente, și Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit și altele) poziționează eticheta în raport cu punctul său. ChartSeries.DataPoints oferă acces per punct prin ChartDataPoint, care are propriul său Marker (un ChartMarker cu Symbol din enum-ul MarkerSymbol și un Size), Explosion (pentru extragerea unei felii de plăcintă) și Format. Fiecare element de diagramă care poate fi umplut sau conturat — serii, puncte de date, legenda, titlul, tabelul de date — expune un ChartFormat prin proprietatea sa Format, cu proprietățile Fill, Stroke și ShapeType (ChartShapeType) și o metodă SetDefaultFill() pentru a-l reseta. Un aspect de reținut: variantele legate de temă ale culorii de umplere și contur pe ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor și omologii lor de nuanță/umbră) nu sunt implementate în această ediție — setați culori simple Fill/Stroke în loc de referințe la culori de temă. Chart.Style (un ChartStyle cum ar fi Muted, Saturated, Gradient, Outline sau Black) aplică un aspect predefinit întregii diagrame într-un singur pas.
Începe rapid
Aspose.Words FOSS pentru .NET este disponibil prin NuGet:
dotnet add package Aspose.Words.FOSSPentru a compila din sursă în schimb:
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
Adăugați apoi o referință de proiect la Aspose.Words.csproj din aplicația dumneavoastră. Odată ce referința este în loc, aceasta creează un grafic liniar cu o singură serie și îl salvează în 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");
Deschideți chart.docx în Word și graficul este complet editabil — faceți clic dreapta pe el și alegeți „Edit Data” pentru a vedea aceleași trei categorii și valori scrise mai sus.
Formate acceptate
| Format | Extensie | Citire | Scriere |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (toate variantele) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Graficele construite cu Chart API sunt obiecte de desen OOXML, astfel încât pot fi transferate în mod round-trip între formatele din familia DOCX de mai sus (DOCX, DOCM, DOTX, DOTM și Flat OPC). Această ediție nu poate exporta în PDF, XPS sau imagini și nu poate tipări, astfel că nimic nu redă un grafic într-un bitmap — graficul rămâne un obiect viu, editabil în interiorul fișierului Word. Conversoarele de format suplimentare eliminate din această ediție (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 și WordML) sunt aceleași subsisteme excluse în alte părți ale bibliotecii, nu ceva specific graficelor.
Open Source și Licențiere
Aspose.Words FOSS pentru .NET este lansat sub licența MIT, gratuit pentru utilizare comercială și personală fără redevențe sau restricții de redistribuire. Codul sursă complet, inclusiv clasele de grafice menționate în acest articol, este disponibil pe GitHub în Aspose.Words FOSS pentru .NET repository.
