syncfusion-wpf-map

实现 Syncfusion WPF Maps（SfMap）

Syncfusion WPF Maps 控件是一个功能强大的组件，可在 Windows Presentation Foundation 应用程序中可视化地理数据。它全面支持渲染形状文件、显示地图图像、添加标记和气泡，以及创建可进行丰富自定义的交互式数据可视化。

何时使用此技能

在以下情况下使用此技能：

• 使用形状文件（.shp、.dbf）渲染地理地图
• 通过颜色编码在地图上可视化统计数据
• 添加标记、气泡和工具提示等交互元素
• 显示来自 OpenStreetMap 或 Bing Maps 的地图图像
• 创建使用数据驱动颜色映射的分级统计地图
• 实现地图图例以便解读数据
• 启用缩放、平移和选择等用户交互
• 构建包含地理数据可视化的仪表板
• 支持包含叠加层和子图层的多图层地图
• 使用主题和模板自定义地图外观

组件概述

SfMap 是一个图形表示控件，可显示地理数据，并具备以下功能：

核心功能

• 多种图层类型： 用于矢量形状的 ShapeFileLayer、用于地图块的 ImageryLayer
• 数据绑定： 将业务对象关联到地图形状
• 视觉元素： 标记、气泡、注释、标签
• 颜色映射： 基于范围和分类的颜色编码
• 图例： 自动生成并可自定义的图例
• 用户交互： 缩放、平移、选择、工具提示
• 多图层支持： 子图层和 KML 叠加层

主要用例

• 天气数据可视化
• 人口密度地图
• 销售区域分析
• 政治／选举地图
• 建筑／楼层平面图布局
• 资源可用性映射

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 通过 NuGet（Syncfusion.SfMaps.WPF）安装
• 所需程序集和命名空间导入
• 创建第一个 SfMap 控件
• 了解形状文件结构（.shp、.dbf）
• 配置形状文件的 Uri 属性
• 基本 XAML 和 C# 实现
• 最精简的可运行示例

图层配置

📄 阅读： references/layers.md

• ShapeFileLayer 与 ImageryLayer 的对比
• ShapeSettings 配置
• ShapeFill、ShapeStroke、ShapeStrokeThickness 属性
• 使用 EnableSelection 启用交互式选择
• 自定义所选形状（SelectedShapeColor、SelectedShapeStroke）
• 图层背景和视觉属性
• 多图层管理

📄 阅读： references/map-providers.md

• 用于地图块的 ImageryLayer
• 集成 OpenStreetMap
• 配置 Bing Maps
• 自定义地图块提供程序
• 缩放级别和缓存

数据绑定与填充

📄 阅读： references/data-binding.md

• 将 ItemsSource 绑定到集合
• ShapeIDPath 和 ShapeIDTableField 映射
• 用于数值数据的 ShapeValuePath
• 用于颜色绑定的 ShapeColorValuePath
• 使用 INotifyPropertyChanged 的 ObservableCollection
• MVVM 模式实现
• 绑定故障排除

可视化元素

📄 阅读： references/markers.md

• 向地图添加标记
• 标记模型属性（Label、Latitude、Longitude）
• 默认标记呈现
• 自定义 MarkerTemplate
• 使用 MarkerTemplateSelector 实现条件样式
• MarkerIconFill 和 MarkerLabelForeground
• 定位与对齐

📄 阅读： references/bubbles.md

• 配置 BubbleMarkerSetting
• 使用 ValuePath 根据数据调整大小
• MinSize 和 MaxSize 属性
• ColorValuePath 和 ColorMappings
• AutoFillColor 与自定义 Fill
• Stroke、StrokeThickness、Opacity
• 气泡图例

📄 阅读： references/shapes-color-customization.md

• 形状颜色属性
• AutoFillColors 属性
• 对连续数据使用 RangeColorMapping
• 对分类数据使用 EqualsColorMapping
• 类似树状图的可视化
• 颜色调色板和渐变
• 自定义颜色逻辑

📄 阅读： references/legends.md

• LegendVisibility 和定位
• LegendPosition 枚举值
• 使用 LegendPositionX 和 LegendPositionY 自定义位置
• 使用 LegendHeader 设置标题
• LegendType（Layers 或 Bubbles）
• LegendIcon 形状（Rectangle、Circle、Diamond、Triangle）
• 使用 LegendColumnSplit 实现多列布局
• 自定义图例模板

📄 阅读： references/map-labels.md

