syncfusion-react-3d-circular-chart

Syncfusion React 3D Circular Charts の実装

Syncfusion の React 3D Circular Chart コンポーネントを実装するための包括的なスキルです。このスキルでは、3D 表示、データラベル、凡例、ツールチップ、高度なカスタマイズオプションを備えた円グラフとドーナツグラフの作成方法を説明します。

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

• React アプリケーションで 3D 円グラフまたはドーナツグラフを作成する
• 円グラフで比例データを可視化する
• 3D の奥行きと視覚的な魅力を備えたデータを表示する
• グラフにインタラクティブなツールチップと凡例を追加する
• データラベルでグラフの外観をカスタマイズする
• 空または null のデータポイントを適切に処理する
• グラフをさまざまな形式（PNG、JPEG、SVG、PDF）にエクスポートする
• ブラウザーからグラフを直接印刷する
• レスポンシブな円グラフの可視化を実装する

コンポーネントの概要

3D Circular Chart コンポーネントには、次の機能があります。

• 円グラフとドーナツグラフ： 3D の奥行きを備えた標準的な円形の可視化
• 柔軟なデータバインディング： データソースをグラフの系列に簡単にマッピング
• インタラクティブ機能： ツールチップ、凡例、クリックイベント
• 視覚的なカスタマイズ： データラベル、色、半径の設定
• エクスポートオプション： 印刷と複数形式へのエクスポート
• 空のポイントの処理： null／undefined 値をスマートに処理
• レスポンシブデザイン： コンテナーのサイズに自動的に適応

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

はじめに

📄 参照: references/getting-started.md

• インストールとパッケージの依存関係
• Vite または Create React App を使用した React アプリケーションのセットアップ
• 3D Circular Chart コンポーネントのプロジェクトへの追加
• CSS テーマのインポート
• データソースを使った基本的な円グラフ系列の実装
• xName プロパティと yName プロパティを使ったデータフィールドのマッピング
• 最初の 3D Circular Chart の実行
• 最小構成の実用的な例

円グラフとドーナツグラフ

📄 参照: references/pie-donut-charts.md

• PieSeries3D モジュールの挿入
• デフォルトの円グラフの描画
• グラフの半径のカスタマイズ（デフォルトではコンテナーの 80%）
• スライスごとのカスタマイズによる、さまざまな半径の円グラフの作成
• innerRadius プロパティを使ったドーナツグラフの実装
• データソースからのテキストと塗りつぶし色のマッピング
• pointRender イベントによる個々のポイントのカスタマイズ
• 円グラフとドーナツグラフのバリエーションを網羅した例

データラベル

📄 参照: references/data-labels.md

• データラベルの表示を有効化
• CircularChartDataLabel3D モジュールの挿入
• ラベルの重なりを防ぐスマートな配置
• グラフの内側または外側へのラベルの配置
• プレースホルダーを使ったカスタムテンプレートの作成
• テキストの書式設定とラベルのスタイル設定
• 接続線の設定
• データラベルのフォントのカスタマイズ

凡例

📄 参照: references/legend.md

• 凡例の表示を有効化
• CircularChartLegend3D モジュールの挿入
• 凡例の位置（左、右、上、下）の設定
• 配置オプション（中央、遠、近）
• 凡例項目の順序の反転
• 項目数が多い場合の凡例のページネーション
• 形状とマーカーのカスタマイズ
• スタイルとクリック動作の設定

ツールチップ

📄 参照: references/tooltip.md

• ホバー時のツールチップの有効化
• CircularChartTooltip3D モジュールの挿入
• カスタムツールチップヘッダーの設定
• プレースホルダーを使った書式文字列のカスタマイズ
• ツールチップテンプレートの作成
• 系列名とポイント値の表示
• ツールチップの外観のスタイル設定
• イベントに基づくツールチップのカスタマイズ

空のポイント

📄 参照: references/empty-points.md

• 空のポイント（null／undefined 値）について
• emptyPointSettings プロパティの設定
• モードのオプション：Gap、Average、Drop、Zero
• Gap モード：空のデータポイントをスキップ
• Average モード：計算された平均値を使用
• Drop モード：グラフから除外
• Zero モード：ゼロ値として扱う
• 空のポイントの塗りつぶし色のカスタマイズ

タイトルとサブタイトル

📄 参照： references/title-and-subtitle.md

• title プロパティを使ったチャートタイトルの追加
• タイトルの位置と配置
• タイトルのスタイルのカスタマイズ（フォント、色、サイズ）
• subTitle プロパティを使ったサブタイトルの追加
• サブタイトルの位置
• サブタイトルの個別のスタイル設定
• タイトルとサブタイトルの組み合わせ
• レスポンシブなタイトルサイズ

印刷とエクスポート

📄 参照： references/print-and-export.md

• ブラウザーからのチャートの直接印刷
• チャート ID を指定した print メソッドの使用
• 画像形式（JPEG、PNG、SVG）へのエクスポート
• pdfExport メソッドを使った PDF へのエクスポート
• エクスポートの種類とファイル名の指定
• ボタンからの印刷とエクスポート
• エクスポートの品質と解像度の設定
• エクスポートに関する問題のトラブルシューティング

API リファレンス

📄 参照： references/api-reference.md

• CircularChart3DComponent に関する公式 Syncfusion API ドキュメントに基づく、コンポーネントのプロパティ、メソッド、イベントの概要です。

クイックスタートの例

