Вступ
У цьому посібнику показано, як створювати рідні діаграми Word за допомогою Aspose.Words FOSS для .NET — ті ж об’єкти малювання, які Word створює, коли ви використовуєте Вставка > Діаграма — повністю з коду. Діаграма, додана таким способом, не є зображенням; це об’єкт Chart, вбудований у пакет OOXML документа, з моделлю серій даних, осями, легендою та таблицею даних, яку Word все ще може відкривати та редагувати після збереження файлу. Цей пост — глибоке занурення у 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, а також складені, відсотково-складені та 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 (a ChartDataLabelCollection) або окремий ChartDataLabel з неї контролює, що саме показує кожен підпис: ShowValue, ShowCategoryName, ShowSeriesName, ShowPercentage, ShowLegendKey та ShowBubbleSize — це незалежні прапорці, а Position (ChartDataLabelPosition.Center, InsideEnd, OutsideEnd, BestFit та інші) розташовує підпис відносно його точки. ChartSeries.DataPoints забезпечує доступ до окремих точок через ChartDataPoint, який містить власний Marker (a ChartMarker з Symbol з переліку MarkerSymbol та Size), Explosion (для витягування частки пирога) і Format. Кожен елемент діаграми, який можна заповнити або окреслити — серії, точки даних, легенда, заголовок, таблиця даних — надає ChartFormat через властивість Format, з властивостями Fill, Stroke та ShapeType (ChartShapeType) і методом SetDefaultFill() для скидання. Одне зауваження, яке варто знати: варіанти заповнення та кольору обведення, пов’язані з темою, у ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor та їх аналогічні відтінки) не реалізовані в цьому випуску — задайте прості кольори Fill/Stroke замість посилань на кольори теми. Chart.Style (a ChartStyle such as 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), — це ті ж підсистеми, що виключені скрізь у бібліотеці, а не щось специфічне для діаграм.
Відкритий код та ліцензування
Aspose.Words FOSS для .NET випущено під ліцензією MIT, безкоштовно для комерційного та особистого використання без роялті чи обмежень на розповсюдження. Повний вихідний код, включаючи класи діаграм, згадані в цьому дописі, доступний на GitHub у Aspose.Words FOSS для .NET repository.
