مقدمة
يوضح هذا الدليل كيفية إنشاء مخططات Word الأصلية باستخدام Aspose.Words FOSS لـ .NET — نفس كائنات الرسم التي ينشئها Word عندما تستخدم إدراج > مخطط — بالكامل من خلال الشيفرة. المخطط المضاف بهذه الطريقة ليس صورة؛ إنه كائن 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 — التعداد (enum) الممرَّر إلى 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 من تعداد 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 المستودع.
