syncfusion-react-bullet-chart

Syncfusion React Bullet Chart の実装

Syncfusion の React Bullet Chart コンポーネントを実装およびカスタマイズするためのスキルです。Bullet Chart は、定性的な範囲内で主要な測定値（実績値）と目標値を比較する、コンパクトなデータ可視化コンポーネントです。

このスキルを使用する場面

次のようなニーズがある場合に、このスキルを使用してください。

• 目標との比較を含むパフォーマンス指標や KPI を表示する
• 実績値と目標値を示すコンパクトなデータ可視化を作成する
• 定性的な範囲（低い／良好／優秀）を使用して目標に対する進捗を可視化する
• 省スペースのパフォーマンス指標を用いたダッシュボードを構築する
• フィーチャー測定値（実績を表すバー）を比較測定値（目標を表すバー）と比較して表示する
• 水平または垂直の Bullet Chart を実装する
• 複数の指標をコンパクトなレイアウトで表示する
• アクセシブルで、キーボード操作に対応したチャートの可視化を作成する

コンポーネントの概要

Bullet Chart は次の要素で構成されます。

• 値バー（フィーチャー測定値）：測定対象となる主要なデータ／実績値
• 比較バー（目標マーカー）：目標値または比較値
• 定性的な範囲：パフォーマンスレベル（例：低い、十分、良好）を示す背景帯
• 定量的な目盛り：数値を示す軸
• タイトル／サブタイトル：チャートの説明テキスト

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

API リファレンス

📄 参照： references/api.md

• 例全体で使用されている BulletChartComponent の props、メソッド、イベント、ディレクティブをまとめています

データバインディング

📄 参照： references/data-binding.md

値バーの設定

📄 参照： references/value-bar.md

• 値バー（フィーチャー測定値）の概要と目的
• データソースからの valueField のマッピング
• 実績バーの形状の種類（Rect、Dot）
• type プロパティによるバーの種類の変更
• valueBorder（色、幅）を使用した枠線のカスタマイズ
• valueFill を使用した塗りつぶし色のカスタマイズ
• valueHeight を使用した高さのカスタマイズ
• dataSource からの色の動的なバインディング
• 各カスタマイズオプションの完全な例

比較バーの設定

📄 参照： references/comparative-bar.md

• 比較バー（目標測定値）の概要
• データソースからの targetField のマッピング
• 目標バーの形状の種類（Circle、Cross、Rect）
• targetTypes プロパティによる目標の種類の変更
• targetColor による目標の外観のカスタマイズ
• targetWidth プロパティによる目標の幅の調整
• dataSource からの目標色のバインディング
• 各目標タイプの完全な例

範囲の設定

📄 参照： references/ranges.md

• 定性的な帯域（良好、低い、十分）を表す範囲
• BulletRangeCollectionDirective と BulletRangeDirective の使用
• end プロパティによる範囲境界の設定
• 範囲の開始点としての最小値について
• 品質レベルごとの複数範囲の設定
• color プロパティによる色のカスタマイズ
• opacity プロパティによる不透明度の調整
• 複数の色付き範囲を含む完全な例

タイトルとサブタイトル

📄 参照： references/titles.md

• title プロパティによるチャートタイトルの追加
• 補足情報を示すサブタイトルの追加
• titlePosition プロパティによるタイトルの配置（Left、Right、Top、Bottom）
• デフォルト位置（Top）の動作
• titleStyle（色、不透明度、フォントプロパティ）によるタイトルスタイルのカスタマイズ
• subtitleStyle（色、不透明度、フォントプロパティ）によるサブタイトルスタイルのカスタマイズ
• 各配置の完全な例
• フォントのカスタマイズ例（サイズ、ファミリー、太さ、スタイル）

ツールチップ

📄 参照: references/tooltips.md

• デフォルトのツールチップの動作（デフォルトでは非表示）
• tooltip.enable プロパティを使用したツールチップの有効化
• サービスへの BulletTooltip モジュールの注入
• ホバー時の実績値と目標値の表示
• template プロパティを使用したカスタムテンプレートの作成
• テンプレート内での ${target} と ${value} プレースホルダーの使用
• ツールチップの外観のカスタマイズ（fill、border、textStyle）
• ツールチップのテキストのフォントのカスタマイズ
• デフォルトおよびカスタムツールチップの完全なサンプル

データラベル

📄 参照: references/data-labels.md

• 実際のバーの値を識別するデータラベル
• dataLabel.enable プロパティを使用したデータラベルの有効化
• ラベルの表示動作と配置
• labelStyle プロパティを使用したスタイルのカスタマイズ
• フォントのプロパティ（サイズ、ファミリー、ウェイト、スタイル）
• 色と不透明度の調整
• スタイルを適用したデータラベルの完全なサンプル

