syncfusion-winforms-map

Windows Forms でのマップの実装

Syncfusion WinForms Maps コントロールは、シェープファイルを描画し、ズーム、パン、ツールチップ、選択などのインタラクティブ機能を備えた統計情報を表示する、強力な地理データ可視化コンポーネントです。

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

次のような用途では、Maps コントロールを使用します。

• 地理データの可視化：世界地図、国別地図、地域地図に地理データを表示する
• 統計マップ：地域ごとの統計データ（人口、売上、人口統計）を示すコロプレスマップを作成する
• バブルマップ：地図上の位置に、さまざまなサイズのバブルを使ってデータを可視化する
• マルチレイヤーマップ：複数の地理レイヤー（例：強調表示された地域を含む世界地図）を組み合わせる
• インタラクティブマップ：ツールチップ、選択、ズーム、パンによるユーザー操作を可能にする
• ダッシュボードへの統合：デスクトップダッシュボードアプリケーションにマップの可視化を追加する
• 位置情報分析：位置情報ベースのデータを分析・表示するアプリケーションを構築する

コンポーネントの概要

主な機能：

• シェープファイルの描画（.shp、.dbf、.shx）
• SubShapeFileLayers による複数レイヤーのサポート
• ItemSource によるデータバインディング
• サイズと色のマッピングによるバブルの可視化
• 位置をカスタマイズできる凡例のサポート
• インタラクティブ機能：ツールチップ、選択、ズーム、パン
• カスタムマーカー用の注釈
• 色、線、塗りつぶしの幅広いカスタマイズオプション

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

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と NuGet のインストール
• 主要な概念とマップの構造
• シェープファイルの説明と要件
• シェープファイルを埋め込みリソースとして追加する
• Uri プロパティの構成
• 最初のマップを作成する
• 基本的な実装例

レイヤーとシェープファイル

📄 参照： references/layers.md

• ShapeFileLayer のアーキテクチャ
• 複数のレイヤーの追加（マルチレイヤーのサポート）
• SubShapeFileLayer の使用方法
• LayoutType の構成（Default と Tile）
• ItemSource のデータバインディング
• ShapeIDPath と ShapeIDTableField のマッピング
• レイヤーのカスタマイズ

バブル

📄 参照： references/bubbles.md

• マップへのバブルの追加
• BubbleSetting プロパティ（AutoFillColors、MaxSize、MinSize）
• ValuePath と ColorValuePath の構成
• バブルの範囲別カラー マッピング
• StrokeThickness と Fill のカスタマイズ
• バブルの可視化例

凡例

📄 参照： references/legends.md

• 凡例の表示（ShowLegend）
• 凡例の位置（Position、PositionX、PositionY）
• 凡例のヘッダーとタイトル
• 凡例のカテゴリ（レイヤーとバブル）
• LegendType と LegendIcon
• 凡例の形状のカスタマイズ

ユーザー操作

📄 参照： references/user-interaction.md

• ツールチップのサポート（ShowToolTip）
• 単一選択と複数選択
• EnableSelection と SelectionMode
• SelectedShapeColor のカスタマイズ
• ZoomFactor と ZoomLevel によるズーム
• パンとナビゲーション
• ShapeSelected イベントの処理

マップポイント

📄 参照： references/map-points.md

• ポイントのシェープファイルとジオメトリ
• ポイントデータレイヤーの読み込み
• ポイント、ポリゴン、ポリラインの形状
• ポイントマーカーのスタイル設定
• ポイントデータのバインディング
• 複数のポイントレイヤー

注釈

📄 参照： references/annotations.md

• カスタム注釈の追加
• 緯度と経度による配置
• AnnotationDrawing イベント
• カスタムマーカーとアイコン
• 注釈コレクション
• マップ上へのカスタムグラフィックの描画

カスタマイズ

📄 参照： references/customization.md

• マップの外観のスタイル設定
• シェイプの塗りつぶしと線のカスタマイズ
• カラー値のパス
• FillSetting の構成
• 範囲別の ColorMappings
• テーマとの統合
• 高度なスタイル設定の手法

クイックスタート

ステップ 1：NuGet パッケージをインストールする

Install-Package Syncfusion.Maps.WinForms

ステップ 2：シェイプファイルをプロジェクトに追加する

1. シェイプファイル（例：world1.shp、world1.dbf、world1.shx）をプロジェクトに追加します
2. ソリューション エクスプローラーでファイルを選択します
3. Build Action を Embedded Resource に設定します
4. Copy to Output Directory を Copy if newer に設定します（任意）

ステップ 3：基本的なマップの実装

using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Maps;

