syncfusion-react-maps

Syncfusion React Maps の実装

Syncfusion React Maps コンポーネントを実装して、豊富なインタラクティブ機能、複数のレイヤー、マーカー、バブル、凡例、マッププロバイダーとの連携を備えた地理データを可視化するための包括的なスキルです。

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

次のような場合に、このスキルを使用します。

• インタラクティブなマップに地理データを表示する
• マーカー、バブル、またはデータラベルを使って位置情報を可視化する
• データ値に基づいて地域を色分けしたコロプレスマップを作成する
• Bing Maps、OpenStreetMap、Azure Maps などのマッププロバイダーと連携する
• GeoJSON データファイルからカスタムシェイプを描画する
• オーバーレイやサブレイヤーを備えた複数レイヤーのマップを構築する
• 位置間のルートやつながりを示すナビゲーションラインを追加する
• マップを探索するためのズームとパンを実装する
• 地理的な地域に統計データを表示する
• データを解釈するためのインタラクティブな凡例を作成する
• 複数の投影法（メルカトル、ミラー、エッケルトなど）をサポートする
• ツールチップ、選択、ハイライトなどのユーザー操作に対応する

コンポーネントの概要

Syncfusion React Maps コンポーネントは、スケーラブルベクターグラフィックス（SVG）を使用して地理データを描画する、強力なデータ可視化ツールです。次の機能をサポートしています。

• 複雑な可視化に対応する任意の数のレイヤーとサブレイヤー
• カスタムシェイプの描画に対応するGeoJSON データバインディング
• ベースレイヤーとしてのマッププロバイダー（Bing、OpenStreetMap、Azure）
• さまざまなマップ表現に対応する6 種類の投影法
• 視覚要素：マーカー、バブル、ナビゲーションライン、注釈、データラベル、凡例
• インタラクティブ機能：ズーム、パン、ツールチップ、選択、ハイライト
• アクセシビリティ：キーボードナビゲーションに対応した WCAG 2.1 準拠
• グローバリゼーション：RTL 対応、国際化、ローカライズ

主な機能

データ可視化要素

• マーカー：カスタムシェイプ、テンプレート、クラスタリングを使って位置を示します
• バブル：サイズに基づくバブルでデータの大きさを表示します
• データラベル：マップシェイプ上に情報を直接表示します
• カラー マッピング：データ値に基づいて色を適用します（均等、範囲、彩度低下）
• ナビゲーションライン：曲線や矢印を使って位置間のつながりを描画します
• 凡例：データを解釈するための視覚的なキーを表示します

レイヤー構成

• メインレイヤー：GeoJSON またはマッププロバイダーから取得するベースマップ
• サブレイヤー：メインレイヤーの上に追加のシェイプを重ねます
• 複数レイヤーのサポート：複数のレイヤーを重ねて、豊かな可視化を実現します

マッププロバイダー

• Bing Maps：衛星画像、航空写真、道路地図
• OpenStreetMap：無料のタイルレイヤープロバイダー
• Azure Maps：Microsoft のマップサービス
• ハイブリッド方式：GeoJSON シェイプとプロバイダーのタイルを組み合わせます

ユーザー操作

• ズーム：マウスホイール、ダブルクリック、ピンチ、ツールバー操作
• パン：ドラッグしてさまざまな地域を探索します
• ツールチップ：ホバー時にデータを表示します
• 選択：クリック時にシェイプをハイライトします
• リセット：初期表示に戻します

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

API リファレンス

📄 参照： references/api-reference.md

• MapsComponent のプロパティに関する完全なリファレンス
• 利用可能なすべてのメソッドと例
• イベントの包括的なドキュメント
• レイヤー、マーカー、バブル、データラベルの設定
• 凡例、ズーム、ツールチップの設定
• クイックリファレンス用のコード例
• 型定義とパラメーター

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの依存関係
• Maps コンポーネントの基本的な実装
• GeoJSON のデータ構造とバインディング
• CSS テーマのインポート
• モジュールのインジェクションパターン（機能ベース）
• 最初の世界地図の例
• shapeDataPath と shapePropertyPath を使ったデータソースのバインディング

レイヤーと構造

