syncfusion-wpf-map

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF Maps (SfMap)

实现Syncfusion WPF Maps（SfMap）

The Syncfusion WPF Maps control is a powerful component for visualizing geographical data in Windows Presentation Foundation applications. It provides comprehensive support for rendering shape files, displaying map imagery, adding markers and bubbles, and creating interactive data visualizations with rich customization options.

Syncfusion WPF Maps控件是一款功能强大的组件，用于在Windows Presentation Foundation（WPF）应用中实现地理数据可视化。它全面支持渲染形状文件、显示地图影像、添加标记和气泡，以及创建具有丰富自定义选项的交互式数据可视化效果。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Render geographical maps using shape files (.shp, .dbf)
Visualize statistical data on maps with color coding
Add interactive elements like markers, bubbles, and tooltips
Display map imagery from OpenStreetMap or Bing Maps
Create choropleth maps with data-driven color mapping
Implement map legends for data interpretation
Enable user interaction with zoom, pan, and selection
Build dashboards with geographical data visualization
Support multilayer maps with overlays and sublayers
Customize map appearance with themes and templates

当你需要以下功能时，可使用本技能：

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

Component Overview

组件概述

SfMap is a graphical representation control that displays geographical data with the following capabilities:

SfMap是一款图形化展示控件，用于呈现地理数据，具备以下功能：

Core Features

核心功能

Multiple layer types: ShapeFileLayer for vector shapes, ImageryLayer for tiles
Data binding: Connect business objects to map shapes
Visual elements: Markers, bubbles, annotations, labels
Color mapping: Range-based and categorical color coding
Legends: Automatic legend generation with customization
User interaction: Zoom, pan, selection, tooltips
Multilayer support: Sublayers and KML overlays

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

Key Use Cases

主要应用场景

Weather data visualization
Population density maps
Sales territory analysis
Political/election maps
Building/floor plan layouts
Resource availability mapping

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation via NuGet (Syncfusion.SfMaps.WPF)
Required assemblies and namespace imports
Creating your first SfMap control
Understanding shape file structure (.shp, .dbf)
Configuring Uri property for shape files
Basic XAML and C# implementation
Minimal working example

📄 阅读： references/getting-started.md

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

Layer Configuration

图层配置

📄 Read: references/layers.md

ShapeFileLayer vs ImageryLayer
ShapeSettings configuration
ShapeFill, ShapeStroke, ShapeStrokeThickness properties
EnableSelection for interactive selection
Customizing selected shapes (SelectedShapeColor, SelectedShapeStroke)
Layer background and visual properties
Multiple layers management

📄 Read: references/map-providers.md

ImageryLayer for map tiles
OpenStreetMap integration
Bing Maps configuration
Custom tile providers
Zoom levels and caching

📄 阅读： references/layers.md

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

📄 阅读： references/map-providers.md

ImageryLayer用于瓦片地图
OpenStreetMap集成
Bing Maps配置
自定义瓦片提供商
缩放级别和缓存

Data Binding and Population

数据绑定与填充

📄 Read: references/data-binding.md

ItemsSource binding to collections
ShapeIDPath and ShapeIDTableField mapping
ShapeValuePath for numerical data
ShapeColorValuePath for color binding
ObservableCollection with INotifyPropertyChanged
MVVM pattern implementation
Binding troubleshooting

📄 阅读： references/data-binding.md

ItemsSource绑定到集合
ShapeIDPath和ShapeIDTableField映射
ShapeValuePath用于数值数据
ShapeColorValuePath用于颜色绑定
实现INotifyPropertyChanged的ObservableCollection
MVVM模式实现
绑定问题排查

Visual Elements

视觉元素

📄 Read: references/markers.md

Adding markers to maps
Marker model properties (Label, Latitude, Longitude)
Default marker rendering
MarkerTemplate customization
MarkerTemplateSelector for conditional styling
MarkerIconFill and MarkerLabelForeground
Positioning and alignment

📄 Read: references/bubbles.md

BubbleMarkerSetting configuration
ValuePath for data-driven sizing
MinSize and MaxSize properties
ColorValuePath and ColorMappings
AutoFillColor vs custom Fill
Stroke, StrokeThickness, Opacity
Bubble legends

📄 Read: references/shapes-color-customization.md

Shape color properties
AutoFillColors property
RangeColorMapping for continuous data
EqualsColorMapping for categorical data
Tree map-like visualization
Color palettes and gradients
Custom color logic

📄 Read: references/legends.md

LegendVisibility and positioning
LegendPosition enum values
LegendPositionX and LegendPositionY for custom placement
LegendHeader for titles
LegendType (Layers vs Bubbles)
LegendIcon shapes (Rectangle, Circle, Diamond, Triangle)
LegendColumnSplit for multi-column layout
Custom legend templates

📄 Read: references/map-labels.md

LabelPath for shape labeling
ShapeLabelTemplate customization
Label positioning and visibility
Font styling and formatting
Zoom-based label display

📄 阅读： 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（图层或气泡）
LegendIcon形状（矩形、圆形、菱形、三角形）
LegendColumnSplit用于多列布局
自定义图例模板

📄 阅读： references/map-labels.md

LabelPath用于形状标注
ShapeLabelTemplate自定义
标签定位和可见性
字体样式和格式
基于缩放级别的标签显示

Interactivity

交互性

📄 Read: references/user-interaction.md

ToolTipSettings configuration
EnableZoom and EnablePan properties
MinZoom and MaxZoom constraints
ZoomLevel property
EnableSelection for shape selection
Mouse, touch, and keyboard interactions
Custom tooltip templates
Programmatic zoom and pan