import { CircularChart3DComponent, CircularChart3DSeriesCollectionDirective, CircularChart3DSeriesDirective, PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, Inject } from '@syncfusion/ej2-react-charts';
import * as React from "react";
import * as ReactDOM from "react-dom";
function App() {
    const circularData = [
        { x: 'Chrome', y: 62.92 },
        { x: 'Internet Explorer', y: 6.12 },
        { x: 'Opera', y: 3.15 },
        { x: 'Edge', y: 5.5 },
        { x: 'Safari', y: 19.97 },
        { x: 'Others', y: 2.34 }
    ];
    return <CircularChart3DComponent id='charts' title='Browser Market Shares in November 2023' tilt={-45} legendSettings={{ visible: true, position: 'Right' }}>
        <Inject services={[PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D]} />
        <CircularChart3DSeriesCollectionDirective>
            <CircularChart3DSeriesDirective dataSource={circularData} xName='x' yName='y' dataLabel={{ visible: true, position: 'Outside', name: 'x', font: { fontWeight: '600' }, connectorStyle: { length: '40px' } }}>
            </CircularChart3DSeriesDirective>
        </CircularChart3DSeriesCollectionDirective>
    </CircularChart3DComponent>;
}
export default App;
const root = ReactDOM.createRoot(document.getElementById('charts'));
root.render(<App />);

一般的なパターン

ドーナツチャートの作成

<CircularChart3DSeriesDirective
  dataSource={data}
  xName="category"
  yName="value"
  innerRadius="40%"  // Creates donut effect
  radius="80%"
/>

データラベルの追加

import { CircularChartDataLabel3D } from '@syncfusion/ej2-react-charts';

<CircularChart3DComponent>
  <Inject services={[PieSeries3D, CircularChartDataLabel3D]} />
  <CircularChart3DSeries>
    <CircularChart3DSeriesDirective
      dataSource={data}
      xName="x"
      yName="y"
      dataLabel={{ visible: true, position: 'Outside' }}
    />
  </CircularChart3DSeries>
</CircularChart3DComponent>

凡例とツールチップの有効化

import { CircularChartLegend3D, CircularChartTooltip3D } from '@syncfusion/ej2-react-charts';

<CircularChart3DComponent
  legendSettings={{ visible: true, position: 'Bottom' }}
  tooltip={{ enable: true, format: '${point.x}: ${point.y}' }}
>
  <Inject services={[PieSeries3D, CircularChartLegend3D, CircularChartTooltip3D]} />
  {/* Series configuration */}
</CircularChart3DComponent>

空のポイントの処理

<CircularChart3DSeriesDirective
  dataSource={dataWithNulls}
  xName="category"
  yName="value"
  emptyPointSettings={{ 
    mode: 'Average',  // Options: Gap, Average, Drop, Zero
    fill: '#cccccc'
  }}
/>

主なプロパティのリファレンス

CircularChart3DComponent のプロパティ

• title：チャートのタイトルテキスト
• subTitle：チャートのサブタイトルテキスト
• legendSettings：凡例の外観と動作を設定します
• tooltip：ツールチップを有効化してカスタマイズします
• enableExport：エクスポート機能を有効化します
• width/height：チャートの寸法

CircularChart3DSeriesDirective のプロパティ

• dataSource：データオブジェクトの配列
• xName：カテゴリ／ラベルのプロパティ名
• yName：値のプロパティ名
• radius：チャートの半径（パーセンテージ文字列、例："70%"）
• innerRadius：ドーナツチャートの内半径（パーセンテージ）
• dataLabel：データラベルの設定
• emptyPointSettings：null／undefined 値の処理
• pointColorMapping：データソースから色を割り当てます

モジュールのインジェクション

必須モジュールは <Inject services={[...]} /> を使ってインジェクションする必要があります：

• PieSeries3D：円／ドーナツチャートのコア機能
• CircularChartDataLabel3D：データラベル機能
• CircularChartLegend3D：凡例機能
• CircularChartTooltip3D：ツールチップ機能
• CircularChart3DExport：画像形式へのエクスポート
• CircularChart3DPdfExport：PDF エクスポート機能

一般的なユースケース

売上分布ダッシュボード

市場シェア、カテゴリ別売上、製品／地域別の収益分布を表示するのに最適です。

予算配分

部門別予算の内訳、費用カテゴリ、コストセンターを、明確な割合で可視化します。

アンケート結果

投票結果、顧客フィードバックの分布、人口統計の内訳を、直感的な円形のビジュアライゼーションで表示します。

ポートフォリオ構成

投資配分、資産分布、リソース配分をインタラクティブなチャートで表示します。

時間配分

活動に費やした時間、プロジェクトの各フェーズ、リソースの利用状況をドーナツチャートで表します。

トラブルシューティングのヒント

チャートが表示されませんか？

• @syncfusion/ej2-react-charts パッケージがインストールされていることを確認してください
• 必要な CSS テーマファイルをインポートしてください
• データソースが正しくフォーマットされた配列であることを確認してください
• 必要なモジュール（PieSeries3D）が注入されていることを確認してください

データラベルが重なっていますか？

• コンポーネントはラベルが重ならないように自動で配置します
• 間隔を広げるには position: 'Outside' を使用してください
• フォントサイズを小さくするか、テンプレートの使用を検討してください

エクスポートが機能しませんか？

• CircularChart3DExport または CircularChart3DPdfExport モジュールを注入してください
• チャートコンポーネントで enableExport: true を設定してください
• 正しいメソッド（export または pdfExport）を呼び出していることを確認してください

色が正しく表示されませんか？

• pointColorMapping を使用して、データソースから色を割り当ててください
• データオブジェクトで色を指定するか、チャートのパレットを使用してください
• CSS テーマが正しくインポートされていることを確認してください

---

構築を始める準備はできましたか？ インストールと基本設定については references/getting-started.md から始め、その後必要に応じて特定の機能を確認してください。