📄 参照： references/layers-and-sublayers.md

• レイヤーアーキテクチャを理解する
• メインレイヤーとサブレイヤーの違い
• 複数レイヤーのマップを作成する
• レイヤーの種類と重ね順
• レイヤー固有の設定と構成
• 複数のレイヤーを使用する場面

マーカー

📄 参照： references/markers.md

• 場所を特定するマーカーを追加する
• マーカーデータソースの構造（緯度、経度）
• マーカーの形状とカスタムテンプレート
• データが密集している場合のマーカークラスタリング
• マーカーの動的な更新
• クリックイベントに対応するインタラクティブなマーカー
• マーカーのツールチップとラベル

データ可視化要素

📄 参照： references/data-visualization.md

• データの大きさを示すバブル可視化
• バブルのサイズと色の設定
• データラベルの設定と書式設定
• スマートラベルモード（trim、hide、none）
• カスタムコンテンツ用のラベルテンプレート
• バブルとデータラベルの組み合わせ
• 視覚的な階層構造に関するベストプラクティス

凡例

📄 参照： references/legend.md

• 凡例の有効化と設定
• 配置方法（absolute、dock）
• 凡例の配置オプション（near、center、far）
• インタラクティブな凡例
• 凡例モード（default、interactive）
• 凡例の外観のカスタマイズ
• 凡例と色のマッピングの同期

色のマッピング

📄 参照： references/color-mapping.md

• 色のマッピングの種類（equal、range、desaturation）
• データ値に基づいた色の適用
• colorValuePath の設定
• コロプレスマップの作成
• 複数の色のマッピングルール
• カスタム配色
• データを視覚的に表現する方法

ナビゲーションライン

📄 参照： references/navigation-lines.md

• 場所間の線の作成
• 線のスタイル設定（幅、色、破線パターン）
• 曲線と角度
• 方向を示す矢印
• 用途（経路、接続、流れ）
• 線のアニメーション効果

マッププロバイダー

📄 参照： references/map-providers.md

• サポート対象のプロバイダーの概要
• GeoJSON とマッププロバイダーの使い分け
• Bing Maps の設定と API キー
• OpenStreetMap との連携（無料）
• Azure Maps の設定
• タイルレイヤーの種類（衛星写真、航空写真、道路）
• ハイブリッド方式（プロバイダーのタイルに GeoJSON オーバーレイを重ねる）

ユーザー操作

📄 参照： references/user-interactions.md

• ズームの有効化と設定
• ズーム倍率とツールバーの操作
• パン機能
• ツールチップの設定とテンプレート
• 図形の選択とハイライト表示
• マウスホイールとダブルクリックによるズーム
• タッチデバイスでのピンチズーム
• 初期表示へのリセット

注釈とポリゴン

📄 参照： references/annotations-polygon.md

• マップへのカスタム注釈の追加
• カスタム図形のポリゴン描画
• 位置と配置
• インタラクティブな注釈
• オーバーレイの用途

カスタマイズ

• マップ投影法（Mercator、Miller、Eckert、Winkel Tripel、Aitoff、Equirectangular）
• タイトルとサブタイトルの設定
• 枠線と背景のスタイル設定
• マージンとパディングの調整
• カスタム CSS クラス
• テーマとの統合
• レスポンシブデザインのパターン

高度な機能

📄 参照： references/advanced-features.md

• 国際化（i18n）
• ローカライズ（l10n）
• アクセシビリティ（WCAG 準拠、キーボード操作）
• セッションをまたいだ状態の保持
• 印刷とエクスポート機能
• イベント処理のパターン
• ref を介したコンポーネントメソッドへのアクセス
• パフォーマンス最適化の手法
• EJ1 から EJ2 への移行ガイド

クイックスタートの例

import * as React from 'react';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';
import { world_map } from './world-map'; // GeoJSON data

