소개
이 가이드는 Aspose.Words FOSS를 사용하여 .NET용 네이티브 Word 차트를 만드는 방법을 보여줍니다 — Insert > Chart를 사용할 때 Word 자체가 생성하는 동일한 그리기 개체 — 전부 코드를 통해 구현합니다. 이렇게 추가된 차트는 그림이 아니라 Chart 객체로, 문서의 OOXML 패키지에 삽입되며 데이터 시리즈 모델, 축, 범례 및 Word가 파일 저장 후에도 열고 편집할 수 있는 데이터 테이블을 포함합니다. 이 게시물은 해당 차트 API에 대한 심층 분석으로, 차트를 생성하고, 시리즈 데이터를 추가하며, 축, 범례, 데이터 레이블 및 렌더링 방식을 제어하는 형식 지정 객체에 접근하는 방법을 다룹니다.
이 라이브러리는 MIT 라이선스를 사용하며 네이티브 종속성이 없습니다. .NET Standard 2.0을 목표로 하므로 이 게시물의 코드는 .NET Framework 4.6.2+ 및 .NET 6, 8, 10에서도 그대로 실행됩니다. NuGet를 통해 설치하거나 소스에서 직접 빌드하십시오 — 아래 Quick Start를 참고하세요. 여기서 보여지는 모든 내용은 상용 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에 전달되는 열거형 — 은 표준 Word 차트 패밀리를 포괄하는 약 40개의 멤버를 가지고 있습니다: 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( LegendPosition of None, Bottom, Left, Right, Top, 또는 TopRight)는 플롯 영역에 대한 렌더링 위치를 제어합니다; LegendEntries은 개별 ChartLegendEntry 객체들의 ChartLegendEntryCollection이며, 각 객체는 차트에서 해당 시리즈를 제거하지 않고 범례에서 숨기기 위한 자체 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 with Symbol from the MarkerSymbol enum and a Size), Explosion (파이 슬라이스를 분리하기 위한), 및 Format이 포함됩니다. 채우기 또는 외곽선이 가능한 모든 차트 요소—시리즈, 데이터 포인트, 범례, 제목, 데이터 테이블—는 ChartFormat을 Format 속성을 통해 노출하며, Fill, Stroke, 및 ShapeType (ChartShapeType) 속성과 이를 초기화하는 SetDefaultFill() 메서드를 가집니다. 알아두면 좋은 주의사항: ChartFormat (FillableForeThemeColor, FillableBackThemeColor, StrokeForeThemeColor, StrokeBackThemeColor 및 그들의 tint/shade 변형) 에 대한 테마 연동 채우기 및 스트로크 색상은 이 버전에서 구현되지 않았습니다 — 테마 색상 참조 대신 일반 Fill/Stroke 색상을 설정하십시오. Chart.Style (a ChartStyle such as Muted, Saturated, Gradient, Outline, or Black) 은(는) 한 번에 전체 차트에 미리 정의된 모양을 적용합니다.
빠른 시작
Aspose.Words FOSS for .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 | ✓ | ✓ |
| Flat OPC (모든 변형) | (다양한) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Chart API으로 만든 차트는 OOXML 드로잉 객체이며, 따라서 위에서 언급한 DOCX 계열 포맷(DOCX, DOCM, DOTX, DOTM, Flat OPC) 간에 라운드 트립됩니다. 이 버전은 PDF, XPS 또는 이미지로 내보내거나 인쇄할 수 없으므로 차트를 비트맵으로 렌더링하는 것이 없습니다—차트는 워드 파일 안에서 살아있는 편집 가능한 객체로 남아 있습니다. 이 버전에서 제거된 추가 포맷 변환기(DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, 및 WordML)는 라이브러리 전반에서 제외된 동일한 서브시스템이며, 차트에만 특화된 것이 아닙니다.
오픈 소스 및 라이선스
Aspose.Words FOSS for .NET은 MIT 라이선스로 배포되며, 상업적 및 개인적 사용이 무료이고 로열티나 재배포 제한이 없습니다. 이 게시물에서 언급된 차트 클래스들을 포함한 전체 소스는 GitHub에 있는 Aspose.Words FOSS for .NET 저장소에서 확인할 수 있습니다.