📄 Read: references/events.md

ShapeSelected event
ShapeSelectionChanged event
BubbleMarkerSelected event
MarkerSelected event
ZoomLevelChanged event
Event arguments and data access

📄 阅读： references/user-interaction.md

ToolTipSettings配置
EnableZoom和EnablePan属性
MinZoom和MaxZoom限制
ZoomLevel属性
EnableSelection用于形状选择
鼠标、触摸和键盘交互
自定义工具提示模板
程序化缩放和平移

📄 阅读： references/events.md

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

Advanced Features

高级功能

📄 Read: references/annotations.md

Annotations collection
Text, shape, and image annotations
Coordinate positioning
Custom annotation templates
Visibility and interaction

📄 Read: references/multilayer-support.md

SubShapeFileLayers collection
Adding multiple shape layers
KML file support
KmlItemsTemplate customization
Layer ordering and z-index
Combining vector and imagery layers

📄 阅读： references/annotations.md

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

📄 阅读： references/multilayer-support.md

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

Quick Start Example

快速入门示例

Here's a minimal example to create a map with data binding and color mapping:

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

XAML

xml

<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>

xml

<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

csharp

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 }
        };
    }
}

csharp

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 }
        };
    }
}

Common Patterns

常见模式

Pattern 1: Adding Markers with Custom Templates

模式1：添加带自定义模板的标记

xml

<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>

csharp

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

xml

<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>

csharp

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

Pattern 2: Implementing Tooltips

模式2：实现工具提示

xml

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

xml

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

Pattern 3: Enabling Interactive Zoom and Pan

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

xml

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

xml

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

Pattern 4: Creating Legends

模式4：创建图例

xml

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

xml

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

Key Properties

关键属性

SfMap Properties

SfMap属性

EnableZoom (bool): Enable/disable zooming functionality
EnablePan (bool): Enable/disable panning functionality
MinZoom (double): Minimum zoom level
MaxZoom (double): Maximum zoom level
ZoomLevel (double): Current zoom level
Layers (ObservableCollection<MapLayer>): Collection of map layers

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

ShapeFileLayer Properties

ShapeFileLayer属性

Uri (string): Path to shape file (.shp) as embedded resource
ItemsSource (IEnumerable): Data source for binding
ShapeIDPath (string): Property path in data source for shape matching
ShapeIDTableField (string): Field name in .dbf file for matching
EnableSelection (bool): Enable shape selection
Markers (IEnumerable): Collection of marker objects
LegendVisibility (Visibility): Show/hide legend
LegendPosition (LegendPosition): Standard position for legend
LegendPositionX/Y (double): Custom legend coordinates
LegendHeader (string): Legend title text
LegendIcon (LegendIcons): Icon shape for legend items
LegendType (LegendType): Legend for shapes or bubbles
LegendColumnSplit (int): Number of legend columns
ToolTipSettings (ToolTipSetting): Tooltip configuration

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 Properties

ShapeSetting属性

ShapeFill (Brush): Default fill color for shapes
ShapeStroke (Brush): Border color for shapes
ShapeStrokeThickness (double): Border thickness
ShapeValuePath (string): Property for data values
ShapeColorValuePath (string): Property for color values
SelectedShapeColor (Brush): Fill color for selected shapes
SelectedShapeStroke (Brush): Border color for selected shapes
SelectedShapeStrokeThickness (double): Border thickness for selected shapes
FillSetting (ShapeFillSetting): Color mapping configuration

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

BubbleMarkerSetting Properties

BubbleMarkerSetting属性

ValuePath (string): Property for bubble size values
ColorValuePath (string): Property for bubble colors
MinSize (double): Minimum bubble diameter
MaxSize (double): Maximum bubble diameter
Fill (Brush): Bubble fill color
Stroke (Brush): Bubble border color
StrokeThickness (double): Bubble border thickness
Opacity (double): Bubble transparency (0-1)
AutoFillColor (bool): Enable automatic color assignment
ColorMappings (ObservableCollection): Range/equals color mappings

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

Common Use Cases

常见应用场景

Use Case 1: Population Density Map

场景1：人口密度地图

Display population data with color-coded regions and interactive tooltips showing detailed statistics.

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

Use Case 2: Sales Territory Visualization

场景2：销售区域可视化

Show sales performance across geographical regions with bubbles representing revenue and colors indicating growth rates.

展示不同地理区域的销售业绩，用气泡代表收入，颜色表示增长率。

Use Case 3: Election Results Map

场景3：选举结果地图

Visualize voting results with categorical colors for different candidates and legends for interpretation.

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

Use Case 4: Weather Data Dashboard

场景4：天气数据仪表盘

Display temperature, precipitation, or other weather metrics on maps with real-time data updates.

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

Use Case 5: Store Location Finder

场景5：门店位置查找器

Mark store locations with custom markers and enable zoom/pan for users to explore different areas.

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

Use Case 6: Building Floor Plans

场景6：建筑楼层平面图

Render building layouts using custom shape files with room labeling and occupancy data visualization.

Next Steps: Navigate to the specific reference files above based on your implementation needs. Start with

getting-started.md

for initial setup, then explore other references as needed.

使用自定义形状文件渲染建筑布局，带有房间标注和占用数据可视化。

下一步： 根据你的实现需求，导航至上述特定参考文件。从

getting-started.md

开始进行初始设置，然后根据需要探索其他参考文档。