function MapExample() {
  const data = [
    { Country: 'United States', Population: 331000000, Membership: 'Permanent' },
    { Country: 'Russia', Population: 145900000, Membership: 'Permanent' },
    { Country: 'China', Population: 1439000000, Membership: 'Permanent' },
    { Country: 'India', Population: 1380000000, Membership: 'Non-Permanent' },
    { Country: 'Brazil', Population: 212500000, Membership: 'Non-Permanent' }
  ];

  return (
    <MapsComponent
      titleSettings={{ text: 'World Map with Country Membership' }}
      legendSettings={{ visible: true }}
    >
      <Inject services={[Legend]} />
      <LayersDirective>
        <LayerDirective
          shapeData={world_map}
          shapeDataPath='Country'
          shapePropertyPath='name'
          dataSource={data}
          shapeSettings={{
            colorValuePath: 'Membership',
            colorMapping: [
              { value: 'Permanent', color: '#D84444' },
              { value: 'Non-Permanent', color: '#316DB5' }
            ]
          }}
        />
      </LayersDirective>
    </MapsComponent>
  );
}

export default MapExample;

モジュールの読み込みガイド

マップの機能はモジュール化されています。必要なモジュールのみを読み込みます。

import { 
  MapsComponent, 
  Inject,
  Legend,        // For legends
  DataLabel,     // For data labels
  Marker,        // For markers
  Bubble,        // For bubbles
  MapsTooltip,   // For tooltips
  Zoom,          // For zooming and panning
  Highlight,     // For highlighting shapes
  Selection,     // For selecting shapes
  NavigationLine,// For navigation lines
  Annotations,   // For annotations
  Polygon        // For polygons
} from '@syncfusion/ej2-react-maps';

<MapsComponent>
  <Inject services={[Legend, Marker, MapsTooltip, Zoom]} />
  {/* Your layers */}
</MapsComponent>

バンドルサイズを最小限に抑えるため、使用する機能のモジュールのみを読み込んでください。

一般的なユースケース

コロプレスマップ（色分けされた地域）

目的：国や地域を色分けして統計データを表示します。

方法：

1. dataSource、shapeDataPath、shapePropertyPath を使ってデータソースをバインドします。
2. shapeSettings.colorValuePath を設定してデータフィールドを指定します。
3. 値と色のペアを指定して colorMapping を設定します。
4. 解釈しやすいように Legend を追加します。

例：人口密度マップ、選挙結果、COVID-19 の統計

---

位置マーカーマップ

目的：カスタムマーカーで特定の場所を表示します。

方法：

1. LayerDirective の中に MarkersDirective を追加します。
2. 緯度と経度を指定してマーカーデータを設定します。
3. マーカーの形状、サイズ、テンプレートをカスタマイズします。
4. マーカー情報を示すツールチップを追加します。

例：店舗検索、支店、観光名所

---

複数レイヤーのオーバーレイ

目的：ベースマップ上で特定の地域を強調表示します。

方法：

1. 最初のレイヤー：ベースマップ（例：国全体）
2. type="SubLayer" を指定した追加レイヤー：強調表示する地域
3. サブレイヤーを区別しやすいスタイル（異なる色、境界線）に設定します。
4. レイヤーの表示状態と順序を制御します。

例：国の地図上で州を強調表示、販売地域

---

ルートの可視化

目的：場所同士のつながりやルートを表示します。

方法：

1. 始点と終点にマーカーを追加します。
2. NavigationLineDirective を使って線を描画します。
3. 線の曲線、矢印、スタイルを設定します。
4. 必要に応じて線をアニメーション表示します。

例：航空路、航路、移住パターン

---

マッププロバイダーとの連携

目的：実際の衛星地図や道路地図をベースとして使用します。

方法：

1. プロバイダーの urlTemplate を使ってレイヤーを設定します。
2. 必要に応じて API キー（Bing、Azure）を設定します。
3. 必要に応じて、GeoJSON の図形をサブレイヤーとして重ねます。
4. その上にマーカーとラベルを追加します。

例：不動産マップ、配送状況の追跡、ライドシェアアプリ

判断のためのフローチャート

GeoJSON とマッププロバイダーのどちらを使うべきですか？

GeoJSON を使う場合：

• カスタムの図形や境界が必要な場合
• データが地域や国を単位としている場合（コロプレスマップ）
• 実際の道路レベルの詳細が不要な場合
• オフライン機能が必要な場合
• スタイル設定とデータバインディングを完全に制御したい場合

マッププロバイダーを使う場合：

