مقدمه
این راهنما نشان میدهد چگونه با استفاده از Aspose.Words FOSS برای .NET نمودارهای بومی ورد را بسازید — همان اشیای گرافیکی که ورد هنگام استفاده از Insert > Chart ایجاد میکند — بهصورت کامل از طریق کد. یک نمودار که به این روش اضافه میشود تصویر نیست؛ بلکه یک شیء Chart است که در بسته OOXML سند جاسازی شده، دارای مدل سری داده، محورها، یک افسانه، و جدول دادهای است که ورد میتواند پس از ذخیرهسازی فایل آن را باز و ویرایش کند. این پست یک بررسی عمیق از 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 پاس داده میشود — تقریباً ۴۰ عضو دارد که خانوادههای استاندارد نمودارهای Word را شامل میشود: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall و Funnel، بهعلاوهٔ انواع stacked، percent-stacked و 3D برخی از آنها (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. هر عنصر نموداری که میتواند پر یا خطدار شود — سریها، نقاط داده، legend، عنوان، جدول دادهها — یک 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 موجود است.
