syncfusion-angular-maps

Syncfusion Angular Maps の実装

インタラクティブ機能、複数のレイヤー、豊富なカスタマイズオプションを使用して地理データを可視化する、Syncfusion Angular Maps コンポーネントの実装に関する包括的なガイドです。

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

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

• 地理データを可視化する - 統計データを世界地図、国別地図、地域地図、またはカスタムの地理的形状に表示します
• インタラクティブなマップを作成する - ズーム、パン、選択、強調表示、ツールチップによる操作に対応したマップを構築します
• 位置をプロットする - マーカー、バブル、注釈を追加して、特定の地理的な地点を強調表示します
• マップレイヤーを表示する - GeoJSON データまたはマッププロバイダー（Bing、OpenStreetMap、Azure）を使って、複数のレイヤーを重ねて表示します
• 地域を色分けする - データ値に基づいて色を割り当て、コロプレスマップ／ヒートマップを可視化します
• カスタムマップの可視化を作成する - 座席配置図、フロアプラン、スタジアムマップなど、地理的でない可視化を作成します
• ナビゲーションとルートを表示する - マーカー間にナビゲーションラインやルートを描画します
• マップをエクスポートして印刷する - 印刷またはエクスポート可能なマップの可視化を生成します
• ダッシュボードを構築する - ビジネスインテリジェンスや分析用に、Angular アプリケーションへマップを統合します

コンポーネントの概要

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

• 複雑な可視化に対応する複数のレイヤーとサブレイヤー
• カスタムの形状や地域に対応するGeoJSON データバインディング
• ベースレイヤーとしてのマッププロバイダー（Bing Maps、OpenStreetMap、Azure Maps）
• 8 種類の投影法（Mercator、Equirectangular、Miller、Eckert3、Eckert5、Eckert6、Winkel3、AitOff）
• 豊富な可視化要素 - マーカー、バブル、データラベル、凡例、ナビゲーションライン、注釈
• インタラクティブ機能 - ズーム、パン、ツールチップ、選択、強調表示
• WCAG に準拠したレスポンシブでアクセシブルなデザイン

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

はじめに

📄 参照: references/getting-started.md

初めて Maps を実装する場合、または新しい Angular プロジェクトをセットアップする場合：

• 依存関係のインストール（@syncfusion/ej2-angular-maps パッケージ）
• Angular 環境のセットアップと MapsModule のインポート
• 世界地図データを使った最初の基本的なマップの作成
• 機能に必要なモジュールインジェクション（MarkerService、BubbleService など）の理解
• CSS テーマとスタイルの追加
• アプリケーションの実行

レイヤーとデータバインディング

📄 参照: references/layers-and-data.md

マップレイヤー、形状データ、データソースのバインディングを扱う場合：

• レイヤーの構造と設定について
• GeoJSON 形状データの読み込み（shapeData プロパティ）
• 外部データソースのバインド（dataSource、shapeDataPath、shapePropertyPath）
• 複数のレイヤーとサブレイヤーの作成
• レイヤーの種類（ベースレイヤーとサブレイヤー）
• レイヤーの切り替え（baseLayerIndex）
• 地理的でない可視化用のカスタム形状の描画
• GeometryType のオプション（Geographic と Normal）

マーカー

📄 参照: references/markers.md

位置マーカーを追加してカスタマイズする場合：

• 緯度／経度データを使ったマーカーの追加
• マーカーの形状（Balloon、Circle、Cross、Diamond、Image、Rectangle、Star、Triangle）
• カスタムマーカーテンプレート
• マーカーのスタイル（サイズ、色、枠線、不透明度）
• データバインディングを使った動的マーカー
• マーカーのクラスタリング
• マーカーのアニメーションとトランジション
• マーカーのツールチップとイベント
• マーカー間のルートの作成

データ可視化機能

📄 参照： references/data-visualization.md

バブル、色、ラベル、凡例を使ってデータを可視化する方法：

• バブル - 定量データをサイズで可視化します
• カラー マッピング - 範囲カラー マッピング、均等カラー マッピング、彩度を下げるカラー マッピング
• データラベル - 地図上に図形名やデータ値を表示します
• 凡例 - カラー マッピングやバブルの凡例を追加します
• ナビゲーション線 - 地点間に線を描画します
• 注釈 - 特定の位置にカスタム HTML コンテンツを追加します
• 複数の可視化機能の組み合わせ

ユーザー操作

📄 参照： references/user-interactions.md

インタラクティブな地図動作を実装する方法：

