GMap.NET 實戰教學：在 WinForms 與 WPF 中整合 Google/OpenStreetMap 離線線上地圖

GMap.NET 是 .NET 生態最成熟的開源地圖控件庫，支援 Google、Bing、OpenStreetMap、ArcGIS 等十幾家提供者，兼容 WinForms、WPF、Mobile。本文從專案建立、核心 DLL 參考、控件封裝、地圖初始化、標記互動完整演示雙平台整合。

專案準備

1. 下載原始碼 (CodePlex 歸檔或 GitHub 鏡像)：greatmaps_81b71bf30091
2. 編譯三個核心專案：
   GMap.NET.Core (核心邏輯)
   GMap.NET.WindowsForms (WinForms 控件)
   GMap.NET.WindowsPresentation (WPF 控件)
3. 專案參考對應 DLL。

WinForms 整合步驟

1. 封裝自訂控件 (方便工具箱拖放)

public partial class MapControl : GMap.NET.WindowsForms.GMapControl {
  public MapControl() { InitializeComponent(); }
}

建置後工具箱自動出現 MapControl，拖入 Form 即可。

2. Form 載入初始化

public partial class MainForm : Form {
  public MainForm() {
    InitializeComponent();
    InitMap();
  }

  private void InitMap() {
    // 離線模式檢測
    try { System.Net.Dns.GetHostEntry("www.google.com.hk"); }
    catch { mapControl.Manager.Mode = AccessMode.CacheOnly; }

    mapControl.MapProvider = GMap.NET.MapProviders.GMapProviders.GoogleChinaMap;
    mapControl.MinZoom = 2;
    mapControl.MaxZoom = 17;
    mapControl.Zoom = 5;
    mapControl.ShowCenter = false; // 隱藏中心十字
    mapControl.DragButton = MouseButtons.Left;
    mapControl.Position = new PointLatLng(32.064, 118.704); // 南京

    mapControl.OnMapZoomChanged += MapControl_OnMapZoomChanged;
    mapControl.MouseClick += MapControl_MouseClick;
  }

  private void MapControl_MouseClick(object sender, MouseEventArgs e) {
    if (e.Button == MouseButtons.Left) {
      PointLatLng pt = mapControl.FromLocalToLatLng(e.X, e.Y);
      GMap.NET.WindowsForms.GMapMarker marker = new GMap.NET.WindowsForms.Markers.GMarkerGoogle(pt, GMarkerGoogleType.red_dot);
      mapControl.Overlays.Add(new GMap.NET.WindowsForms.GMapOverlay("markers") { Markers = { marker } });
    }
  }
}

WPF 整合步驟

1. 繼承類別 (WPF UserControl 無法變更基類)

public class MapControl : GMap.NET.WindowsPresentation.GMapControl { }

2. XAML 引用命名空間與控件

<Window x:Class="GMapWPFDemo.MainWindow"
        xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:src="clr-namespace:GMapWPFDemo"
        Title="MainWindow" Height="410" Width="618">
  <Grid>
    <GroupBox Name="mapgroup">
      <src:MapControl x:Name="mapControl" Zoom="13" MaxZoom="24" MinZoom="1" />
    </GroupBox>
  </Grid>
</Window>

3. 後置碼初始化 (API 與 WinForms 大同小異)

mapControl.MapProvider = GMapProviders.GoogleChinaMap;
mapControl.MinZoom = 2; mapControl.MaxZoom = 17; mapControl.Zoom = 5;
mapControl.ShowCenter = false;
mapControl.DragButton = MouseButton.Left;
mapControl.Position = new PointLatLng(32.064, 118.704);

mapControl.MouseLeftButtonDown += (s, e) => {
  Point click = e.GetPosition(mapControl);
  PointLatLng pt = mapControl.FromLocalToLatLng((int)click.X, (int)click.Y);
  var marker = new GMap.NET.WindowsPresentation.GMapMarker(pt);
  mapControl.Markers.Add(marker);
};

兩平台關鍵差異對照

實用進階技巧

1. 離線地圖：預先用 GMaps.Instance.Mode = AccessMode.CacheOnly + CacheLocation，搭配 MapType 下載瓦片 (需遵守提供者授權)。
2. 自訂 Marker 模板 (WPF)：定義 DataTemplate 含 Ellipse、TextBlock、Image，綁定 Marker.Shape。
3. 路徑規劃/多邊形：GMapRoute、GMapPolygon 同樣加入 Overlays/Markers 集合。
4. 授權合規：商業專案請確認 Google Maps/Bing Maps 授權條款，或改用 OpenStreetMap (ODbL) / 高德/騰訊地圖 SDK (需申請 Key)。