介绍
本指南展示了如何使用 Aspose.Words FOSS 为 .NET 完全通过代码构建原生 Word 图表——这与在 Word 中使用 插入 > 图表 时 Word 本身创建的绘图对象相同。以这种方式添加的图表不是图片；它是嵌入文档 OOXML 包中的 Chart 对象，拥有数据系列模型、坐标轴、图例以及数据表，文件保存后 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 — 传递给 InsertChart 的枚举 — 包含约 40 个成员，覆盖标准 Word 图表族：Line、Bar、Column、Pie、Doughnut、Radar、Scatter、Stock、Surface、Treemap、Sunburst、Histogram、Pareto、BoxAndWhisker、Waterfall 和 Funnel，以及其中若干的堆叠、百分比堆叠和 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 公开了一个带有自身 Text、Show 和 Font 的 ChartAxisTitle。
图例、数据表和图表标题
Chart.Legend 返回一个 ChartLegend，其 Position（一个由 None、Bottom、Left、Right、Top 或 TopRight 组成的 LegendPosition）控制它相对于绘图区的渲染位置；LegendEntries 是一个由各个 ChartLegendEntry 对象组成的 ChartLegendEntryCollection，每个对象都有自己的 Font 和 IsHidden 标志，用于在不将系列从图表中移除的情况下隐藏该系列在图例中的显示。Chart.DataTable（一个 ChartDataTable）在设置 Show 时将系列值以网格形式显示在图表下方，并由 HasLegendKeys、HasHorizontalBorder、HasVerticalBorder 和 HasOutlineBorder 控制其外观。Chart.Title 是一个具有 Text 和 Show 属性的 ChartTitle，遵循与坐标轴标题相同的模式。
数据标签、数据点和标记
ChartSeries.HasDataLabels 打开系列的数据标签，而 ChartSeries.DataLabels（一个 ChartDataLabelCollection）或其单独的 ChartDataLabel 控制每个标签显示的内容：ShowValue、ShowCategoryName、ShowSeriesName、ShowPercentage、ShowLegendKey 和 ShowBubbleSize 是独立的标志，Position（ChartDataLabelPosition.Center、InsideEnd、OutsideEnd、BestFit 等）将标签相对于其点放置。ChartSeries.DataPoints 通过 ChartDataPoint 提供逐点访问，后者拥有自己的 Marker（一个带有来自 MarkerSymbol 枚举的 Symbol 的 ChartMarker 和一个 Size）、Explosion（用于拉出饼图切片）以及 Format。所有可以填充或描边的图表元素——系列、数据点、图例、标题、数据表——都通过其 Format 属性公开一个 ChartFormat，并具有 Fill、Stroke 和 ShapeType（ChartShapeType）属性以及一个用于重置的 SetDefaultFill() 方法。需要注意的一点是：在 ChartFormat 上与主题关联的填充和描边颜色变体（FillableForeThemeColor、FillableBackThemeColor、StrokeForeThemeColor、StrokeBackThemeColor 以及它们的色调/阴影对应项）在此版本中未实现——请改用普通的 Fill/Stroke 颜色，而不是主题颜色引用。Chart.Style（一个如 Muted、Saturated、Gradient、Outline 或 Black 的 ChartStyle）在一步中为整个图表应用预定义的外观。
快速入门
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");
在 Word 中打开 chart.docx，该图表可完全编辑——右键单击它并选择“Edit Data”即可看到上面写的相同三个类别和数值。
支持的格式
| 格式 | 扩展名 | 读取 | 写入 |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| 扁平 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 for .NET 在 MIT 许可证下发布，免费用于商业和个人用途，无版税或再分发限制。完整源码，包括本文中引用的图表类，已在 GitHub 的 Aspose.Words FOSS for .NET 仓库 中提供。