• ズーム - マウスホイールによるズーム、ピンチズーム、ダブルクリックによるズーム、ズームツールバー
• パン - マウスドラッグやタッチによるパン
• ツールチップ - レイヤーのツールチップ、マーカーのツールチップ、バブルのツールチップ
• 選択 - 図形の選択、マーカーの選択、バブルの選択
• ハイライト - ホバー時のハイライト効果
• インタラクティブな凡例 - 凡例項目をクリックして図形の表示／非表示を切り替えます
• イベント処理（クリック、ホバー、ズーム、パンのイベント）
• タッチおよびモバイルのサポート

地図プロバイダー

📄 参照： references/map-providers.md

外部地図サービスを統合する方法：

• 地図プロバイダーのサポート概要
• Bing Maps の統合と API キーの設定
• OpenStreetMap（OSM）の統合
• Azure Maps の統合
• プロバイダー固有の機能と制限事項
• 地図プロバイダーと図形レイヤーの組み合わせ
• URL テンプレートとタイルサービス
• ズームレベルの設定

ポリゴン図形

📄 参照： references/polygon-shapes.md

ポリゴンを描画してカスタマイズする方法：

• 地図へのポリゴンオーバーレイの追加
• ポリゴンの設定とデータ構造
• ポリゴンのスタイル設定（塗りつぶし、境界線、不透明度）
• ポリゴンのイベント（クリック、ホバー）
• ユースケース（地域、境界、ゾーンのハイライト）
• 動的なポリゴンのレンダリング

カスタマイズとスタイル設定

📄 参照： references/customization.md

テーマ設定と外観のカスタマイズ方法：

• CSS によるカスタマイズとテーマの上書き
• 図形のスタイル設定（塗りつぶし、境界線、配色）
• レスポンシブデザインのパターン
• 地図投影法 - 投影法の種類の選択と設定
• 背景のカスタマイズ（色、画像）
• タイトルとサブタイトルのスタイル設定
• 境界線と余白の設定

ローカライズと国際化

📄 参照： references/localization.md

地図コンテンツをグローバル化する方法：

• 国際化（i18n）の設定
• 言語別のローカライズ（l10n）
• 右から左（RTL）への表示のサポート
• ロケール別の数値形式
• ツールチップ／ラベルの通貨形式
• 日付と時刻の形式
• 文化圏に応じたレンダリング

高度な機能

📄 参照： references/advanced-features.md

高度な機能と API：

• 印刷とエクスポート - 地図の印刷、PNG/JPEG/SVG/PDF へのエクスポート
• 状態の永続化 - 地図の状態の保存と復元
• パブリックメソッド - プログラムによる制御（更新、印刷、エクスポートなど）
• イベントリファレンス - 利用可能なイベントの完全な一覧
• ルートの作成 - マーカー間のナビゲーションルートの描画
• カスタムパスのレンダリング - パスと線の高度なカスタマイズ
• ドリルダウンナビゲーション - 階層型の地図ナビゲーションの作成

アクセシビリティ

📄 参照： references/accessibility.md

アクセシブルな地図を実装する方法：

• WCAG 2.1 準拠のガイドライン
• キーボード操作のサポート
• ARIA 属性とロール
• スクリーンリーダーとの互換性
• ハイコントラストテーマのサポート
• フォーカスインジケーターと管理
• 図形とマーカーの代替テキスト

クイックスタート

インストール

# Install the Maps package
npm install @syncfusion/ej2-angular-maps --save

基本的な実装

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map'; // GeoJSON data

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer [shapeData]='shapeData'></e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
}

データバインディングとカラー マッピングを使用する

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [dataSource]='dataSource'
          shapeDataPath='Country'
          shapePropertyPath='name'
          [shapeSettings]='shapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public dataSource: object[] = [
    { Country: 'United States', Population: 331002651, Code: 'US' },
    { Country: 'India', Population: 1380004385, Code: 'IN' },
    { Country: 'China', Population: 1439323776, Code: 'CN' }
  ];
  
  public shapeSettings: object = {
    colorValuePath: 'Population',
    colorMapping: [
      { from: 0, to: 100000000, color: '#C5E8B7' },
      { from: 100000001, to: 500000000, color: '#5BC85A' },
      { from: 500000001, to: 2000000000, color: '#238B45' }
    ]
  };
}

一般的なパターン

パターン 1：マーカーとツールチップを含むマップ

import { Component } from '@angular/core';
import { MapsModule, MarkerService, MapsTooltipService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  providers: [MarkerService, MapsTooltipService],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [markerSettings]='markerSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public markerSettings: object[] = [{
    visible: true,
    dataSource: [
      { latitude: 40.7128, longitude: -74.0060, name: 'New York' },
      { latitude: 51.5074, longitude: -0.1278, name: 'London' },
      { latitude: 35.6762, longitude: 139.6503, name: 'Tokyo' }
    ],
    shape: 'Circle',
    fill: '#FF6347',
    height: 15,
    width: 15,
    tooltipSettings: {
      visible: true,
      valuePath: 'name'
    }
  }];
}