軸のカスタマイズ

📄 参照: references/axis-customization.md

• MajorTickLines のカスタマイズ（幅、高さ、色、useRangeColor）
• MinorTickLines のカスタマイズ（幅、高さ、色、useRangeColor）
• tickPosition（Inside、Outside）を使用した目盛りの配置
• labelFormat を使用したラベルの書式設定（globalize 形式：n1、n2、p1、c1 など）
• 一般的な数値、パーセンテージ、通貨の形式を示す形式の表
• enableGroupSeparator を使用した千の位の区切り
• ${value} プレースホルダーを使用したカスタムラベル形式
• labelPosition（Inside、Outside）を使用したラベルの配置
• opposedPosition プロパティを使用した反対側への配置
• X 軸の categoryField を使用したカテゴリラベル
• categoryLabelStyle と labelStyle を使用したカテゴリラベルのスタイル設定
• 範囲の色に合わせたラベルの色設定に使用する useRangeColor
• 各軸機能の完全なサンプル

チャートの寸法

📄 参照: references/dimensions.md

• インラインスタイルと CSS によるコンテナーサイズの設定
• width および height プロパティを使用したチャートの寸法設定
• 固定寸法のピクセル指定
• コンテナーに対するレスポンシブな動作のパーセンテージ指定
• デフォルトのサイズ動作（高さ 126px、ウィンドウ幅）
• コンテナーと直接指定によるサイズ設定の完全なサンプル

カスタマイズオプション

📄 参照: references/customization.md

• orientation プロパティによる向きの指定（Horizontal、Vertical）
• デフォルトの Horizontal の向き
• enableRtl プロパティによる右から左（RTL）のサポート
• animation プロパティによるアニメーションの設定（duration、delay）
• 実績バーと目標バーの線形アニメーション
• theme プロパティによるテーマのサポート
• 利用可能な Syncfusion テーマ
• 各カスタマイズの完全なサンプル

アクセシビリティ

📄 参照: references/accessibility.md

• アクセシビリティへの準拠（ADA、Section 508、WCAG 2.2）
• 対応状況を含むアクセシビリティ機能の表
• WAI-ARIA の属性とパターン（img role、button role、aria-label、aria-pressed）
• キーボード操作のサポート（Tab、Shift+Tab、Ctrl+P）
• スクリーンリーダーのサポート
• 国際化のための右から左（RTL）への対応
• 色のコントラストへの準拠
• モバイルデバイスのサポート
• accessibility-checker と axe-core ツールを使用したテスト
• アクセシビリティのサンプルデモへの参照

クイックスタートのサンプル

import { BulletChartComponent, BulletRangeCollectionDirective, BulletRangeDirective, BulletTooltip, Inject } from '@syncfusion/ej2-react-charts';

function App() {
  const data = [
    { value: 270, target: 250 }
  ];

  return (
    <BulletChartComponent
      id="bulletChart"
      dataSource={data}
      valueField="value"
      targetField="target"
      title="Revenue"
      minimum={0}
      maximum={300}
      interval={50}
      tooltip={{ enable: true }}
    >
      <BulletRangeCollectionDirective>
        <BulletRangeDirective end={150} color="red" />
        <BulletRangeDirective end={250} color="yellow" />
        <BulletRangeDirective end={300} color="green" />
      </BulletRangeCollectionDirective>
      <Inject services={[BulletTooltip]} />
    </BulletChartComponent>
  );
}

よく使われるパターン

複数の指標を含むパフォーマンスダッシュボード

複数の KPI を表示するため、複数のブレットチャートを縦に並べます。

const metrics = [
  { value: 270, target: 250, category: 'Revenue' },
  { value: 85, target: 100, category: 'Profit' },
  { value: 180, target: 150, category: 'Sales' }
];

// Map each metric to a separate BulletChartComponent with categoryField

データからの動的な色設定

データソースから色を直接バインドします。

const data = [
  { value: 270, target: 250, valueColor: '#5B5FC7', targetColor: '#646464' }
];

<BulletChartComponent
  dataSource={data}
  valueFill="valueColor"
  targetColor="targetColor"
/>

カスタムツールチップテンプレート

カスタム HTML で書式設定した値を表示します。

<BulletChartComponent
  tooltip={{
    enable: true,
    template: '<div><b>Actual:</b> ${value}<br/><b>Target:</b> ${target}</div>'
  }}
/>

レスポンシブレイアウト

レスポンシブなダッシュボードには、パーセンテージベースのサイズ指定を使用します。