namespace WinFormsMapsExample
{
    public partial class Form1 : Form
    {
        private Maps mapsControl;

        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {
            // Create Maps control
            mapsControl = new Maps();
            mapsControl.Name = "mapsControl";
            mapsControl.Size = new Size(880, 585);
            mapsControl.Dock = DockStyle.Fill;
            mapsControl.MapBackgroundBrush = new SolidBrush(Color.White);

            // Create and configure shape layer
            ShapeFileLayer shapeLayer = new ShapeFileLayer();
            shapeLayer.Uri = "world1.shp";  // Shape file name
            
            // Add layer to map
            mapsControl.Layers.Add(shapeLayer);
            
            // Add control to form
            this.Controls.Add(mapsControl);
        }
    }
}

一般的なパターン

パターン 1：統計ビジュアライゼーションを備えたデータ バインド型マップ

private void CreateDataBoundMap()
{
    // Prepare data
    MapViewModel model = new MapViewModel();
    
    // Create shape layer
    ShapeFileLayer shapeLayer = new ShapeFileLayer();
    shapeLayer.Uri = "world1.shp";
    
    // Bind data
    shapeLayer.ItemSource = model.Countries;
    shapeLayer.ShapeIDPath = "NAME";            // Property in data model
    shapeLayer.ShapeIDTableField = "NAME";      // Column in .dbf file
    
    // Configure shape display
    shapeLayer.ShapeSetting.ShapeValuePath = "Population";
    shapeLayer.ShapeSetting.ShapeColorValuePath = "Population";
    shapeLayer.ShapeSetting.ShapeDisplayValuePath = "NAME";
    
    // Style settings
    shapeLayer.ShapeSetting.ShapeFill = "#E5E5E5";
    shapeLayer.ShapeSetting.ShapeStroke = "#C1C1C1";
    shapeLayer.ShapeSetting.ShapeStrokeThickness = 1.5;
    
    // Enable features
    shapeLayer.ShowToolTip = true;
    shapeLayer.EnableSelection = true;
    
    mapsControl.Layers.Add(shapeLayer);
}

// Data Model
public class Country
{
    public string NAME { get; set; }
    public double Population { get; set; }
}

パターン 2：マルチレイヤーマップ

private void CreateMultiLayerMap()
{
    // Base world layer
    ShapeFileLayer worldLayer = new ShapeFileLayer();
    worldLayer.Uri = "world1.shp";
    worldLayer.ShapeSetting.ShapeFill = "#E5E5E5";
    worldLayer.ShapeSetting.ShapeStroke = "#C1C1C1";
    worldLayer.ShapeSetting.ShapeStrokeThickness = 0.5;

    // Highlighted region 1
    SubShapeFileLayer africaLayer = new SubShapeFileLayer();
    africaLayer.Uri = "africa.shp";
    africaLayer.ShapeSetting.ShapeFill = "#8DCEFF";
    africaLayer.ShapeSetting.ShapeStroke = "#2F8CEA";
    africaLayer.ShapeSetting.ShapeStrokeThickness = 0.5;

    // Highlighted region 2
    SubShapeFileLayer australiaLayer = new SubShapeFileLayer();
    australiaLayer.Uri = "australia.shp";
    australiaLayer.ShapeSetting.ShapeFill = "#FFA07A";
    australiaLayer.ShapeSetting.ShapeStroke = "#FF6347";
    australiaLayer.ShapeSetting.ShapeStrokeThickness = 0.5;

    // Add sublayers to main layer
    worldLayer.SubShapeFileLayers.Add(africaLayer);
    worldLayer.SubShapeFileLayers.Add(australiaLayer);
    
    mapsControl.Layers.Add(worldLayer);
}

パターン 3：カラー範囲を使用したバブルマップ

private void CreateBubbleMap()
{
    ShapeFileLayer shapeLayer = new ShapeFileLayer();
    shapeLayer.Uri = "world1.shp";
    shapeLayer.ItemSource = GetCountries();
    shapeLayer.ShapeIDPath = "NAME";
    shapeLayer.ShapeIDTableField = "NAME";

    // Configure bubbles
    shapeLayer.BubbleSetting.AutoFillColors = false;
    shapeLayer.BubbleSetting.MaxSize = 70;
    shapeLayer.BubbleSetting.MinSize = 25;
    shapeLayer.BubbleSetting.ValuePath = "Population";
    shapeLayer.BubbleSetting.ColorValuePath = "Population";

    // Define color ranges
    shapeLayer.BubbleSetting.ColorMappings = 
        new System.Collections.ObjectModel.ObservableCollection<ColorMapping>
        {
            new RangeColorMapping 
            { 
                From = 1000000000, 
                To = 2000000000, 
                Color = Color.FromArgb(127, 32, 188, 238) 
            },
            new RangeColorMapping 
            { 
                From = 500000000, 
                To = 1000000000, 
                Color = Color.FromArgb(127, 167, 206, 56) 
            },
            new RangeColorMapping 
            { 
                From = 100000000, 
                To = 500000000, 
                Color = Color.FromArgb(127, 241, 178, 26) 
            },
            new RangeColorMapping 
            { 
                From = 0, 
                To = 100000000, 
                Color = Color.FromArgb(127, 235, 115, 124) 
            }
        };

    mapsControl.Layers.Add(shapeLayer);
}