パターン 2：ズームと凡例を備えたインタラクティブマップ

import { Component } from '@angular/core';
import { MapsModule, ZoomService, LegendService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  providers: [ZoomService, LegendService],
  template: `
    <ejs-maps 
      id='maps-container'
      [zoomSettings]='zoomSettings'
      [legendSettings]='legendSettings'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [dataSource]='dataSource'
          shapeDataPath='Country'
          shapePropertyPath='name'
          [shapeSettings]='shapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public dataSource: object[] = [
    { Country: 'United States', Category: 'High' },
    { Country: 'Canada', Category: 'Medium' },
    { Country: 'Mexico', Category: 'Low' }
  ];
  
  public shapeSettings: object = {
    colorValuePath: 'Category',
    colorMapping: [
      { value: 'High', color: '#E74C3C' },
      { value: 'Medium', color: '#F39C12' },
      { value: 'Low', color: '#27AE60' }
    ]
  };
  
  public zoomSettings: object = {
    enable: true,
    toolbars: ['Zoom', 'ZoomIn', 'ZoomOut', 'Pan', 'Reset']
  };
  
  public legendSettings: object = {
    visible: true,
    position: 'Bottom'
  };
}

パターン 3：サブレイヤーを含む複数レイヤーのマップ

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';
import { usa_map } from './usa-map';
import { california } from './california';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        
        <e-layer 
          [shapeData]='usaMap'
          [shapeSettings]='baseShapeSettings'>
        </e-layer>
        
        
        <e-layer 
          type='SubLayer'
          [shapeData]='californiaMap'
          [shapeSettings]='sublayerShapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public usaMap: object = usa_map;
  public californiaMap: object = california;
  
  public baseShapeSettings: object = {
    fill: '#E5E5E5',
    border: { color: '#000000', width: 0.5 }
  };
  
  public sublayerShapeSettings: object = {
    fill: '#FFD700',
    border: { color: '#FF6347', width: 2 }
  };
}

主な設定オプション

レイヤー設定

• shapeData - 図形の GeoJSON データ
• dataSource - バインドする外部データ
• shapeDataPath - 図形を識別する dataSource 内のフィールド
• shapePropertyPath - dataSource と一致する shapeData 内のフィールド
• shapeSettings - 図形のビジュアルスタイル
• type - レイヤーの種類（'Layer' または 'SubLayer'）

図形設定

• fill - 図形の塗りつぶし色
• border - 境界線の設定（色、幅、不透明度）
• colorValuePath - 色のマッピングに使用するデータフィールド
• colorMapping - 色の範囲または値の配列
• autofill - 図形の色を自動生成

マーカー設定

• visible - マーカーの表示／非表示
• dataSource - 緯度／経度を含むマーカーデータ
• shape - マーカーの形状の種類
• height / width - マーカーの寸法
• template - カスタム HTML テンプレート
• tooltipSettings - マーカーのツールチップ設定

ズーム設定

• enable - ズームの有効／無効
• zoomFactor - 初期ズームレベル
• maxZoom / minZoom - ズームの上限／下限
• toolbars - ズームコントロールボタン
• mouseWheelZoom - マウスホイールによるズームを有効化
• pinchZooming - タッチ操作によるピンチズームを有効化

凡例の設定

• visible - 凡例の表示／非表示
• position - 凡例の配置（Top、Bottom、Left、Right）
• mode - 凡例のモード（'Default'、'Interactive'）
• type - 凡例の種類（'Layers'、'Bubbles'、'Markers'）

よくあるユースケース

ユースケース 1：地域別の売上ダッシュボード

国や州ごとの売上データを色分けした地域、インタラクティブなツールチップ、凡例とともに表示するコロプレスマップを作成します。ビジネスインテリジェンスのダッシュボードに便利です。

ユースケース 2：店舗検索マップ

カスタムマーカーアイコンや、店舗が密集する地域向けのクラスタリングを使用して店舗の所在地を表示し、店舗の詳細を示すツールチップを追加します。地図プロバイダーと連携して、街路レベルの詳細を表示できます。

ユースケース 3：選挙結果の可視化

色のマッピングを使用して選挙結果を選挙区や州ごとに表示し、詳細な地域データを調べるためのドリルダウン機能を提供します。

ユースケース 4：リアルタイム追跡ダッシュボード

車両、貨物、または資産の所在地をアニメーション付きマーカーでプロットし、ルートを示すナビゲーション線とリアルタイムのデータ更新を表示します。

ユースケース 5：気象または環境データ

色のグラデーションと地理的地域上のデータラベルを使用して、気温、降水量、空気質、その他の環境指標を可視化します。

ユースケース 6：COVID-19 または感染症の拡大追跡

バブルの大きさと色の濃さを使用して、地域ごとの症例数、ワクチン接種率、または感染率を表示します。

ユースケース 7：航空路線の可視化

ナビゲーション線を使用して都市間の飛行経路を表示し、空港のマーカーとインタラクティブな選択機能を追加します。

ユースケース 8：カスタム座席レイアウト

カスタム GeoJSON 図形を使用して、劇場、スタジアム、または交通機関の座席選択のような、地理情報以外の可視化を実現します。

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

Maps コンポーネントでは、機能ごとのサービスをインジェクションする必要があります。

import { 
  MapsModule,
  MarkerService,          // For markers
  BubbleService,          // For bubbles
  DataLabelService,       // For data labels
  LegendService,          // For legends
  MapsTooltipService,     // For tooltips
  ZoomService,            // For zoom and pan
  SelectionService,       // For selection
  HighlightService,       // For highlighting
  NavigationLineService,  // For navigation lines
  AnnotationsService,     // For annotations
  PolygonService          // For polygons
} from '@syncfusion/ej2-angular-maps';

@Component({
  providers: [
    MarkerService,
    LegendService,
    MapsTooltipService,
    ZoomService
    // Add only the services you need
  ]
})

API リファレンスドキュメント

API カタログ全体

📘 API リファレンスガイドの全文 - Maps API 全体の包括的なドキュメント

カテゴリー別クイック API リンク

コアコンポーネント

• MapsComponent - 20 以上のプロパティとメソッドを備えたメインのマップコンポーネント
• print() - 印刷機能
• export() - 画像／PDF へのエクスポート
• refresh() - マップの再読み込み
• addLayer() - レイヤーを動的に追加

レイヤー設定

• LayerSettings - レイヤー設定モデル
• ShapeSettings - 形状のスタイル設定
• shapeData - GeoJSON 形状データ
• dataSource - 外部データバインディング

マーカーとバブル

• MarkerSettings - マーカー設定
• BubbleSettings - バブルの視覚化
• DataLabelSettings - データラベル

ユーザー操作

• ZoomSettings - ズームとパンの設定
• TooltipSettings - ツールチップの設定
• SelectionSettings - 選択動作
• HighlightSettings - ハイライト動作

カスタマイズ

• LegendSettings - 凡例の設定
• ColorMappingSettings - コロプレスマップの色分け
• NavigationLineSettings - ナビゲーションライン
• Annotation - カスタム注釈

主なイベント（合計 25 件以上）

• load - マップの読み込み前
• loaded - マップの読み込み後
• shapeSelected - 形状の選択イベント
• markerClick - マーカーのクリックイベント
• zoom - ズームイベント
• pan - パンイベント

列挙型

• ProjectionType - 地図投影法の種類（Mercator、Miller、Eckert など）
• MarkerType - マーカーの形状（Balloon、Circle、Diamond など）
• LayerType - レイヤーとサブレイヤー
• GeometryType - 地理座標と通常座標

イベントインターフェース

• ILoadEventArgs - 読み込みイベントの引数
• IShapeSelectedEventArgs - 選択イベントの引数
• IMarkerClickEventArgs - マーカークリックの引数

コンテキスト別 API リファレンス

各リファレンスガイドには、関連する API の表が含まれています。

• getting-started.md - 基本的なセットアップ API
• layers-and-data.md - レイヤーとデータバインディングの API
• markers.md - マーカーの API とイベント
• data-visualization.md - バブル、色のマッピング、凡例の API
• user-interactions.md - ズーム、パン、ツールチップ、選択の API
• map-providers.md - マッププロバイダーの API
• customization.md - 外観とスタイルの API
• accessibility.md - アクセシビリティ関連の API

---

次のステップ

1. getting-started.md から始めて、最初のマップをセットアップします
2. layers-and-data.md を確認して、データバインディングについて理解します
3. markers.md を追加して、位置をプロットします
4. user-interactions.md を実装して、ズーム、パン、ツールチップを利用できるようにします
5. customization.md を確認して、スタイルとテーマを設定します
6. accessibility.md を確認して、WCAG への準拠を確保します

---

パッケージ： @syncfusion/ej2-angular-maps
ドキュメント： Syncfusion Angular Maps Documentation
デモ： Syncfusion Angular Maps Demos