グラフとレポート

1つのテンプレートにグラフ、表、テキストを組み合わせて、売上、マーケティング、プロジェクトのレポートを作成できます。自分でグラフを作る場合、既製のレポートデザインを購入する必要はありません。

ジェネレーターでのグラフ作成

1. アセットからグラフを追加し、インスペクターで種類とタイトルを選択します。
2. 「グラフデータを編集」を開くと、系列名、色、カテゴリ、数値を編集できます。必要に応じて系列や行を追加してください。
3. 適用すると変更がグラフに反映されます。キャンセルすると、ダイアログ内での変更は破棄されます。テンプレートを保存し、プレビューと出力を確認してください。

種類と制限

縦棒、横棒、折れ線、面、円、ドーナツグラフに対応しています。JSONの種類コードは次のとおりです。

サンプルは同じ4行のデータから製品内蔵のグラフエンジンで描画し、種類のコードだけを変更しています。

各グラフは最大100カテゴリ、6系列に対応します。円グラフとドーナツグラフは1系列のみで、負の値は使用できません。

テンプレート要素の例

このオブジェクトは、schemaVersion: 2のテンプレートのelements配列内にあるグラフ要素です。生成リクエスト全体ではありません。この例では、content.dataに直接データを保存しています。

{
  "id": "monthly-revenue",
  "type": "chart",
  "placementMode": "flow",
  "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
  "content": {
    "title": "Revenue",
    "data": [{ "month": "Jan", "revenue": 42 }, { "month": "Feb", "revenue": 52 }]
  },
  "chart": {
    "type": "bar",
    "labelField": "month",
    "series": [{ "field": "revenue", "label": "Revenue", "color": "#e3232a" }],
    "showLegend": true,
    "showValues": true
  }
}

動的データのバインド

ドキュメントごとに異なるデータを使うには、グラフ要素にbinding: monthlyRevenueを追加し、リクエストデータにmonthlyRevenueという名前のオブジェクト配列を送信します。この場合、content.dataは削除してください。labelFieldでカテゴリのフィールドを指定し、各系列のfieldで数値フィールドを指定します。sales.netのような入れ子のパスにも対応しています。

欠損値や有限でない数値は0に変換せず、折れ線グラフと面グラフでは空白として扱います。円グラフやドーナツグラフの負の値は、元データで修正してください。密集したグラフでは、重なりを避けるため、一部の値ラベルが省略される場合があります。

実際のデータを使うレポート

monthlyRevenueに接続したグラフは、リクエストから同名の配列を読み取ります。テンプレートは変えず、呼び出すたびに数値だけを渡します。

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "sales-report",
        "format": "pdf",
        "locale": "ja",
        "data": {
          "monthlyRevenue": [
            { "month": "2026-01", "revenue": 42000, "target": 40000 },
            { "month": "2026-02", "revenue": 51500, "target": 45000 },
            { "month": "2026-03", "revenue": 47250, "target": 50000 }
          ]
        }
      }'

配列の各オブジェクトが1つのカテゴリーになります。labelFieldでカテゴリー名を選び、各系列のフィールドは同じオブジェクトから数値を取得します。

よくある問題

• bindingとcontent.dataは、どちらか一方を使います。両方を指定すると固定データが描画され続け、リクエストが無視されたように見えます。
• 系列の値は数値である必要があります。"42.000,00"は文字列です。読者向けの書式設定は、系列ではなくテキスト要素で行ってください。
• グラフは最大100点、6系列まで対応します。余分な行が描画されることを期待せず、送信前に集計してください。
• Wordでは、グラフは編集可能なWordグラフではなく画像です。クリックして編集することはできません。PDFとビューアーでも、同じ描画が表示されます。
• 100%は用紙全体ではなく、格納される領域の幅です。列や内側余白のあるコンテナー内では、ページ幅より狭くなります。

プレビューと出力の動作

グラフには共通のSVGレンダラーを使用します。PDFとViewerでは外観を保持します。Word出力には、編集可能なWordネイティブのグラフオブジェクトではなく、グラフの画像が含まれます。

幅100%は、用紙全体ではなく、親領域内で使用できる幅を意味します。ページの余白、段組み、内側の余白によって、この領域は小さくなります。