<BulletChartComponent
  width="100%"
  height="80px"
/>

主なプロパティ

プロパティ	型	用途
dataSource	Array	チャートのデータコレクション
valueField	string	実績値／特徴量のフィールド名
targetField	string	目標値／比較値のフィールド名
minimum	number	量的尺度の最小値
maximum	number	量的尺度の最大値
interval	number	軸ラベルの間隔
title	string	チャートのタイトルテキスト
subtitle	string	チャートのサブタイトルテキスト
type	string	値バーの形状：「Rect」または「Dot」
targetTypes	string[]	目標バーの形状：「Circle」、「Cross」、「Rect」
orientation	string	チャートの向き：「Horizontal」または「Vertical」
width	string	チャートの幅（ピクセルまたはパーセンテージ）
height	string	チャートの高さ（ピクセルまたはパーセンテージ）
enableRtl	boolean	右から左への描画を有効にする
theme	string	Syncfusion テーマを適用する
tooltip	object	有効化、テンプレート、塗りつぶし、枠線、テキストスタイルを指定するツールチップ設定
dataLabel	object	有効化、ラベルスタイルを指定するデータラベル設定

よくあるユースケース

KPI ダッシュボード

複数のパフォーマンス指標を表示するには、ブレットチャートを使用します。

• 指標ごとに異なる目標値を設定します
• パフォーマンスレベルに合わせて赤／黄／緑の範囲を使用します
• 指標名のカテゴリラベルを追加します
• 詳細情報を表示するツールチップを有効にします

販売実績トラッカー

実際の売上と目標を比較します。

• 売上データを valueField に割り当てます
• targetField に四半期／月次の目標値を設定します
• 目標未達／達成／超過の範囲を設定します
• データラベルを使用して正確な値を表示します

進捗インジケーター

視覚的な文脈とともに、目標に対する進捗を表示します。

• パーセンテージベースの範囲（0～50%、50～75%、75～100%）を使用します
• ブランドガイドラインに合わせて色をカスタマイズします
• 魅力的な遷移を実現するアニメーションを追加します
• コンパクトなレイアウトにするため、タイトルを左側に配置します

比較分析

複数の項目を並べて比較します。

• スペースを効率的に使うには、垂直方向を使用します
• すべてのチャートで尺度を統一します
• 項目を明確に識別できるよう、カテゴリラベルを適用します
• 区別しやすいよう、目標の種類（Circle、Cross）をカスタマイズします

モバイルダッシュボード

画面に適応し、タッチ操作に使いやすい可視化を作成します。

• パーセンテージベースの寸法を使用します
• バーのタッチ対象領域を大きくします
• モバイルに最適化されたツールチップを有効にします
• スクリーンリーダー向けのアクセシビリティツールでテストします

エッジケースとトラブルシューティング

データが表示されない場合：

• valueField と targetField がデータソースのプロパティ名と一致していることを確認します
• dataSource が有効なオブジェクトを含む配列であることを確認します
• minimum と maximum がデータ範囲を包含していることを確認します

範囲が表示されない場合：

• @syncfusion/ej2-react-charts から BulletRangeCollectionDirective と BulletRangeDirective をインポートします
• 終了値を昇順に設定します
• 終了値が minimum と maximum の範囲内にあることを確認します

ツールチップが機能しない場合：

• BulletTooltip モジュールを注入します：<Inject services={[BulletTooltip]} />
• tooltip.enable を true に設定します
• tooltip オブジェクトが正しく設定されていることを確認します

タイトル／サブタイトルが重なっている場合：

• titlePosition を Left、Right、Top、Bottom に調整します
• チャートの寸法（width／height）を大きくします
• titleStyle と subtitleStyle のフォントサイズをカスタマイズします

軸ラベルが切れている場合：

• チャートの幅または高さを大きくします
• ラベルの形式を短い表記に調整します（例：完全な数値ではなく「n1」を使用）
• 読みやすさを向上させるため、enableGroupSeparator を使用します

実装チェックリスト

• @syncfusion/ej2-react-charts パッケージをインストールする
• BulletChartComponent とディレクティブをインポートする
• value フィールドと target フィールドを含むデータを準備する
• dataSource、valueField、targetField を設定する
• 尺度の minimum、maximum、interval を設定する
• BulletRangeCollectionDirective を使用して範囲を追加する
• 必要に応じてタイトルとサブタイトルを設定する
• ツールチップを有効化してカスタマイズする（BulletTooltip を注入）
• さまざまなデータ範囲でテストする
• キーボード操作でアクセシビリティを確認する
• さまざまな画面サイズでレスポンシブ動作をテストする