antv-g2-chart

G2 v5 チャート可視化

概要

G2 v5 は AntV の文法グラフィックス方式のチャートライブラリです。Spec Mode を使用します。これは宣言的な JSON 風の設定スタイルです。生成する例は完全な spec から始めてください。実行時のコードでは、後から chart.options() を通じてローカルの更新をマージできます。

import { Chart } from '@antv/g2';

const chart = new Chart({ container: 'container', autoFit: true });
chart.options({
  type: 'interval',
  data: [{ genre: 'Sports', sold: 275 }],
  encode: { x: 'genre', y: 'sold' },
});
chart.render();

CDN の使用

<script src="https://unpkg.com/@antv/g2@5/dist/g2.min.js"></script>
<script>
  const chart = new G2.Chart({ container: 'container', autoFit: true });
  chart.options({
    type: 'interval',
    data: [{ genre: 'Sports', sold: 275 }],
    encode: { x: 'genre', y: 'sold' },
  });
  chart.render();
</script>

コンテンツ取得サービス

データ可視化に AntV G2 を使用する際に、G2 v5 の概念、使用方法、API、例などについて理解する必要がある場合は、提供されているコンテキスト取得サービスを利用できます。このスキルでは、GET リクエストを使用して antv HTTP API サーバー経由でコンテンツを取得します。

• ホスト：https://sive.antv.antgroup.com
• エンドポイント：/api/v1/context/retrieve
• メソッド：GET
• パラメーター：query、library、topK、content、maxTokens

クエリでリファレンスドキュメントを取得します（ハイブリッド検索 = FTS + ベクトル + RRF 融合）。

パラメーター	型	必須	説明
query	string	✅	検索キーワード。例：bar chart interval
library	string	✅	ライブラリ名：g2、g6、x6
topK	number		返す結果の件数（デフォルト：5）
content	boolean		リファレンスドキュメントの Markdown 全文を返すかどうか（デフォルト：true）
maxTokens	number		結果あたりの最大トークン数（デフォルト：無制限）

curl "https://sive.antv.antgroup.com/api/v1/context/retrieve?query=bar+chart+stacked&library=g2"

重要なルール

必須：V5 Spec Mode のみを使用

// ❌ WRONG — V4 chain API (deprecated, will not render)
chart.interval()
  .data([...])
  .encode('x', 'genre')
  .encode('y', 'sold')
  .style({ radius: 4 });

// ✅ CORRECT — V5 Spec Mode
chart.options({
  type: 'interval',
  data: [...],
  encode: { x: 'genre', y: 'sold' },
  style: { radius: 4 },
});

複数のマークを重ねる場合は view + children を使用

chart.options() は増分的なディープマージ更新に対応しており、実行時のインタラクションに便利です。一度だけ実行するコードを生成する場合は、初期 spec 全体を指定してください。独立したマークを重ねるには、children を含む type: 'view' を1つ使用します。ルートの type を順番に変更しても、オーバーレイは作成されません。

// ❌ WRONG — this changes one root mark from line to point; it does not overlay them
chart.options({ type: 'line', data, encode: { x: 'date', y: 'value' } });
chart.options({ type: 'point', data, encode: { x: 'date', y: 'value' } });

// ✅ CORRECT — children array for multi-mark
chart.options({
  type: 'view',
  data,
  children: [
    { type: 'line',  encode: { x: 'date', y: 'value' } },
    { type: 'point', encode: { x: 'date', y: 'value' } },
  ],
});

必須：container を指定し、最後に chart.render() を呼び出す

// ❌ WRONG — no container, no render
const chart = new Chart();
chart.options({ type: 'interval', data });

// ✅ CORRECT
const chart = new Chart({ container: 'container', autoFit: true });
chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } });
chart.render();

必須：正しいマークタイプのみを使用

❌ 幻覚（ECharts/Vega 由来）	✅ G2 での正しい置き換え
type: 'ruleX'	type: 'lineX'
type: 'ruleY'	type: 'lineY'
type: 'regionX'	type: 'rangeX'
type: 'regionY'	type: 'rangeY'
type: 'venn'	type: 'path' + transform