パターン 4：イベント対応のインタラクティブマップ

private void CreateInteractiveMap()
{
    ShapeFileLayer shapeLayer = new ShapeFileLayer();
    shapeLayer.Uri = "world1.shp";
    shapeLayer.ItemSource = GetCountries();
    shapeLayer.ShapeIDPath = "Country";
    shapeLayer.ShapeIDTableField = "NAME";
    
    // Enable interaction
    shapeLayer.ShowToolTip = true;
    shapeLayer.EnableSelection = true;
    shapeLayer.SelectionMode = SelectionModes.Multiple;
    
    // Style selected shapes
    shapeLayer.ShapeSetting.SelectedShapeColor = Color.Orange;
    
    // Enable zooming
    mapsControl.ZoomFactor = 1.0f;
    mapsControl.ZoomLevel = 1;
    
    // Subscribe to events
    mapsControl.ShapeSelected += MapsControl_ShapeSelected;
    
    mapsControl.Layers.Add(shapeLayer);
}

private void MapsControl_ShapeSelected(object sender, ShapeSelectedEventArgs e)
{
    if (e.Data != null)
    {
        foreach (Country country in e.Data)
        {
            Console.WriteLine($"Selected: {country.Country}");
        }
    }
}

主なプロパティ

Maps コントロールのプロパティ

プロパティ	型	説明
Layers	LayerCollection	ShapeFileLayer のコレクション
MapBackgroundBrush	Brush	マップの背景色
MapItemsShape	MapItemShapes	マップアイテムの形状（Circle、Diamond など）
ZoomFactor	float	ズームレベル係数
ZoomLevel	int	ズームレベルの倍率
SelectedMapShapes	Collection	現在選択されているシェイプ

ShapeFileLayer のプロパティ

プロパティ	型	説明
Uri	string	シェイプファイル（.shp）へのパス
ItemSource	object	バインドするデータソース
ShapeIDPath	string	データモデル内のプロパティ名
ShapeIDTableField	string	.dbf ファイル内の列名
ShowToolTip	bool	ツールチップの有効化／無効化
EnableSelection	bool	選択の有効化／無効化
SelectionMode	SelectionModes	単一または複数選択
ShowLegend	bool	凡例の表示／非表示
LayoutType	LayoutType	既定またはタイルレイアウト
SubShapeFileLayers	Collection	追加のシェイプレイヤー

ShapeSetting のプロパティ

プロパティ	型	説明
ShapeFill	string/Color	シェイプの塗りつぶし色
ShapeStroke	string/Color	シェイプの線の色
ShapeStrokeThickness	double	境界線の太さ
ShapeValuePath	string	値のバインドに使用するプロパティ
ShapeColorValuePath	string	色のマッピングに使用するプロパティ
SelectedShapeColor	Color	選択されたシェイプの色

BubbleSetting のプロパティ

プロパティ	型	説明
AutoFillColors	bool	バブルの色を自動生成する
MaxSize	double	バブルの最大サイズ
MinSize	double	バブルの最小サイズ
ValuePath	string	バブルサイズに使用するプロパティ
ColorValuePath	string	バブルの色に使用するプロパティ
ColorMappings	Collection	範囲ベースの色マッピング

一般的なユースケース

ユースケース 1：人口密度マップ

人口範囲に基づいて地域を色分けし、国ごとの世界人口を表示します。

ユースケース 2：販売テリトリーマップ

販売量を表すバブルと、実績の段階を示す色を使って、地域ごとの販売データを可視化します。

ユースケース 3：選挙結果マップ

州／県ごとの選挙結果を表示し、勝者を色分けして、投票数を示すツールチップを表示します。

ユースケース 4：地域分析ダッシュボード

人口統計や経済指標など、異なるデータの次元を表示する複数のマップレイヤーを備えたダッシュボードを作成します。

ユースケース 5：位置情報ベースのアプリケーション

カスタム注釈で特定の場所を強調表示し、ユーザーがマップ上の地域を操作できるデスクトップアプリケーションを構築します。

トラブルシューティング

問題：シェープファイルが読み込まれない

• ファイルが埋め込みリソースとして追加されていることを確認してください
• Uri がシェープファイル名と完全に一致していることを確認してください
• .shp ファイルと一緒に .dbf ファイルが含まれていることを確認してください

問題：データがシェープにバインドされない

• ShapeIDPath がデータモデルのプロパティと一致していることを確認してください
• ShapeIDTableField が .dbf ファイルの列と一致していることを確認してください
• 値が完全に一致していることを確認してください（大文字と小文字を区別します）

問題：色が正しく表示されない

• ColorMappings を使用する場合は、AutoFillColors = false を設定してください
• 色の範囲がすべてのデータ値をカバーしていることを確認してください
• ColorValuePath が正しいプロパティを指していることを確認してください

問題：選択が機能しない

• EnableSelection = true を設定してください
• SelectionMode（Single または Multiple）を設定してください
• 選択するシェープにバインドされたデータがあることを確認してください