• 実際の衛星画像や航空写真が必要な場合
• 道路レベルの詳細が必要な場合
• マップをリアルタイムで更新したい場合
• ユーザーが Google Maps のような使い慣れたマップインターフェースを期待する場合

両方を使う（ハイブリッド）場合：

• 実際の地図をベースにカスタム図形を重ねる必要がある場合
• 統計上の地域と道路のコンテキストを組み合わせる場合

---

どの色分けタイプを使うべきですか？

等値色分け：

• データが離散的なカテゴリーの場合に使います（例：会員区分：正社員／非正社員）
• 一意の値ごとに特定の色が割り当てられます。

範囲色分け：

• データが連続した数値の場合に使います（例：人口：0～100 万、100 万～1,000 万、1,000 万以上）
• 範囲内の値に色が割り当てられます。

彩度色分け：

• 数値に基づくグラデーション効果に使います。
• 1 つの色で、彩度を変化させます。

---

レイヤーはいくつ使うべきですか？

単一レイヤー：

• 1 つのデータ項目を使ったシンプルな可視化
• 基本的な国や地域のマップ
• すべてのデータが 1 つのレイヤーに収まる場合

複数レイヤー：

• ベースマップ上で特定の地域を強調表示する場合
• 異なるデータソースを組み合わせる場合
• オーバーレイで視覚的な奥行きを作る場合
• 境界線、河川、都市を個別に表示する場合

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

MapsComponent

• titleSettings：タイトルとサブタイトルを設定します。
• legendSettings：凡例の表示、位置、配置を設定します。
• zoomSettings：ズームを有効にし、初期ズーム倍率を設定します。
• layers：レイヤー設定の配列

LayerDirective

• shapeData：シェイプの GeoJSON データ
• dataSource：シェイプにバインドするデータ
• shapeDataPath：シェイプに一致する dataSource 内のフィールド
• shapePropertyPath：dataSource に一致する GeoJSON 内のフィールド
• shapeSettings：塗りつぶし、境界線、色のマッピング
• type：「Layer」（メイン）または「SubLayer」（オーバーレイ）
• markerSettings：マーカーの設定
• bubbleSettings：バブルの視覚化
• dataLabelSettings：ラベルの設定
• tooltipSettings：ツールチップのカスタマイズ
• navigationLineSettings：線の視覚化

一般的なパターン

• モジュールのインジェクション：バンドルサイズを小さくするため、必要なサービスのみをインジェクションします
• データバインディング：自動的に照合するには、shapeDataPath と shapePropertyPath を使用します
• 段階的な機能拡張：基本的な地図から始め、機能を段階的に追加します
• レスポンシブデザイン：地図は自動でサイズ変更されますが、さまざまなビューポートでテストしてください

トラブルシューティングの簡易チェック

❌ 地図が表示されない：

• GeoJSON データが正しくインポートされていることを確認します
• コンソールにエラーがないか確認します
• CSS がインポートされていることを確認します

❌ 色が適用されない：

• shapeDataPath がデータフィールド名と一致していることを確認します
• shapePropertyPath が GeoJSON プロパティと一致していることを確認します
• colorValuePath が正しいデータフィールドを参照していることを確認します

❌ マーカーが表示されない：

• Marker サービスをインジェクションします
• MarkerDirective で visible={true} を設定します
• 緯度と経度の値が有効であることを確認します

❌ ズームが機能しない：

• Zoom サービスをインジェクションします
• zoomSettings.enable={true} を設定します
• enablePanning が必要かどうか確認します

❌ 凡例が表示されない：

• Legend サービスをインジェクションします
• legendSettings.visible={true} を設定します
• 色のマッピングが設定されていることを確認します

次のステップ

1. シンプルに始める：基本的な地図については、getting-started.md から始めます
2. データを追加する：マーカーやバブルについては、data-visualization.md に従います
3. スタイルを設定する：コロプレス効果には、color-mapping.md を使用します
4. インタラクティブにする：ズームやパンには、user-interactions.md を実装します
5. 機能を強化する：必要に応じて高度な機能を追加します

現在の実装段階と具体的な要件に合ったリファレンスドキュメントを選択してください。