G2 で使用できるマーク：interval、line、area、point、rect、cell、text、image、path、polygon、shape、link、connector、vector、lineX、lineY、rangeX、rangeY、range、box、boxplot、density、heatmap、beeswarm、treemap、pack、partition、tree、sankey、chord、wordCloud、gauge、liquid。sunburst には @antv/g2-extension-plot が必要です。

必須：encode はオブジェクト、transform は配列

// ❌ WRONG
.encode('x', 'genre')
.transform: { type: 'stackY' }

// ✅ CORRECT
encode: { x: 'genre', y: 'sold' }
transform: [{ type: 'stackY' }]

必須：labels は複数形。範囲のエンコーディングにはマークに適したチャンネルを使用

// ❌ WRONG
label: { text: 'sold' }

// ✅ CORRECT
labels: [{ text: 'sold' }]
// Interval / link ranges may use either a two-field array or y + y1.
encode: { y: ['start', 'end'] }
// RangeY explicitly uses y + y1.
encode: { y: 'start', y1: 'end' }

必須：ユーザーコードで d3 を使用しない

// ❌ WRONG — d3 is not exposed in user scope
const total = d3.sum(data, d => d.value);

// ✅ CORRECT — use native JS or G2 built-in transforms
const total = data.reduce((sum, d) => sum + d.value, 0);

必須：白色や白に近い塗りつぶしを使用しない。padding に配列を使用しない

// ❌ WRONG
style: { fill: '#fff' }       // invisible on white background
padding: [40, 30, 40, 50]     // invalid in G2 v5

// ✅ CORRECT
encode: { color: 'group' }    // let G2 assign colors
padding: 40                   // single number or 'auto'

必須：転置は座標タイプではなく、トランスフォームとして指定

// ❌ WRONG
coordinate: { type: 'transpose' }

// ✅ CORRECT
coordinate: { transform: [{ type: 'transpose' }] }

デフォルトの美観／デフォルトの視覚的基準

デフォルトでは、すべての図に同じ装飾を加えるのではなく、明快さ、控えめさ、読みやすさを重視します。まず以下の判断基準に従い、必要に応じて default+aesthetics+design を検索し、完全な例を取得してください。

2 種類の「デフォルト」を区別してください。G2 エンジンのデフォルト（theme/create.ts）は、line.lineWidth: 1、area.fillOpacity: 0.85、矩形の radius は角丸なしです。この節の Mark 基準にある radius: 4／lineWidth: 2／fillOpacity: 0.5~0.6 は、このスキルの規約値です。生成例の見栄えをよくするためにエンジンのデフォルトを上書きするものであり、style に明示的に記述する必要があります。省略しても適用されるものではありません。

1. 共通事項：container、完全な初期 chart.options() spec、chart.render() は必須です。通常の埋め込み型チャートでは、autoFit: true、theme: 'classic'、padding: 'auto' を優先してください。classic は視覚的な安定性を考慮して明示的に選択するライトテーマのプリセットであり、エンジンのデフォルトテーマではありません（エンジンのデフォルトは light と推論されます）。暗色のコンテナでは classicDark を使用してください。どちらも同じ category10 パレット（第一候補は #5B8FF9）を共有するため、安定した主色はライトテーマとダークテーマのどちらでも使用できます。
2. 色で意味を表現する：色が独立した系列、状態、グループを表す場合に限り、encode.color と凡例を使用してください。単一指標のカテゴリ比較では、安定した単色（例：style.fill: '#5B8FF9'。スタイル値として有効です）を使用し、色の凡例を無効にして、虹色の棒や冗長な凡例を避けてください。禁止されているのは、データ内に hex 文字列を保存し、それを encode.color のカテゴリフィールドとしてエンコードすることです。
3. Mark 基準（規約値。エンジンのデフォルトを上書きします）：interval では radius: 4（エンジンのデフォルトは角丸なし）、line では lineWidth: 2（エンジンのデフォルトは 1）、area では fillOpacity: 0.5~0.6（エンジンのデフォルトは 0.85 で、やや不透明なため、値を下げるとより軽やかになります）。これらの値はすべて style に明示的に記述する必要があり、省略しても適用されるものではありません。グラデーション、影、カスタムアニメーションは不要です。
4. テキストには既知の意味だけを使用する：フィールド／単位／出典が明確な場合は、意味のある軸タイトル、tooltip 名、formatter を追加してください。レポートの文脈がある場合、またはユーザーからタイトルが指定された場合は、トップレベルの title を追加してください。情報が不明な場合は省略し、単位、出典、副題を作り出さないでください。
5. 密度に応じてラベルを選ぶ：データ数が少なく、正確な読み取りが必要な場合はラベルを追加できます。密集した散布図、複数系列の折れ線、カテゴリ数が多い場合は、デフォルトで tooltip に頼ってください。inside ラベルには contrastReverse を使用し、衝突が発生する場合は overlapHide／overlapDodgeY／overflowHide を使用してください。dx／dy は、衝突を避けた後の微調整にのみ使用してください。
6. 特殊なチャート：円グラフ／ドーナツグラフでは、カテゴリ数が少ない場合は外部ラベルを優先し、カテゴリ数が多い場合は legend に切り替えてください。通常は両方を同時に重複して表示しないでください。バブルチャートでは G2 のデフォルトの sqrt サイズマッピングを維持し、データ範囲に応じて size.range を設定してください。size legend が理解の助けにならない場合に限り、非表示にしてください。