• 使用 LabelPath 为形状添加标签
• 自定义 ShapeLabelTemplate
• 标签定位与可见性
• 字体样式和格式
• 基于缩放级别显示标签

交互性

📄 阅读： references/user-interaction.md

• 配置 ToolTipSettings
• EnableZoom 和 EnablePan 属性
• MinZoom 和 MaxZoom 限制
• ZoomLevel 属性
• 使用 EnableSelection 选择形状
• 鼠标、触控和键盘交互
• 自定义工具提示模板
• 以编程方式缩放和平移

📄 阅读： references/events.md

• ShapeSelected 事件
• ShapeSelectionChanged 事件
• BubbleMarkerSelected 事件
• MarkerSelected 事件
• ZoomLevelChanged 事件
• 事件参数和数据访问

高级功能

📄 阅读： references/annotations.md

• Annotations 集合
• 文本、形状和图像注释
• 坐标定位
• 自定义注释模板
• 可见性和交互

📄 阅读： references/multilayer-support.md

• SubShapeFileLayers 集合
• 添加多个形状图层
• 支持 KML 文件
• 自定义 KmlItemsTemplate
• 图层顺序和 z-index
• 组合矢量图层与影像图层

快速入门示例

以下是一个使用数据绑定和颜色映射创建地图的最简示例：

XAML

<Window xmlns:syncfusion="clr-namespace:Syncfusion.UI.Xaml.Maps;assembly=Syncfusion.SfMaps.WPF">
    <Grid>
        <Grid.DataContext>
            <local:MapViewModel />
        </Grid.DataContext>

        <syncfusion:SfMap>
            <syncfusion:SfMap.Layers>
                <syncfusion:ShapeFileLayer Uri="MyApp.ShapeFiles.world1.shp"
                                           ItemsSource="{Binding Countries}"
                                           ShapeIDPath="Name"
                                           ShapeIDTableField="NAME"
                                           EnableSelection="True">
                    
                    <syncfusion:ShapeFileLayer.ShapeSettings>
                        <syncfusion:ShapeSetting ShapeValuePath="Population"
                                                 ShapeStroke="White"
                                                 ShapeStrokeThickness="1">
                            <syncfusion:ShapeSetting.FillSetting>
                                <syncfusion:ShapeFillSetting AutoFillColors="False">
                                    <syncfusion:ShapeFillSetting.ColorMappings>
                                        <syncfusion:RangeColorMapping From="0" To="1000000" Color="#FEE5D9" />
                                        <syncfusion:RangeColorMapping From="1000000" To="10000000" Color="#FCAE91" />
                                        <syncfusion:RangeColorMapping From="10000000" To="100000000" Color="#FB6A4A" />
                                        <syncfusion:RangeColorMapping From="100000000" To="1000000000" Color="#CB181D" />
                                    </syncfusion:ShapeFillSetting.ColorMappings>
                                </syncfusion:ShapeFillSetting>
                            </syncfusion:ShapeSetting.FillSetting>
                        </syncfusion:ShapeSetting>
                    </syncfusion:ShapeFileLayer.ShapeSettings>                 
                </syncfusion:ShapeFileLayer>
            </syncfusion:SfMap.Layers>
        </syncfusion:SfMap>
    </Grid>
</Window>

C# ViewModel

using System.Collections.ObjectModel;
using System.ComponentModel;

public class Country : INotifyPropertyChanged
{
    private string name;
    private int population;

    public string Name
    {
        get { return name; }
        set { name = value; OnPropertyChanged(nameof(Name)); }
    }

    public int Population
    {
        get { return population; }
        set { population = value; OnPropertyChanged(nameof(Population)); }
    }

    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

public class MapViewModel
{
    public ObservableCollection<Country> Countries { get; set; }

