Введение
В этом руководстве показано, как создавать нативные диаграммы Word с помощью Aspose.Words FOSS для .NET — тех же объектов рисования, которые Word создает при использовании Insert > Chart — полностью из кода. Диаграмма, добавленная таким способом, не является изображением; это объект 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 — перечисление, передаваемое в 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 раскрывает 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. Каждый элемент диаграммы, который может быть заполнен или обведён — серии, точки данных, легенда, заголовок, таблица данных — раскрывает 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), являются теми же подсистемами, которые исключены в остальных частях библиотеки, а не чем-то специфическим для диаграмм.
Open Source и лицензирование
Aspose.Words FOSS для .NET выпущен под лицензией MIT, свободно для коммерческого и личного использования без роялти и ограничений на распространение. Полный исходный код, включая классы диаграмм, упомянутые в этом посте, доступен на GitHub в Aspose.Words FOSS for .NET repository.