グラデーション、影、スライダー、スクロールバー、カスタムアニメーション、3D バブルは、ユーザーが明確に「レポート品質／洗練された仕上がり」を求めた場合の強化要素です。追加する前に、データを覆い隠したり、ラベルのコントラストを下げたりしないことを確認してください。

クイックリファレンス

ユーザーの意図	取得クエリ
チャートの初期化、コンテナ、autoFit	GET /api/v1/context/retrieve?query=chart+init&library=g2
棒グラフ／縦棒グラフ	GET /api/v1/context/retrieve?query=bar+chart+interval&library=g2
折れ線グラフ／面グラフ	GET /api/v1/context/retrieve?query=line+area+chart&library=g2
円グラフ／ドーナツグラフ／ローズチャート	GET /api/v1/context/retrieve?query=pie+chart+theta&library=g2
散布図／バブルチャート	GET /api/v1/context/retrieve?query=scatter+point+bubble&library=g2
ツリーマップ／サンバースト／パック	GET /api/v1/context/retrieve?query=treemap+sunburst+pack&library=g2
ヒートマップ／密度／箱ひげ図	GET /api/v1/context/retrieve?query=heatmap+density+boxplot&library=g2
ファネル／ゲージ／ワードクラウド	GET /api/v1/context/retrieve?query=funnel+gauge+wordcloud&library=g2
エンコードチャンネル（x、y、color、size）	GET /api/v1/context/retrieve?query=encode+channel&library=g2
スケール／パレット／色の範囲	GET /api/v1/context/retrieve?query=scale+palette+color&library=g2
座標（polar、theta、transpose）	GET /api/v1/context/retrieve?query=coordinate+polar+theta+transpose&library=g2
変換（stack、normalize、sort）	GET /api/v1/context/retrieve?query=transform+stack+normalize&library=g2
軸／凡例／tooltip／ラベル	GET /api/v1/context/retrieve?query=axis+legend+tooltip+label&library=g2
インタラクション（brush、highlight、drilldown）	GET /api/v1/context/retrieve?query=interaction+brush+highlight&library=g2
テーマ／ダークモード	GET /api/v1/context/retrieve?query=theme+dark+classicDark&library=g2
デフォルトの美観／視覚的基準	GET /api/v1/context/retrieve?query=default+aesthetics+design&library=g2
アニメーション	GET /api/v1/context/retrieve?query=animation+animate&library=g2
データの取得／フィルター／ソート	GET /api/v1/context/retrieve?query=data+fetch+filter+sort&library=g2
ファセット／ビュー構成	GET /api/v1/context/retrieve?query=facet+view+composition&library=g2
チャートタイプの選択ガイド	GET /api/v1/context/retrieve?query=chart+type+selection&library=g2
レンダリングのトラブルシューティング	GET /api/v1/context/retrieve?query=rendering+troubleshoot+debug&library=g2

依存関係

• @antv/g2 — G2 v5 チャートエンジン