Aspose.Cells for Node.js via Java でスパークラインを画像および HTML に変換する

Introduction

スパークラインは、ワークシート内で直接トレンドを視覚化するためのコンパクトな手段です。Excel ユーザーはセル内でそれらを確認しますが、実世界の多くのシナリオでは、スパークラインをセル外に取り出す必要があります。たとえば、別のセルに静的な画像として埋め込んだり、自動メールに添付したり、Web に公開された HTML レポートの一部としてレンダリングしたりする場合です。 Aspose.Cells はこれら両方の操作をサポートしています。Sparkline.toImage メソッドは個々のスパークラインをストリームにレンダリングし、その結果得られるバイト列を Cell.EmbeddedImage に割り当てることができます。これにより、画像がワークブックの単一セル内に保存されます。一方、HtmlSaveOptions を使用すると、ワークブック全体(スパークラインを含むすべて)を自己完結型の HTML ファイルに変換できます。本記事では、両方のワークフローを順を追って説明します。

Workflow 1 — Render Sparklines to Images and Embed Them into Cells

このワークフローでは、ソース値の小範囲を含むワークシートを作成し、その範囲に 3 つの異なるスパークライングループ(Line、Column、Stacked/Win-Loss)を関連付け、各グループを PNG としてレンダリングして、それらの PNG バイトを隣接するセルに埋め込み画像として書き込みます。最終結果は、ライブのスパークラインとそのレンダリングされたピクチャの両方を含む単一の .xlsx ファイルです。

Step-by-Step Instructions

  1. 作業ディレクトリを定義し、ディスク上に存在することを確認します。
  2. 新しい Workbook を作成し、最初の Worksheet への参照を取得します。
  3. セル A1 から E1 に 5 つのサンプル数値(たとえば、日次売上や気温の測定値など)を入力します。
  4. worksheet.sparklineGroups.add(...) を呼び出して、ワークシートに 3 つの SparklineGroup オブジェクトを追加します:
    • F1 にアンカーされ、データ範囲が A1:E1 の SparklineType.Line グループ。
    • G1 にアンカーされ、データ範囲が A1:E1 の SparklineType.Column グループ。
    • H1 にアンカーされ、データ範囲が A1:E1 の SparklineType.Stacked(win/loss)グループ。
  5. ImageOrPrintOptions インスタンスを作成し、その ImageType を ImageType.Png に設定して、各スパークラインが透明な PNG としてレンダリングされるようにします。
  6. ワークブックを output_with_sparklines.xlsx として保存します。
const AsposeCells = require("aspose.cells");
let workbook = new AsposeCells.Workbook();
let worksheet = workbook.getWorksheets().get(0);
// Populate sample data in cells A1:E1
worksheet.getCells().get("A1").putValue(5);
worksheet.getCells().get("B1").putValue(-3);
worksheet.getCells().get("C1").putValue(8);
worksheet.getCells().get("D1").putValue(-2);
worksheet.getCells().get("E1").putValue(6);
// Add a Line sparkline group anchored at F1 (column 5, row 0)
let lineArea = new AsposeCells.CellArea();
lineArea.StartColumn = 5;
lineArea.EndColumn = 5;
lineArea.StartRow = 0;
lineArea.EndRow = 0;
let lineIdx = worksheet.getSparklineGroups().add(AsposeCells.SparklineType.LINE, "A1:E1", false, lineArea);
// Add a Column sparkline group anchored at G1 (column 6, row 0)
let columnArea = new AsposeCells.CellArea();
columnArea.StartColumn = 6;
columnArea.EndColumn = 6;
columnArea.StartRow = 0;
columnArea.EndRow = 0;
let columnIdx = worksheet.getSparklineGroups().add(AsposeCells.SparklineType.COLUMN, "A1:E1", false, columnArea);
// Add a Win/Loss (Stacked) sparkline group anchored at H1 (column 7, row 0)
let stackedArea = new AsposeCells.CellArea();
stackedArea.StartColumn = 7;
stackedArea.EndColumn = 7;
stackedArea.StartRow = 0;
stackedArea.EndRow = 0;
let stackedIdx = worksheet.getSparklineGroups().add(AsposeCells.SparklineType.STACKED, "A1:E1", false, stackedArea);
// Configure image options for PNG output
let imageOptions = new AsposeCells.ImageOrPrintOptions();
imageOptions.setImageType(AsposeCells.ImageType.PNG);
// Convert the Line sparkline to image and embed it in cell F2
let lineSp = worksheet.getSparklineGroups().get(lineIdx).getSparklines().get(0);
let lineMs = new java.io.ByteArrayOutputStream();
lineSp.toImage(lineMs, imageOptions);
worksheet.getCells().get("F2").setEmbeddedImage(lineMs.toByteArray());
// Convert the Column sparkline to image and embed it in cell G2
let columnSp = worksheet.getSparklineGroups().get(columnIdx).getSparklines().get(0);
let columnMs = new java.io.ByteArrayOutputStream();
columnSp.toImage(columnMs, imageOptions);
worksheet.getCells().get("G2").setEmbeddedImage(columnMs.toByteArray());
// Convert the Win/Loss sparkline to image and embed it in cell H2
let stackedSp = worksheet.getSparklineGroups().get(stackedIdx).getSparklines().get(0);
let stackedMs = new java.io.ByteArrayOutputStream();
stackedSp.toImage(stackedMs, imageOptions);
worksheet.getCells().get("H2").setEmbeddedImage(stackedMs.toByteArray());
// Save the workbook to disk
workbook.save("output_with_sparklines.xlsx");

