Pendahuluan
Panduan ini menunjukkan cara membangun diagram Word asli dengan Aspose.Words FOSS untuk .NET — objek gambar yang sama yang dibuat Word ketika Anda menggunakan Sisipkan > Diagram — sepenuhnya melalui kode. Diagram yang ditambahkan dengan cara ini bukan gambar; itu adalah objek Chart yang disematkan dalam paket OOXML dokumen, dengan model seri data, sumbu, legenda, dan tabel data yang masih dapat dibuka dan diedit oleh Word setelah file disimpan. Posting ini merupakan deep dive ke dalam Chart API: cara membuat diagram, menambahkan data seri, dan menjangkau objek sumbu, legenda, label data, serta pemformatan yang mengontrol cara renderingnya.
Pustaka ini berlisensi MIT dan tidak memiliki ketergantungan native. Ia menargetkan .NET Standard 2.0, sehingga kode dalam posting ini berjalan tanpa perubahan pada .NET Framework 4.6.2+ dan .NET 6, 8, dan 10. Instal melalui NuGet, atau bangun dari sumber — lihat Mulai Cepat di bawah. Semua yang ditampilkan di sini adalah mesin diagram yang sama yang digunakan oleh Aspose.Words komersial untuk .NET; edisi ini mencakup model objek diagram lengkap tetapi tidak termasuk tata letak halaman atau rendering, sehingga posisi diagram pada halaman tidak dihitung dan dokumen tidak dapat diekspor ke PDF atau gambar.
Apa yang Disertakan
Membuat Diagram dan Menambahkan Seri Data
DocumentBuilder.InsertChart(chartType, width, height) menyisipkan bentuk diagram pada posisi saat ini dan mengembalikan Shape; properti Chart-nya adalah titik masuk untuk semua hal lainnya. Diagram yang baru disisipkan sudah memiliki seri default, sehingga sebagian besar kode membersihkannya terlebih dahulu dan menambahkan data sendiri melalui Chart.Series, sebuah 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 memiliki overload untuk pasangan kategori/nilai (seperti di atas), pasangan nilai X/Y, seri bertanggal, dan seri gelembung dengan nilai ukuran tambahan. Pada ChartSeries individual, Add(xValue), Add(xValue, yValue), dan Add(xValue, yValue, bubbleSize) menambahkan titik tunggal, Insert menempatkan titik pada indeks tertentu, dan Clear() / ClearValues() menghapus data seri tanpa harus menghapus objek seri itu sendiri.
Jenis Diagram dan Jenis Seri
ChartType — enum yang diteruskan ke InsertChart — memiliki sekitar 40 anggota yang mencakup keluarga diagram standar Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, dan Funnel, serta varian stacked, percent-stacked, dan 3D dari beberapa di antaranya (Bar3D, ColumnStacked, Area3DPercentStacked, dan seterusnya).
Enum yang terkait namun berbeda, ChartSeriesType, muncul pada ChartSeries.SeriesType dan ChartSeriesGroup.SeriesType serta menggambarkan tipe seri individu atau grup seri daripada diagram secara keseluruhan. Enum ini memiliki anggota yang sama dengan ChartType ditambah dua lagi — ParetoLine dan RegionMap — yang tidak langsung diungkapkan oleh ChartType. ChartSeriesGroup adalah apa yang memungkinkan diagram kombinasi: Chart.SeriesGroups (sebuah ChartSeriesGroupCollection) menyimpan satu grup per tipe seri dalam diagram, dan setiap grup memiliki pasangan AxisX/AxisY serta properti tata letak seperti Overlap, GapWidth, BubbleScale, dan DoughnutHoleSize.
Sumbu, Garis Kisi, dan Skala
Chart.AxisX, AxisY, dan AxisZ (plus koleksi Axes) mengembalikan objek ChartAxis. Setiap sumbu memiliki Type (ChartAxisType.Category, Series, atau Value), pengaturan tanda centang (MajorTickMark, MinorTickMark — Cross, Inside, Outside, atau None), flag garis kisi (HasMajorGridlines, HasMinorGridlines), dan kontrol satuan (MajorUnit, MinorUnit, serta pasangan *IsAuto mereka). ChartAxis.Scaling mengembalikan objek AxisScaling yang Minimum dan Maximumnya adalah nilai AxisBound — AxisBound.IsAuto melaporkan apakah batas dihitung secara otomatis, dan konstruktor parametrik (AxisBound(value), AxisBound(datetime)) menetapkan batas numerik atau tanggal secara eksplisit. Sumbu kategori dapat dipatok ke kategori teks atau waktu melalui ChartAxis.CategoryType (AxisCategoryType.Automatic, Category, atau Time), dan ChartAxis.Title menampilkan ChartAxisTitle dengan Text, Show, dan Font miliknya.
Legenda, Tabel Data, dan Judul Diagram
Chart.Legend mengembalikan sebuah ChartLegend, yang Position (sebuah LegendPosition dari None, Bottom, Left, Right, Top, atau TopRight) mengontrol di mana ia dirender relatif terhadap area plot; LegendEntries adalah sebuah ChartLegendEntryCollection dari objek ChartLegendEntry individu, masing-masing dengan Font dan flag IsHidden untuk menyembunyikan satu seri dari legenda tanpa menghapusnya dari diagram. Chart.DataTable (sebuah ChartDataTable) merender nilai seri sebagai kisi di bawah diagram ketika Show diatur, dengan HasLegendKeys, HasHorizontalBorder, HasVerticalBorder, dan HasOutlineBorder mengontrol tampilannya. Chart.Title adalah sebuah ChartTitle dengan properti Text dan Show, mengikuti pola yang sama seperti judul sumbu.
Label Data, Titik Data, dan Penanda
ChartSeries.HasDataLabels mengaktifkan label data untuk sebuah seri, dan ChartSeries.DataLabels (sebuah ChartDataLabelCollection) atau ChartDataLabel individual darinya mengontrol apa yang ditampilkan tiap label: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey, dan ShowBubbleSize adalah flag independen, dan Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit, dan lain-lain) menempatkan label relatif terhadap titiknya. ChartSeries.DataPoints memberikan akses per-titik melalui ChartDataPoint, yang memiliki Marker sendiri (sebuah ChartMarker dengan Symbol dari enum MarkerSymbol dan sebuah Size), Explosion (untuk menarik irisan pai), dan Format. Setiap elemen diagram yang dapat diisi atau dioutline — seri, titik data, legenda, judul, tabel data — mengekspos ChartFormat melalui properti Format-nya, dengan properti Fill, Stroke, dan ShapeType (ChartShapeType) serta metode SetDefaultFill() untuk mengatur ulangnya. Satu catatan penting: varian yang terhubung tema untuk warna isi dan garis pada ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor, dan pasangan tint/shade-nya) tidak diimplementasikan dalam edisi ini — gunakan warna Fill/Stroke biasa alih-alih referensi warna tema. Chart.Style (sebuah ChartStyle seperti Muted, Saturated, Gradient, Outline, atau Black) menerapkan tampilan pra-definisi ke seluruh diagram dalam satu langkah.
Mulai Cepat
Aspose.Words FOSS untuk .NET tersedia melalui NuGet:
dotnet add package Aspose.Words.FOSSUntuk membangun dari sumber sebagai gantinya:
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
Kemudian tambahkan referensi proyek ke Aspose.Words.csproj dari aplikasi Anda. Dengan referensi tersebut, ini membuat diagram garis dengan satu seri dan menyimpannya ke 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");
Buka chart.docx di Word dan diagram tersebut dapat diedit sepenuhnya — klik kanan dan pilih “Edit Data” untuk melihat tiga kategori dan nilai yang sama seperti yang dituliskan di atas.
Format yang Didukung
| Format | Ekstensi | Baca | Tulis |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (semua varian) | (berbagai) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Diagram yang dibangun dengan Chart API adalah objek gambar OOXML, sehingga dapat dipertukarkan di seluruh format keluarga DOCX di atas (DOCX, DOCM, DOTX, DOTM, dan Flat OPC). Edisi ini tidak dapat mengekspor ke PDF, XPS, atau gambar dan tidak dapat mencetak, sehingga tidak ada yang merender diagram menjadi bitmap — diagram tetap menjadi objek hidup yang dapat diedit di dalam file Word. Konverter format tambahan yang dihapus dari edisi ini (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, dan WordML) adalah subsistem yang sama yang dikecualikan di tempat lain dalam perpustakaan, bukan sesuatu yang khusus untuk diagram.
Sumber Terbuka & Lisensi
Aspose.Words FOSS untuk .NET dirilis di bawah lisensi MIT, gratis untuk penggunaan komersial dan pribadi tanpa royalti atau pembatasan redistribusi. Sumber lengkap, termasuk kelas diagram yang disebutkan dalam posting ini, tersedia di GitHub dalam Aspose.Words FOSS untuk .NET repository.
