インタラクティブ・ガイド
Chart.js アノテーションプラグイン (2025年版)
このガイドでは、`chartjs-plugin-annotation`の基本的な使い方から動的な設定までを、実際に操作しながら学ぶことができます。
インタラクティブ・エクスプローラー
左のコントロールを操作して、リアルタイムでチャートと設定コードが変化するのを確認しましょう。
アノテーション設定
データ操作
ライブ設定コード
主要コンセプトとベストプラクティス
CDN読み込みと登録
最新版のライブラリはCDN経由で簡単に利用できます。多くの場合プラグインは自動登録されますが、互換性を考慮し、明示的に`Chart.register()`を呼び出すのが安全です。
動的アノテーション
JavaScriptを使ってデータ（例: 最大値、平均値）を計算し、その結果をアノテーションの`yMin`や`yMax`プロパティに設定することで、データに連動した注釈を簡単に描画できます。
レスポンシブ対応
Chart.jsはデフォルトでレスポンシブ対応ですが、`maintainAspectRatio: false`を設定し、親コンテナでサイズを制御することで、より柔軟なレイアウトが可能です。
特殊タイプ: Doughnut Label (ドーナツ中央注釈)
`doughnutLabel`タイプは、**ドーナツチャートまたはパイチャートの中心にテキストを配置するため**に特化したアノテーションです。複数行のコンテンツを異なるフォントや色で柔軟に構成できますが、**LineチャートやBarチャートでは機能しません**。以下のコードは、対応するチャートでの設定リファレンスです。
設定例（コードリファレンス）:
Chart.js アノテーションタイプ完全一覧
標準アノテーションタイプ（2軸チャート用）
| 種類名 | type 値 | 主な用途・説明 | 備考 |
|---|---|---|---|
| Line | 'line' | 軸に沿った直線を描画。閾値・平均線・基準線の表示に使用。 | 水平・垂直どちらも可。xMin / xMax / yMin / yMax で範囲指定。 |
| Box | 'box' | 指定範囲を矩形で強調。ゾーン・期間・目標範囲の可視化に使用。 | 背景色、枠線、角丸、シャドウなど豊富なスタイル設定が可能。 |
| Point | 'point' | 特定座標のマーカー表示。注目データ点を示すのに最適。 | xValue / yValue で位置指定。pointStyle で形状変更可。 |
| Ellipse | 'ellipse' | 円・楕円形の範囲を描画。分布内のエリアを強調したい場合など。 | xMin / xMax / yMin / yMax で外接矩形を指定。 |
| Label | 'label' | 任意座標にテキストラベルを表示。コメント・注釈などに使用。 | 単独でも利用可能。画像・Canvas要素も表示可能。 |
| Polygon | 'polygon' | 多角形領域の描画。複雑形状のエリア強調に使用。 | sides / radius で正多角形、points 配列で任意形状を指定。 |
特殊アノテーションタイプ
| 種類名 | type 値 | 主な用途・説明 | 備考 |
|---|---|---|---|
| Doughnut Label | 'doughnutLabel' | ドーナツチャート中央にテキスト・画像・Canvasコンテンツを表示。 | ドーナツチャート専用。複数行、行ごとに異なるフォント・色指定が可能。 |
対応チャートタイプ
標準アノテーション（Line / Box / Point / Ellipse / Label / Polygon）
対応: line, bar, scatter, bubble チャート
軸要件: 2軸必須（linear, logarithmic, time, category スケール）
非対応: pie, radar, polar area チャート（2軸を持たないため）
Doughnut Label アノテーション
対応: doughnut チャート専用
用途: 中央エリアへのコンテンツ追加
主要プロパティ早見表
| タイプ | 位置指定 | スタイル設定 | その他 |
|---|---|---|---|
| Line | xMin/xMax/yMin/yMax, value/endValue | borderColor, borderWidth, borderDash | label で注釈追加可 |
| Box | xMin/xMax/yMin/yMax | backgroundColor, borderColor, borderRadius | 透明度・枠線スタイル調整可 |
| Point | xValue, yValue | radius, backgroundColor, borderColor | pointStyle でアイコン変更可 |
| Ellipse | xMin/xMax/yMin/yMax | backgroundColor, borderColor | 円形・楕円形の範囲指定 |
| Label | xValue/yAdjust or xAdjust/yValue | font, color, backgroundColor, padding | 自由なテキスト配置 |
| Polygon | points 配列（座標リスト） | backgroundColor, borderColor | 任意の多角形を作成 |
| DoughnutLabel | 自動（ドーナツ中央） | font, color | content で動的表示可 |
使用例
Line アノテーション（閾値表示）:
Doughnut Label アノテーション（中央表示）:
バージョン情報
v2.0+: 基本タイプ（Line, Box, Point, Ellipse, Label, Polygon）実装
v3.0+: Doughnut Label 追加
最新版: v3.1.0（2024年時点）
Chart.js 本体は v2.4.0 以降で対応。
初心者向けの注意事項
Chart.jsアノテーションプラグインを初めて使用する際に、以下の点に留意してください。これらの注意事項は、スムーズな学習と実装を支援します。
ライブラリの依存関係を確認
`chartjs-plugin-annotation`を使用するには、Chart.js本体（v2.4.0以降）が必要です。CDNまたはnpmで正しいバージョンを読み込んでください。
チャートタイプの適合性を理解
標準アノテーション（例: Line, Box）は2軸（X軸とY軸）を持つチャート（line, barなど）でのみ動作します。Doughnut Labelはドーナツチャート専用です。
プロパティの設定に注意
アノテーションの位置（例: xMin, yValue）やスタイル（例: borderColor）は、チャートのスケールやデータ範囲に合わせて設定してください。値が範囲外だと表示されない場合があります。
デバッグの基本
アノテーションが表示されない場合、ブラウザの開発者ツール（コンソール）でエラーを確認し、`type`や`enabled`プロパティが正しいかチェックしてください。
レスポンシブデザインの考慮
チャートとアノテーションは画面サイズに応じて調整されます。親コンテナの幅や高さを適切に設定し、`maintainAspectRatio: false`を活用してください。
よくある質問（FAQ）
Q: アノテーションがチャートに表示されないのはなぜですか？
A: 以下の原因が考えられます：(1) プラグインが正しく読み込まれていない、(2) チャートタイプが非対応（例: pieチャートで標準アノテーションを使用）、(3) 位置指定（xMin/yMaxなど）がチャートのスケール範囲外、(4) `enabled: false`が設定されている。コンソールでエラーを確認し、設定を見直してください。
Q: ドーナツチャート以外でDoughnut Labelを使用できますか？
A: いいえ、`doughnutLabel`はドーナツチャート専用です。他のチャート（例: line, bar）では`label`タイプを使用してください。
Q: アノテーションのスタイルをカスタマイズするにはどうすればよいですか？
A: `borderColor`, `backgroundColor`, `font`, `borderWidth`などのプロパティを調整してください。たとえば、Lineアノテーションの`borderDash: [6, 6]`で破線を設定できます。
Q: 動的にアノテーションを更新する方法は？
A: データに基づいて`yMin`, `yMax`, `xValue`などの値を計算し、チャートの`options.plugins.annotation.annotations`を更新後、`chart.update()`を呼び出してください。このガイドのインタラクティブ・エクスプローラーを参考にしてください。
Q: 古いバージョンのChart.jsでも動作しますか？
A: `chartjs-plugin-annotation`はChart.js v2.4.0以降で動作しますが、最新機能（例: Doughnut Label）はv3.0以降が必要です。最新バージョンの使用を推奨します。
CDNの使用について
Chart.jsおよび`chartjs-plugin-annotation`は、CDN（Content Delivery Network）を利用することで簡単にプロジェクトに組み込むことができます。以下のガイドラインに従ってください。
推奨CDN
信頼性の高いCDNとして、jsDelivr（`https://cdn.jsdelivr.net`）を使用してください。本ガイドでは以下のURLを使用しています：
バージョンの選択
最新バージョンを指定しない場合（例: `@latest`）、互換性の問題が発生する可能性があります。Chart.js v2.4.0以降および`chartjs-plugin-annotation` v3.1.0（2024年時点）を推奨します。
読み込み順序
Chart.js本体を先に読み込み、その後に`chartjs-plugin-annotation`を読み込んでください。順序が逆だとプラグインが正しく動作しません。
プラグインの登録
最新バージョンでは自動登録されますが、明示的に`Chart.register(ChartAnnotationPlugin)`を呼び出すことで、互換性と安定性を確保できます。
代替手段
CDNを使用せず、npmでインストールする場合は、`npm install chart.js chartjs-plugin-annotation`を実行し、モジュールとしてインポートしてください。
コメント