上記のコードにより、スパークラインの各視覚表現が 2 つの形式で複製されたワークブックが生成されます。1 行目にアンカーされたライブのネイティブスパークラインと、2 行目の隣接するセルに直接埋め込まれた静的な PNG ピクチャです。ピクチャはファイル自体に格納されているため、ワークブックは埋め込み画像参照が壊れることなくメール送信やアーカイブが可能な単一の自己完結型の成果物のままです。各スパークライングループを PNG としてレンダリングし、ByteArrayOutputStream を byte[] に変換して、その配列を対象セルの setEmbeddedImage プロパティに割り当てます。この割り当てによって、ピクチャがセルの格納コンテンツの一部となります。

Workflow 2 — Export the Sparkline Worksheet to HTML

ワークブックにライブのスパークライン(およびオプションで埋め込まれたピクチャ)が含まれるようになると、ワークシート全体を HTML として保存することで Web に公開できます。HtmlSaveOptions クラスには、このエクスポートを制御するために必要な機能が用意されています。このワークフローでは、ワークフロー 1 で生成された output_with_sparklines.xlsx ファイルを再利用して、クリーンな単一ページの HTML ドキュメントに変換します。

Step-by-Step Instructions

  1. ワークフロー 1 で生成された output_with_sparklines.xlsx ファイルが、作業ディレクトリ内のディスク上で利用可能であることを確認します。
  2. そのファイルを新しい Workbook インスタンスに読み込みます。
  3. HtmlSaveOptions をインスタンス化し、その ExportActiveWorksheetOnly プロパティを true に設定します。これにより、結果として生成される HTML ファイルにはワークブック全体ではなく、アクティブなワークシートのみが含まれるようになります。
  4. workbook.save("sparklines.html", htmlOptions) を呼び出して、HTML 出力をディスクに書き込みます。
const AsposeCells = require("aspose.cells");
let workbook = new AsposeCells.Workbook("output_with_sparklines.xlsx");
let htmlOptions = new AsposeCells.HtmlSaveOptions();
htmlOptions.setExportActiveWorksheetOnly(true);
workbook.save("sparklines.html", htmlOptions);

上記のコードは、ワークフロー 1 からのスパークラインを含むワークブックを、ポータブルな HTML ファイルに変換します。スパークラインは、エクスポートモードに応じて生成された HTML 内でインライン SVG または PNG レンダリングとして保持されるため、エンドユーザーは Excel がインストールされていなくても、モダンなブラウザでトレンドを確認できます。ExportActiveWorksheetOnly を true に設定することで、非表示シートや補助データを誤って公開するのを防ぎ、現在ユーザーに表示されているワークシートのみがエクスポートされます。

API Summary

上記のワークフローは、Aspose.Cells API の小さなセットが連携して動作することに依存しています。

  • SparklineGroup およびコレクションアクセサ worksheet.sparklineGroups は、各スパークライングループのタイプ(Line、Column、Stacked)、データ範囲、アンカーセルを宣言するために使用されます。本記事では各グループが単一のセルにアンカーされているため、グループには worksheet.sparklineGroups[i] を通じてアクセスします。
  • Sparkline およびインデクサ group.sparklines[0] は、グループ内の個々のスパークラインを返します。例のすべてのグループには正確に 1 つのスパークラインが含まれているため、forEach ループは必要ありません。
  • Sparkline.toImage(OutputStream, ImageOrPrintOptions) は、提供された OutputStream にスパークラインのピクチャを書き込むレンダリングメソッドです。このメソッドは void を返します。呼び出し後にストリームからバイトを読み取ります。
  • HtmlSaveOptions.ExportActiveWorksheetOnly(boolean)は、HTML エクスポートをアクティブなワークシートのみに制限します。これは、単一ページレポートを生成する際に HtmlSaveOptions で最も一般的に使用されるプロパティの 1 つです。
  • ImageOrPrintOptions.ImageType は com.aspose.cells.drawing 名前空間にあり、toImage を使用してレンダリングする際、およびワークシートを画像に印刷する際のピクチャ形式(たとえば ImageType.Png)を選択します。