Bevezetés
Ez az útmutató bemutatja, hogyan lehet natív Word-diagramokat építeni a Aspose.Words FOSS használatával a .NET számára — ugyanazokat a rajzobjektumokat, amelyeket a Word maga hoz létre az Insert > Chart (Beszúrás > Diagram) használatakor — teljesen kódból. Így hozzáadott diagram nem képek; egy Chart objektum, amely a dokumentum OOXML csomagjába van beágyazva, adat-sorozat modellel, tengelyekkel, jelmagyarázattal és adat-táblázattal, amelyet a Word a fájl mentése után is megnyithat és szerkeszthet. Ez a bejegyzés mélyrehatóan bemutatja a Chart API részleteit: hogyan hozhatunk létre diagramot, adhatunk hozzá sorozat adatokat, és érhetjük el a tengely, jelmagyarázat, adatcímke és formázási objektumokat, amelyek meghatározzák a megjelenítését.
A könyvtár MIT licencű, és nincsenek natív függőségei. A .NET Standard 2.0-ra céloz, így a bejegyzésben szereplő kód változtatás nélkül fut a .NET Framework 4.6.2+-on és a .NET 6, 8 és 10 verziókon. Telepíthető a NuGet segítségével, vagy felépíthető forráskódból – lásd az alábbi Gyors kezdés részt. Itt bemutatott minden ugyanaz a diagrammotor, amelyet a kereskedelmi Aspose.Words használ a .NET számára; ez a kiadás tartalmazza a teljes diagramobjektum-modellt, de nem a lapelrendezést vagy a renderelést, így a diagram oldalbeli pozíciója nem kerül kiszámításra, és a dokumentumot nem lehet PDF-re vagy képre exportálni.
Mi van benne
Diagram létrehozása és adat-sorozat hozzáadása
DocumentBuilder.InsertChart(chartType, width, height) egy diagram alakzatot szúr be az aktuális pozícióba, és visszaad egy Shape objektumot; annak Chart tulajdonsága a belépési pont a többi számára. Egy újonnan beszúrt diagram már rendelkezik alapértelmezett sorozattal, ezért a legtöbb kód először törli azt, majd saját adatait a Chart.Series segítségével adja hozzá, ami egy 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 overloadokat biztosít kategória/érték párokra (mint fent), X/Y érték párokra, dátumos sorozatokra és buborék sorozatokra egy extra méretértékkel. Egyedi ChartSeries, Add(xValue), Add(xValue, yValue) és Add(xValue, yValue, bubbleSize) esetén egyetlen pontot fűznek hozzá, a Insert egy adott indexnél helyez el egy pontot, és a Clear() / ClearValues() sorozat adatokat távolítanak el anélkül, hogy feltétlenül a sorozat objektumot magát eltávolítanák.
Diagramtípusok és sorozattípusok
ChartType — a InsertChart paraméterként átadott felsorolt típus — körülbelül 40 taggal rendelkezik, amelyek a szabványos Word diagramcsaládokat fedik le: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, és Funnel, valamint néhány közülük halmozott, százalékos halmozott és 3D változatai (Bar3D, ColumnStacked, Area3DPercentStacked stb.).
Egy kapcsolódó, de különálló felsorolt típus, ChartSeriesType, a ChartSeries.SeriesType és ChartSeriesGroup.SeriesType helyen jelenik meg, és egy egyedi sorozat vagy sorozatcsoport típusát írja le, nem pedig a diagramot egészében. Ugyanazokat a tagokat tartalmazza, mint a ChartType, plusz még kettőt — ParetoLine és RegionMap — amelyeket a ChartType nem tesz közvetlenül elérhetővé. A ChartSeriesGroup teszi lehetővé a kombinált diagramokat: a Chart.SeriesGroups (egy ChartSeriesGroupCollection) egy csoportot tárol sorozattípusonként a diagramon, és minden csoport saját AxisX/AxisY párt és elrendezési tulajdonságokat, például Overlap, GapWidth, BubbleScale és DoughnutHoleSize.
Tengelyek, Rácsvonalak és Skálázás
Chart.AxisX, AxisY, és AxisZ (plusz a Axes gyűjtemény) ChartAxis objektumokat ad vissza. Minden tengelynek van egy Type (ChartAxisType.Category, Series vagy Value), jelölő beállítások (MajorTickMark, MinorTickMark — Cross, Inside, Outside vagy None), rácsvonal jelzők (HasMajorGridlines, HasMinorGridlines), és egységvezérlés (MajorUnit, MinorUnit, valamint azok *IsAuto megfelelői). ChartAxis.Scaling egy AxisScaling objektumot ad vissza, amelynek Minimum és Maximum AxisBound értékek — AxisBound.IsAuto jelzi, hogy a határ automatikusan számított-e, és a paraméteres konstruktorok (AxisBound(value), AxisBound(datetime)) egy explicit numerikus vagy dátum határt állítanak be. Egy kategória tengely szöveg- vagy időkategóriákhoz rögzíthető a ChartAxis.CategoryType segítségével (AxisCategoryType.Automatic, Category vagy Time), és a ChartAxis.Title egy ChartAxisTitle objektumot tár fel saját Text, Show és Font értékekkel.
Jelmagyarázat, Adattábla és Diagramcím
Chart.Legend egy ChartLegend objektumot ad vissza, amelynek Position (egy LegendPosition None, Bottom, Left, Right, Top vagy TopRight közül) szabályozza, hogy hol jelenik meg a diagramterülethez képest; LegendEntries egy ChartLegendEntryCollection az egyedi ChartLegendEntry objektumokból, mindegyiknek saját Font és IsHidden jelzője van, amely egyetlen sorozat elrejtését teszi lehetővé a jelmagyarázatból anélkül, hogy a diagramról eltávolítaná. Chart.DataTable (egy ChartDataTable) egy rácsként jeleníti meg a sorozatértékeket a diagram alatt, ha a Show be van állítva, és a HasLegendKeys, HasHorizontalBorder, HasVerticalBorder és HasOutlineBorder szabályozzák a megjelenését. Chart.Title egy ChartTitle Text és Show tulajdonságokkal, a tengelycímekhez hasonló mintát követve.
Adatcímkék, Adatpontok és Jelölők
ChartSeries.HasDataLabels bekapcsolja az adatcímkéket egy sorozathoz, és ChartSeries.DataLabels (egy ChartDataLabelCollection) vagy egy egyedi ChartDataLabel tőle szabályozza, hogy a címke mit mutasson: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey és ShowBubbleSize önálló jelzők, valamint Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit és egyebek) a címkét a ponthoz képest helyezi. ChartSeries.DataPoints pontonkénti hozzáférést biztosít a ChartDataPoint segítségével, amely saját Marker tartalmaz (egy ChartMarker a MarkerSymbol felsorolt Symbol értékkel és egy Size), Explosion (a tortaszelet kihúzásához), és Format. Minden diagram elem, amely kitölthető vagy körvonalazható – sorozatok, adatpontok, a jelmagyarázat, a cím, az adat táblázat – egy ChartFormat-t tesz elérhetővé a Format tulajdonságán keresztül, Fill, Stroke és ShapeType (ChartShapeType) tulajdonságokkal, valamint egy SetDefaultFill() metódussal a visszaállításhoz. Egy fontos megjegyzés: a ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor és azok árnyalat/tónus változatai) témához kapcsolt kitöltés- és vonal színváltozatai nincsenek megvalósítva ebben a kiadásban – állíts be egyszerű Fill/Stroke színeket a téma-szín hivatkozások helyett. Chart.Style (egy ChartStyle, mint például Muted, Saturated, Gradient, Outline vagy Black) egy lépésben alkalmaz egy előre definiált megjelenést a teljes diagramra.
Gyors kezdés
Aspose.Words FOSS a .NET számára elérhető a NuGet segítségével:
dotnet add package Aspose.Words.FOSSForrásból való felépítéshez:
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
Ezután adj hozzá egy projekt hivatkozást a Aspose.Words.csproj objektumra az alkalmazásodból. A hivatkozás létrehozása után ez egy vonaldiagramot hoz létre egy sorozattal, és elmenti DOCX formátumban:
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");
Nyisd meg a chart.docx fájlt a Wordben, és a diagram teljesen szerkeszthető – jobb-klikk rá, és válaszd a „Edit Data” lehetőséget, hogy lásd a fent leírt három kategóriát és értéket.
Támogatott formátumok
| Formátum | Kiterjesztés | Olvasás | Írás |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (összes változat) | (különböző) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
A API segítségével épített diagramok OOXML rajzobjektumok, ezért körbejárhatóak a fent említett DOCX-család formátumokon (DOCX, DOCM, DOTX, DOTM és Flat OPC). Ez a kiadás nem tud exportálni PDF-be, XPS-be vagy képekbe, és nem tud nyomtatni, így semmi sem renderel diagramot bitmapre — a diagram élő, szerkeszthető objektumként marad a Word-fájlban. A további formátumkonvertálókat, amelyeket ebből a kiadásból eltávolítottak (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 és WordML), ugyanazok a alrendszerek, amelyeket a könyvtár minden más részén is kizártak, nem kifejezetten a diagramokhoz kapcsolódóak.
Nyílt forráskód & licencelés
Aspose.Words FOSS a .NET számára MIT licenc alatt kerül kiadásra, kereskedelmi és személyes felhasználásra ingyenes, jogdíj vagy terjesztési korlátozás nélkül. A teljes forrás, beleértve a bejegyzésben hivatkozott diagram osztályokat is, elérhető a GitHub oldalon a Aspose.Words FOSS a .NET számára tárolt repóban.
