syncfusion-winforms-map

在 Windows Forms 中实现地图

Syncfusion WinForms Maps 控件是一款功能强大的地理数据可视化组件，可渲染形状文件并显示统计信息，还支持缩放、平移、工具提示和选择等交互功能。

何时使用此技能

在以下情况下使用 Maps 控件：

• 地理可视化：在世界地图、国家地图或区域地图上显示地理数据
• 统计地图：创建按区域展示统计数据（人口、销售额、人口统计信息）的分级统计地图
• 气泡地图：使用大小不同的气泡可视化地图位置上的数据
• 多图层地图：组合多个地理图层（例如，带有高亮区域的世界地图）
• 交互式地图：通过工具提示、选择、缩放和平移支持用户交互
• 仪表板集成：将地图可视化添加到桌面仪表板应用程序
• 位置分析：构建用于分析和显示基于位置的数据的应用程序

组件概述

主要功能：

• 形状文件渲染（.shp、.dbf、.shx）
• 支持使用 SubShapeFileLayers 添加多个图层
• 使用 ItemSource 进行数据绑定
• 支持通过大小和颜色映射实现气泡可视化
• 支持图例及其自定义位置
• 交互功能：工具提示、选择、缩放、平移
• 用于自定义标记的注释
• 提供丰富的颜色、描边和填充自定义选项

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 安装
• 核心概念和地图结构
• 形状文件说明和要求
• 将形状文件添加为嵌入资源
• Uri 属性配置
• 创建第一张地图
• 基本实现示例

图层和形状文件

📄 阅读： references/layers.md

• ShapeFileLayer 架构
• 添加多个图层（支持 MultiLayer）
• 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. 将 生成操作 设置为 嵌入的资源
4. 将 复制到输出目录 设置为 如果较新则复制（可选）

步骤 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 与形状文件名完全一致
• 确保 .dbf 文件与 .shp 文件一同包含

问题：数据未绑定到形状

• 确认 ShapeIDPath 与数据模型中的属性匹配
• 确认 ShapeIDTableField 与 .dbf 文件中的列匹配
• 检查值是否完全一致（区分大小写）

问题：颜色显示不正确

• 使用 ColorMappings 时，将 AutoFillColors = false
• 确保颜色范围覆盖所有数据值
• 确认 ColorValuePath 指向正确的属性

问题：选择功能无效

• 将 EnableSelection = true
• 配置 SelectionMode（Single 或 Multiple）
• 确保形状已绑定数据，以便进行选择