はじめに

このガイドでは、.NET 用に Aspose.Words FOSS を使用してネイティブな Word チャートを構築する方法を、コードだけで完全に示します — Insert > Chart を使用したときに 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 プロパティが他のすべてへのエントリーポイントです。新しく挿入されたチャートにはデフォルトの系列が既に存在するため、ほとんどのコードはまずそれをクリアし、ChartSeriesCollection である Chart.Series を通じて独自のデータを追加します。

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 の2つが追加されており、ChartType は直接公開していません。ChartSeriesGroup がコンボチャートを可能にする要素です：Chart.SeriesGroups（ChartSeriesGroupCollection）は、チャート内の各シリーズタイプごとに1つのグループを保持し、各グループは独自の 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（None、Bottom、Left、Right、Top、または TopRight の LegendPosition）はプロット領域に対する描画位置を制御します；LegendEntries は個々の ChartLegendEntry オブジェクトの ChartLegendEntryCollection であり、各オブジェクトは単一のシリーズを凡例から非表示にするための独自の 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 で、MarkerSymbol 列挙型からの Symbol と Size を含む）、Explosion（円グラフのスライスを引き出すため）、および Format が含まれます。塗りつぶしや輪郭線を設定できるすべてのチャート要素—系列、データ ポイント、凡例、タイトル、データ テーブル—は、その Format プロパティを通じて ChartFormat を公開し、Fill、Stroke、ShapeType（ChartShapeType）プロパティとリセット用の SetDefaultFill() メソッドを備えています。覚えておくべき注意点として、ChartFormat 上のテーマ連動の塗りつぶしおよびストロークカラー（FillableForeThemeColor、FillableBackThemeColor、StrokeForeThemeColor、StrokeBackThemeColor とそれらのティント/シェード バリエーション）はこのエディションでは実装されていません — テーマカラー参照の代わりに単純な Fill/Stroke カラーを設定してください。Chart.Style（ChartStyle で、Muted、Saturated、Gradient、Outline、または 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 へのプロジェクト参照を追加します。参照が設定されると、1 つの系列を持つ折れ線グラフが作成され、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」を選択すると、上記と同じ 3 つのカテゴリと値が表示されます。

対応フォーマット

形式拡張子読み取り書き込み
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 リポジトリ で入手可能です。

開始ガイド

関連リソース