บทนำ
คู่มือนี้แสดงวิธีสร้างแผนภูมิ Word แบบดั้งเดิมด้วย Aspose.Words FOSS สำหรับ .NET — วัตถุการวาดเดียวกันที่ Word สร้างเมื่อคุณใช้แทรก > แผนภูมิ — ทั้งหมดจากโค้ด แผนภูมิที่เพิ่มด้วยวิธีนี้ไม่ใช่รูปภาพ; มันเป็นวัตถุ Chart ที่ฝังอยู่ในแพ็กเกจ OOXML ของเอกสาร พร้อมโมเดลชุดข้อมูล, แกน, คำอธิบาย, ตารางข้อมูลที่ Word ยังสามารถเปิดและแก้ไขได้หลังจากไฟล์ถูกบันทึก บทความนี้เป็นการสำรวจเชิงลึกเกี่ยวกับ Chart 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, พร้อมกับเวอร์ชัน stacked, percent-stacked, และ 3D ของบางรายการ (Bar3D, ColumnStacked, Area3DPercentStacked, เป็นต้น).
enum ที่เกี่ยวข้องแต่แยกจากกัน, 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), การตั้งค่าตำแหน่ง tick (MajorTickMark, MinorTickMark — Cross, Inside, Outside หรือ None), ธง gridline (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 | ✓ | ✓ |
แผนภูมิที่สร้างด้วย API เป็นวัตถุการวาดแบบ OOXML ดังนั้นจึงสามารถทำ round-trip ข้ามรูปแบบของตระกูล 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.