    public MapViewModel()
    {
        Countries = new ObservableCollection<Country>
        {
            new Country { Name = "United States", Population = 331000000 },
            new Country { Name = "China", Population = 1400000000 },
            new Country { Name = "India", Population = 1380000000 },
            new Country { Name = "Brazil", Population = 212000000 }
        };
    }
}

常见模式

模式 1：使用自定义模板添加标记

<syncfusion:ShapeFileLayer Uri="MyApp.ShapeFiles.usa_state.shp"
                           Markers="{Binding Cities}">
    <syncfusion:ShapeFileLayer.MarkerTemplate>
        <DataTemplate>
            <Grid>
                <Ellipse Width="12" Height="12" Fill="Red" />
                <TextBlock Text="{Binding Label}" 
                           Margin="0,15,0,0"
                           FontSize="11"
                           Foreground="Black" />
            </Grid>
        </DataTemplate>
    </syncfusion:ShapeFileLayer.MarkerTemplate>
</syncfusion:ShapeFileLayer>

public class City
{
    public string Label { get; set; }
    public string Latitude { get; set; }
    public string Longitude { get; set; }
}

模式 2：实现工具提示

<syncfusion:ShapeFileLayer.ToolTipSettings>
    <syncfusion:ToolTipSetting ValuePath="Population" />
</syncfusion:ShapeFileLayer.ToolTipSettings>

模式 3：启用交互式缩放和平移

<syncfusion:SfMap EnableZoom="True" 
                  EnablePan="True"
                  MinZoom="1"
                  MaxZoom="20"
                  ZoomLevel="5" />

模式 4：创建图例

<syncfusion:ShapeFileLayer LegendVisibility="Visible"
                           LegendPosition="BottomLeft"
                           LegendHeader="Population Density"
                           LegendIcon="Rectangle"
                           LegendColumnSplit="2" />

关键属性

SfMap 属性

• EnableZoom (bool)：启用/禁用缩放功能
• EnablePan (bool)：启用/禁用平移功能
• MinZoom (double)：最小缩放级别
• MaxZoom (double)：最大缩放级别
• ZoomLevel (double)：当前缩放级别
• Layers (ObservableCollection<MapLayer>)：地图图层集合

ShapeFileLayer 属性

• Uri (string)：形状文件（.shp）的路径，作为嵌入资源
• ItemsSource (IEnumerable)：用于绑定的数据源
• ShapeIDPath (string)：数据源中用于匹配形状的属性路径
• ShapeIDTableField (string)：用于匹配的 .dbf 文件中的字段名称
• EnableSelection (bool)：启用形状选择
• Markers (IEnumerable)：标记对象集合
• LegendVisibility (Visibility)：显示/隐藏图例
• LegendPosition (LegendPosition)：图例的标准位置
• LegendPositionX/Y (double)：自定义图例坐标
• LegendHeader (string)：图例标题文本
• LegendIcon (LegendIcons)：图例项的图标形状
• LegendType (LegendType)：形状或气泡图例
• LegendColumnSplit (int)：图例列数
• ToolTipSettings (ToolTipSetting)：工具提示配置

ShapeSetting 属性

• ShapeFill (Brush)：形状的默认填充颜色
• ShapeStroke (Brush)：形状的边框颜色
• ShapeStrokeThickness (double)：边框粗细
• ShapeValuePath (string)：数据值对应的属性
• ShapeColorValuePath (string)：颜色值对应的属性
• SelectedShapeColor (Brush)：选中形状的填充颜色
• SelectedShapeStroke (Brush)：选中形状的边框颜色
• SelectedShapeStrokeThickness (double)：选中形状的边框粗细
• FillSetting (ShapeFillSetting)：颜色映射配置

BubbleMarkerSetting 属性

• ValuePath (string)：气泡大小值对应的属性
• ColorValuePath (string)：气泡颜色对应的属性
• MinSize (double)：气泡最小直径
• MaxSize (double)：气泡最大直径
• Fill (Brush)：气泡填充颜色
• Stroke (Brush)：气泡边框颜色
• StrokeThickness (double)：气泡边框粗细
• Opacity (double)：气泡不透明度（0-1）
• AutoFillColor (bool)：启用自动分配颜色
• ColorMappings (ObservableCollection)：范围/相等值颜色映射

常见用例

用例 1：人口密度地图

通过颜色区分不同区域来展示人口数据，并使用交互式工具提示显示详细统计信息。

用例 2：销售区域可视化

展示各地理区域的销售业绩，以气泡表示收入，并以颜色表示增长率。

用例 3：选举结果地图

使用分类颜色可视化不同候选人的投票结果，并通过图例辅助解读。

用例 4：天气数据仪表板

在地图上显示温度、降水量或其他天气指标，并实时更新数据。

用例 5：商店位置查找器

使用自定义标记标示商店位置，并启用缩放/平移功能，让用户探索不同区域。

用例 6：建筑平面图

使用自定义形状文件渲染建筑布局，并显示房间标签和占用数据。

---

后续步骤： 根据实现需求，转到上文中相应的参考文件。先从 getting-started.md 开始进行初始设置，然后按需查看其他参考文件。