Giới thiệu
Hướng dẫn này cho thấy cách xây dựng biểu đồ Word gốc với Aspose.Words FOSS cho .NET — cùng các đối tượng vẽ mà Word tự tạo khi bạn sử dụng Chèn > Biểu đồ — hoàn toàn bằng mã. Một biểu đồ được thêm theo cách này không phải là hình ảnh; nó là một đối tượng Chart được nhúng trong gói OOXML của tài liệu, có mô hình chuỗi dữ liệu, trục, chú giải và bảng dữ liệu mà Word vẫn có thể mở và chỉnh sửa sau khi tệp được lưu. Bài viết này là một phân tích sâu về API của Biểu đồ: cách tạo biểu đồ, thêm dữ liệu chuỗi, và truy cập các đối tượng trục, chú giải, nhãn dữ liệu và định dạng kiểm soát cách nó hiển thị.
Thư viện này được cấp phép MIT và không có phụ thuộc gốc. Nó nhắm tới .NET Standard 2.0, vì vậy mã trong bài viết này chạy không thay đổi trên .NET Framework 4.6.2+ và .NET 6, 8, và 10. Cài đặt nó qua NuGet, hoặc xây dựng từ nguồn — xem phần Khởi động nhanh bên dưới. Tất cả những gì được trình bày ở đây là cùng một engine biểu đồ được sử dụng bởi Aspose.Words thương mại cho .NET; phiên bản này bao gồm toàn bộ mô hình đối tượng biểu đồ nhưng không có bố cục trang hoặc việc render, vì vậy vị trí của biểu đồ trên trang không được tính và tài liệu không thể xuất ra PDF hoặc hình ảnh.
Những gì có trong gói
Tạo biểu đồ và thêm chuỗi dữ liệu
DocumentBuilder.InsertChart(chartType, width, height) chèn một hình dạng biểu đồ tại vị trí hiện tại và trả về một Shape; thuộc tính Chart của nó là điểm khởi đầu cho mọi thứ khác. Một biểu đồ mới chèn đã có một chuỗi mặc định, vì vậy hầu hết mã sẽ xóa nó trước và thêm dữ liệu của mình thông qua Chart.Series, một 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 có các overload cho các cặp danh mục/giá trị (như trên), cặp giá trị X/Y, chuỗi có ngày, và chuỗi bong bóng với một giá trị kích thước bổ sung. Trên một ChartSeries riêng lẻ, Add(xValue), Add(xValue, yValue), và Add(xValue, yValue, bubbleSize) thêm các điểm đơn, Insert đặt một điểm tại chỉ mục cho trước, và Clear() / ClearValues() loại bỏ dữ liệu chuỗi mà không nhất thiết phải xóa đối tượng chuỗi đó.
Các loại biểu đồ và các loại chuỗi
ChartType — enum được truyền vào InsertChart — có khoảng 40 thành viên bao phủ các họ biểu đồ tiêu chuẩn của Word: Line, Bar, Column, Pie, Doughnut, Radar, Scatter, Stock, Surface, Treemap, Sunburst, Histogram, Pareto, BoxAndWhisker, Waterfall, và Funnel, cộng thêm các biến thể chồng, chồng theo phần trăm và 3D của một số trong số chúng (Bar3D, ColumnStacked, Area3DPercentStacked, v.v.).
Một enum liên quan nhưng riêng biệt, ChartSeriesType, xuất hiện trên ChartSeries.SeriesType và ChartSeriesGroup.SeriesType và mô tả loại của một chuỗi riêng lẻ hoặc nhóm chuỗi thay vì toàn bộ biểu đồ. Nó chứa các thành viên giống như ChartType cộng thêm hai thành viên — ParetoLine và RegionMap — mà ChartType không trực tiếp hiển thị. ChartSeriesGroup là yếu tố cho phép các biểu đồ hỗn hợp: Chart.SeriesGroups (một ChartSeriesGroupCollection) chứa một nhóm cho mỗi loại chuỗi trong biểu đồ, và mỗi nhóm có cặp AxisX/AxisY riêng và các thuộc tính bố cục như Overlap, GapWidth, BubbleScale, và DoughnutHoleSize.
Trục, Đường lưới và Tỷ lệ
Chart.AxisX, AxisY, và AxisZ (cùng với bộ sưu tập Axes) trả về các đối tượng ChartAxis. Mỗi trục có một Type (ChartAxisType.Category, Series, hoặc Value), cài đặt dấu tick (MajorTickMark, MinorTickMark — Cross, Inside, Outside, hoặc None), cờ đường lưới (HasMajorGridlines, HasMinorGridlines), và điều khiển đơn vị (MajorUnit, MinorUnit, và các phiên bản *IsAuto của chúng). ChartAxis.Scaling trả về một đối tượng AxisScaling mà Minimum và Maximum là các giá trị AxisBound — AxisBound.IsAuto báo cáo liệu giới hạn có được tính tự động hay không, và các hàm khởi tạo có tham số (AxisBound(value), AxisBound(datetime)) đặt một giới hạn số hoặc ngày cụ thể. Một trục danh mục có thể được ghim vào các danh mục văn bản hoặc thời gian thông qua ChartAxis.CategoryType (AxisCategoryType.Automatic, Category, hoặc Time), và ChartAxis.Title hiển thị một ChartAxisTitle với Text, Show, và Font riêng của nó.
Chú giải, Bảng dữ liệu và Tiêu đề biểu đồ
Chart.Legend trả về một ChartLegend, mà Position (một LegendPosition của None, Bottom, Left, Right, Top, hoặc TopRight) điều khiển vị trí hiển thị của nó so với vùng vẽ; LegendEntries là một ChartLegendEntryCollection của các đối tượng ChartLegendEntry riêng lẻ, mỗi cái có cờ Font và IsHidden riêng để ẩn một chuỗi duy nhất khỏi chú giải mà không loại bỏ nó khỏi biểu đồ. Chart.DataTable (một ChartDataTable) hiển thị các giá trị chuỗi dưới dạng lưới dưới biểu đồ khi Show được đặt, với HasLegendKeys, HasHorizontalBorder, HasVerticalBorder, và HasOutlineBorder kiểm soát giao diện của nó. Chart.Title là một ChartTitle có các thuộc tính Text và Show, tuân theo cùng mẫu như tiêu đề trục.
Nhãn dữ liệu, Điểm dữ liệu và Dấu đánh dấu
ChartSeries.HasDataLabels bật nhãn dữ liệu cho một chuỗi, và ChartSeries.DataLabels (một ChartDataLabelCollection) hoặc một ChartDataLabel riêng lẻ từ nó kiểm soát những gì mỗi nhãn hiển thị: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey, và ShowBubbleSize là các cờ độc lập, và Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit, và các mục khác) đặt nhãn tương đối so với điểm của nó. ChartSeries.DataPoints cung cấp quyền truy cập từng điểm thông qua ChartDataPoint, mà chứa Marker riêng của nó (một ChartMarker với Symbol từ enum MarkerSymbol và một Size), Explosion (để kéo ra một lát bánh), và Format. Mọi thành phần biểu đồ có thể được tô màu hoặc viền — chuỗi, điểm dữ liệu, chú giải, tiêu đề, bảng dữ liệu — đều khai báo một ChartFormat thông qua thuộc tính Format của nó, với các thuộc tính Fill, Stroke, và ShapeType (ChartShapeType) và một phương thức SetDefaultFill() để đặt lại. Một lưu ý đáng biết: các biến thể liên kết với giao diện chủ đề của màu tô và màu viền trên ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor, và các phiên bản tông màu/độ tối tương ứng) không được triển khai trong phiên bản này — hãy đặt màu Fill/Stroke thuần thay vì tham chiếu màu chủ đề. Chart.Style (một ChartStyle như Muted, Saturated, Gradient, Outline, hoặc Black) áp dụng một giao diện đã định sẵn cho toàn bộ biểu đồ trong một bước.
Bắt đầu nhanh
Aspose.Words FOSS cho .NET có sẵn thông qua NuGet:
dotnet add package Aspose.Words.FOSSĐể biên dịch từ mã nguồn thay thế:
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
Sau đó thêm một tham chiếu dự án tới Aspose.Words.csproj từ ứng dụng của bạn. Khi tham chiếu đã được thêm, điều này tạo một biểu đồ đường với một chuỗi và lưu nó dưới dạng 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");
Mở chart.docx trong Word và biểu đồ có thể chỉnh sửa hoàn toàn — nhấp chuột phải vào nó và chọn “Edit Data” để xem cùng ba danh mục và các giá trị được viết ở trên.
Các định dạng được hỗ trợ
| Định dạng | Phần mở rộng | Đọc | Ghi |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (tất cả các biến thể) | (nhiều loại) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Biểu đồ được xây dựng bằng API Chart là các đối tượng vẽ OOXML, vì vậy chúng có thể chuyển đổi qua lại giữa các định dạng họ DOCX ở trên (DOCX, DOCM, DOTX, DOTM và Flat OPC). Bản phát hành này không thể xuất ra PDF, XPS hoặc hình ảnh và không thể in, do đó không có gì chuyển đổi biểu đồ thành bitmap — biểu đồ vẫn là một đối tượng sống, có thể chỉnh sửa bên trong tệp Word. Các bộ chuyển đổi định dạng bổ sung bị loại bỏ khỏi bản này (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 và WordML) là cùng các hệ thống phụ đã bị loại trừ ở mọi nơi khác trong thư viện, không phải là điều gì đặc thù đối với biểu đồ.
Mã nguồn mở & Giấy phép
Aspose.Words FOSS cho .NET được phát hành dưới giấy phép MIT, miễn phí cho việc sử dụng thương mại và cá nhân mà không có phí bản quyền hay hạn chế phân phối lại. Mã nguồn đầy đủ, bao gồm các lớp biểu đồ được tham chiếu trong bài viết này, có sẵn trên GitHub trong Aspose.Words FOSS cho kho .NET.
