הקדמה
מדריך זה מראה כיצד לבנות גרפים מקוריים של Word עם Aspose.Words FOSS עבור .NET — אותם אובייקטי ציור ש-Word יוצר בעצמו כשאתם משתמשים ב-Insert > Chart — באופן מלא מקוד. גרף שנוסף בצורה זו אינו תמונה; הוא אובייקט Chart משובץ בחבילת ה-OOXML של המסמך, עם מודל סדרת נתונים, צירים, מקרא וטבלת נתונים ש-Word עדיין יכול לפתוח ולערוך לאחר שמירת הקובץ. פוסט זה הוא צלילה עמוקה לתוך API של הגרף: כיצד ליצור גרף, להוסיף נתוני סדרה, ולהגיע לציר, למקרא, לתווית הנתונים ולפריטי העיצוב השולטים באופן הצגתו.
הספרייה ברישיון MIT ואין לה תלותיות מקומיות. היא ממקמת את .NET Standard 2.0, ולכן הקוד בפוסט זה רץ ללא שינוי על .NET Framework 4.6.2+ ו-.NET 6, 8 ו-10. התקינו אותה דרך NuGet, או בנו ממקור — ראו התחלה מהירה למטה. כל מה שמוצג כאן הוא אותו מנוע גרפים שבו משתמשים Aspose.Words המסחרי עבור .NET; גרסה זו כוללת את מודל האובייקט המלא של הגרף אך לא את פריסת העמוד או הרינדור, ולכן מיקום הגרף על העמוד אינו מחושב והמסמך אינו ניתן לייצוא ל-PDF או לתמונה.
מה נכלל
יצירת גרף והוספת סדרת נתונים
DocumentBuilder.InsertChart(chartType, width, height) מכניס צורת גרף במיקום הנוכחי ומחזיר Shape; המאפיין Chart שלו הוא נקודת הכניסה לכל השאר. גרף שמוכנס זה עתה כבר כולל סדרה ברירת מחדל, ולכן רוב הקוד מוחק אותה תחילה ומוסיף נתונים משלו דרך Chart.Series, 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 כולל עומסים עבור זוגות קטגוריה/ערך (כמתואר למעלה), זוגות ערכי X/Y, סדרות מתוזמנות, וסדרות בועות עם ערך גודל נוסף. על ChartSeries בודד, Add(xValue), Add(xValue, yValue) ו-Add(xValue, yValue, bubbleSize) מוסיפים נקודות בודדות, Insert מציב נקודה באינדקס נתון, ו-Clear() / ClearValues() מסירים נתוני סדרה מבלי בהכרח להסיר את אובייקט הסדרה עצמו.
סוגי גרפים וסוגי סדרות
ChartType — המונה שעובר ל-InsertChart — מכיל כ-40 חברים המכסים את משפחות הגרפים הסטנדרטיות של Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, ו-Funnel, בנוסף לגרסאות ערימתיות, ערימתיות באחוזים, ותלת-ממדיות של כמה מהם (Bar3D, ColumnStacked, Area3DPercentStacked, וכן הלאה).
מונה קשור אך נפרד, ChartSeriesType, מופיע ב-ChartSeries.SeriesType וב-ChartSeriesGroup.SeriesType ומתאר את סוג הסדרה או קבוצת הסדרות הבודדת ולא את הגרף כולו. הוא כולל את אותם החברים כמו ChartType ועוד שניים — ParetoLine ו-RegionMap — ש-ChartType לא חושף ישירות. ChartSeriesGroup הוא מה שמאפשר גרפים משולבים: Chart.SeriesGroups (ChartSeriesGroupCollection) מכיל קבוצה אחת לכל סוג סדרה בגרף, ולכל קבוצה יש את זוג ה-AxisX/AxisY שלה וכן תכונות פריסה כגון Overlap, GapWidth, BubbleScale ו-DoughnutHoleSize.
צירים, קווי רשת וקנה מידה
Chart.AxisX, AxisY ו-AxisZ (בנוסף לאוסף Axes) מחזירים עצמים מסוג ChartAxis. לכל ציר יש Type (ChartAxisType.Category, Series או Value), הגדרות סימני טיק (MajorTickMark, MinorTickMark — Cross, Inside, Outside או None), דגלי קו רשת (HasMajorGridlines, HasMinorGridlines) ובקרת יחידות (MajorUnit, MinorUnit) והמקבילים שלהם *IsAuto. ChartAxis.Scaling מחזיר עצם AxisScaling שבו Minimum ו-Maximum הם ערכי AxisBound — AxisBound.IsAuto מדווח האם המגבלה מחושבת אוטומטית, והקונסטרוקטורים הפרמטריים (AxisBound(value), AxisBound(datetime)) מגדירים מגבלה מספרית או תאריך מפורשת. ציר קטגוריה ניתן לעגינה לטקסט או לקטגוריות זמן דרך ChartAxis.CategoryType (AxisCategoryType.Automatic, Category או Time), ו-ChartAxis.Title חושף ChartAxisTitle עם Text, Show ו-Font משלו.
מקרא, טבלת נתונים וכותרת גרף
Chart.Legend מחזיר ChartLegend, שבו Position (LegendPosition של None, Bottom, Left, Right, Top או TopRight) קובע היכן הוא מציג יחסית לאזור הציור; LegendEntries הוא ChartLegendEntryCollection של עצמים ChartLegendEntry בודדים, שלכל אחד יש Font ו-דגל IsHidden שמסתיר סדרה בודדת מהמקרא מבלי להסיר אותה מהגרף. Chart.DataTable (ChartDataTable) מציג את ערכי הסדרה כרשת מתחת לגרף כאשר Show מוגדר, כאשר HasLegendKeys, HasHorizontalBorder, HasVerticalBorder ו-HasOutlineBorder שולטות במראה שלו. Chart.Title הוא ChartTitle עם תכונות Text ו-Show, על פי אותו דפוס כמו כותרות הצירים.
תוויות נתונים, נקודות נתונים וסמנים
ChartSeries.HasDataLabels מפעיל תוויות נתונים עבור סדרה, ו-ChartSeries.DataLabels (ChartDataLabelCollection) או ChartDataLabel בודד ממנה קובע מה כל תווית מציגה: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey ו-ShowBubbleSize הם דגלים עצמאיים, ו-Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit ואחרים) ממקם את התווית יחסית לנקודה שלה. ChartSeries.DataPoints מספק גישה לכל נקודה דרך ChartDataPoint, שכולל את ה-Marker שלו (ChartMarker עם Symbol מה-enum MarkerSymbol ו-Size), Explosion (להוצאת פרוסת פאי), ו-Format. כל רכיב של תרשים שניתן למלא או לקוול — סדרות, נקודות נתונים, האגדה, הכותרת, טבלת הנתונים — חושף ChartFormat דרך המאפיין Format שלו, עם מאפיינים Fill, Stroke ו-ShapeType (ChartShapeType) ושיטת SetDefaultFill() לאיפוס. דבר שיש לדעת: הגרסאות הקשורות לנושא של צבע מילוי וקו קו על ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor והגרסאות המוטות/מוצלות שלהם) אינן מיושמות בגרסה זו — יש להגדיר צבעי Fill/Stroke רגילים במקום הפניות לצבעי נושא. Chart.Style (ChartStyle כגון Muted, Saturated, Gradient, Outline או Black) מחיל מראה מוגדר מראש על כל התרשים בצעד אחד.
התחלה מהירה
Aspose.Words FOSS עבור .NET זמין דרך NuGet:
dotnet add package Aspose.Words.FOSSכדי לבנות מהמקור במקום זאת:
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
לאחר מכן הוסף רפרנס לפרויקט ל-Aspose.Words.csproj מהיישום שלך. עם הרפרנס במקום, זה יוצר תרשים קו עם סדרה אחת ושומר אותו ל-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");
פתח את chart.docx ב-Word והתרשים ניתן לעריכה מלאה — לחץ עליו לחיצה ימנית ובחר “Edit Data” כדי לראות את שלוש הקטגוריות והערכים שכתובים למעלה.
פורמטים נתמכים
| פורמט | הרחבה | קריאה | כתיבה |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (כל הווריאנטים) | (שונות) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
התרשימים שנבנו עם Chart API הם אובייקטים של ציור OOXML, ולכן הם עוברים בצורה מלאה בין פורמטים ממשפחת DOCX המצוינים למעלה (DOCX, DOCM, DOTX, DOTM ו-Flat OPC). גרסה זו אינה יכולה לייצא ל-PDF, XPS או תמונות ואינה יכולה להדפיס, ולכן שום דבר אינו ממיר תרשים לביטמפה — התרשים נשאר אובייקט חי, ניתן לעריכה בתוך קובץ ה-Word. ממירי הפורמטים הנוספים שהוסרו מגרסה זו (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 ו-WordML) הם אותם תתי-מערכות שמוחרגות במקומות אחרים בספרייה, ולא משהו ספציפי לתרשימים.
קוד פתוח ורישוי
Aspose.Words FOSS עבור .NET משוחרר תחת רישיון MIT, חינמי לשימוש מסחרי ואישי ללא תמלוגים או מגבלות הפצה. הקוד המלא, כולל מחלקות התרשים המוזכרות בפוסט זה, זמין ב-GitHub ב-Aspose.Words FOSS עבור .NET repository.
