syncfusion-blazor-maps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Maps for Blazor

为Blazor实现Syncfusion Maps组件

A comprehensive guide to implementing Syncfusion Maps component in Blazor applications. Syncfusion Maps provides powerful spatial visualization capabilities including marker management, polygon overlays, layer support, event handling, and integration with multiple map providers.

本文是在Blazor应用中实现Syncfusion Maps组件的综合指南。Syncfusion Maps提供强大的空间可视化功能，包括标记管理、多边形叠加、图层支持、事件处理以及与多个地图提供商的集成。

When to Use This Skill

何时使用此技能

Use Syncfusion Maps when you need to:

Display geographic data on interactive maps
Visualize data across regions using color mapping (choropleth)
Add markers, polygons, and annotations to maps
Handle user interactions (click, hover, zoom, pan)
Support multiple map providers (Google, Bing, Azure, OpenStreetMap)
Export or print maps with custom legends and labels
Build location-aware applications
Create multi-layer spatial visualizations

当你需要以下功能时，可使用Syncfusion Maps：

在交互式地图上展示地理数据
使用颜色映射（分级统计图）跨区域可视化数据
在地图上添加标记、多边形和注释
处理用户交互（点击、悬停、缩放、平移）
支持多种地图提供商（Google、Bing、Azure、OpenStreetMap）
导出或打印带有自定义图例和标签的地图
构建位置感知型应用
创建多层空间可视化

Component Overview

组件概述

Syncfusion Maps is a powerful geospatial visualization component that enables you to:

Render interactive maps with multiple provider options
Bind and visualize geographic datasets
Support rich spatial features (markers, polygons, layers, annotations)
Handle complex user interactions and events
Customize appearance through themes and styling
Enable localization and accessibility features
Export maps for reporting and sharing

Syncfusion Maps是一款功能强大的地理空间可视化组件，可让你：

渲染支持多种提供商选项的交互式地图
绑定并可视化地理数据集
支持丰富的空间功能（标记、多边形、图层、注释）
处理复杂的用户交互和事件
通过主题和样式自定义外观
启用本地化和无障碍功能
导出地图用于报告和分享

Documentation and Navigation Guide

文档与导航指南

Choose the reference guide that matches your current task:

选择与当前任务匹配的参考指南：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Basic map initialization and rendering
CSS imports and theme configuration
Creating your first interactive map
Step-by-step setup walkthrough

📄 阅读： references/getting-started.md

安装与NuGet包设置
基础地图初始化与渲染
CSS导入与主题配置
创建你的第一个交互式地图
分步设置教程

Map Providers and Configuration

地图提供商与配置

📄 Read: references/map-providers.md

Google Maps setup and API key configuration
Bing Maps setup and authentication
Azure Maps provider configuration
OpenStreetMap setup
Provider comparison and selection guide

📄 阅读： references/map-providers.md

Google Maps设置与API密钥配置
Bing Maps设置与身份验证
Azure Maps提供商配置
OpenStreetMap设置
提供商对比与选择指南

Markers and Layers

标记与图层

📄 Read: references/markers-and-layers.md

Adding and managing markers
Marker clustering and grouping
Working with layers and layer collections
Toggling layer visibility
Dynamic marker updates and data binding

📄 阅读： references/markers-and-layers.md

添加与管理标记
标记聚类与分组
图层与图层集合的使用
切换图层可见性
动态标记更新与数据绑定

Spatial Features and Overlays

空间功能与叠加层

📄 Read: references/spatial-features.md

Drawing polygons and geographic shapes
Creating navigation lines and polylines
Adding annotations with text, icons, and circles
Creating data bubbles and interactive overlays
Advanced spatial geometry features

📄 阅读： references/spatial-features.md

绘制多边形与地理形状
创建导航线与折线
添加包含文本、图标和圆形的注释
创建数据气泡与交互式叠加层
高级空间几何功能

Data Visualization and Mapping

数据可视化与映射

📄 Read: references/data-visualization.md

Color mapping and choropleth visualization
Configuring legends and legend placement
Data labels on map elements
Populating maps with geographic datasets
Advanced data binding and visualization patterns

📄 阅读： references/data-visualization.md

颜色映射与分级统计图可视化
配置图例与图例位置
地图元素上的数据标签
用地理数据集填充地图
高级数据绑定与可视化模式

User Interactions

用户交互

📄 Read: references/user-interactions.md

Handling mouse clicks and double-clicks
Zoom and pan control configuration
Tooltip and popup behavior
Keyboard navigation support
Custom interaction patterns

📄 阅读： references/user-interactions.md

处理鼠标点击与双击
缩放和平移控件配置
工具提示与弹出窗口行为
键盘导航支持
自定义交互模式

Events and Methods

事件与方法

📄 Read: references/events-and-methods.md

Mouse event handling (click, hover, move)
Pan and zoom event capture
Programmatic map methods (pan, zoom, reset, refresh)
Event data and callback patterns
Triggering actions from user interactions

📄 阅读： references/events-and-methods.md

鼠标事件处理（点击、悬停、移动）
平移与缩放事件捕获
程序化地图方法（平移、缩放、重置、刷新）
事件数据与回调模式
从用户交互触发操作

Customization and Styling

自定义与样式

📄 Read: references/customization-and-styling.md

CSS class customization
Theme Studio integration
Marker and popup styling
Map controls and navigation styling
Dark mode and responsive design

📄 阅读： references/customization-and-styling.md

CSS类自定义
Theme Studio集成
标记与弹出窗口样式
地图控件与导航样式
深色模式与响应式设计

Print and Export

打印与导出

📄 Read: references/print-and-export.md

Exporting maps as PNG, SVG, and PDF
Print functionality and page setup
Exporting with legends and data labels
File format considerations
Server-side and client-side export options

📄 阅读： references/print-and-export.md

将地图导出为PNG、SVG和PDF格式
打印功能与页面设置
导出包含图例和数据标签的地图
文件格式注意事项
服务端与客户端导出选项

Internationalization and Localization

国际化与本地化

📄 Read: references/internationalization-and-localization.md

Multi-language support for map labels
Right-to-left (RTL) text support
Localized number and date formatting
Regional map variations
Language-specific customization

📄 阅读： references/internationalization-and-localization.md

地图标签的多语言支持
从右到左（RTL）文本支持
本地化数字与日期格式
区域地图变体
特定语言的自定义

State Persistence

状态持久化

📄 Read: references/state-persistence.md

Saving and restoring map state
Persisting zoom level and center position
Preserving user interaction state
Session and local storage integration
State management patterns

📄 阅读： references/state-persistence.md

保存与恢复地图状态
持久化缩放级别与中心位置
保留用户交互状态
会话与本地存储集成
状态管理模式

Accessibility and Advanced Topics

无障碍与高级主题

📄 Read: references/accessibility.md

WCAG 2.1 compliance and standards
Keyboard navigation and shortcuts
ARIA attributes and semantic markup
Screen reader support
High contrast mode support
Assistive technology compatibility

📄 阅读： references/accessibility.md

WCAG 2.1合规性与标准
键盘导航与快捷键
ARIA属性与语义化标记
屏幕阅读器支持
高对比度模式支持
辅助技术兼容性

Complete API Reference

完整API参考

📄 Read: references/api-reference.md

```
SfMaps
```
main component properties and methods

Configuration classes (

MapsCenterPosition

MapsZoomSettings

MapsLegendSettings

, etc.)

Event arguments for all event types
Interfaces (
```
ILayer
```
,
```
IMarker
```
,
```
IBubble
```
)

Enumerations for

MarkerType

ExportType

ProjectionType

GeometryType

, etc.

Properties quick reference guide
Complete class hierarchy and API surface

📄 阅读： references/api-reference.md

```
SfMaps
```
主组件的属性与方法

配置类（

MapsCenterPosition

、

MapsZoomSettings

、

MapsLegendSettings

等）

所有事件类型的事件参数
接口（
```
ILayer
```
、
```
IMarker
```
、
```
IBubble
```
）

枚举类型（

MarkerType

、

ExportType

、

ProjectionType

、

GeometryType

等）

属性快速参考指南
完整类层次结构与API范围

Quick Start Example

快速入门示例

csharp

// Basic map setup in Blazor
@page "/maps-demo"
@using Syncfusion.Blazor.Maps

<SfMaps>
    <MapsLayers>
        <MapsLayer UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    // Additional configuration as needed
}

csharp

// Basic map setup in Blazor
@page "/maps-demo"
@using Syncfusion.Blazor.Maps

<SfMaps>
    <MapsLayers>
        <MapsLayer UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    // Additional configuration as needed
}

Common Patterns

常见模式

Pattern 1: Adding Markers to a Map

模式1：为地图添加标记

csharp

<SfMaps>
    <MapsLayers>
        <MapsLayer TValue="MarkerData" UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
            <MapsMarkerSettings>
                <MapsMarker TValue="MarkerData" Latitude="37.368" Longitude="-122.095" 
                    Width="15" Height="15">
                </MapsMarker>
            </MapsMarkerSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    public class MarkerData
    {
        public double Latitude { get; set; }
        public double Longitude { get; set; }
    }
}

csharp

<SfMaps>
    <MapsLayers>
        <MapsLayer TValue="MarkerData" UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
            <MapsMarkerSettings>
                <MapsMarker TValue="MarkerData" Latitude="37.368" Longitude="-122.095" 
                    Width="15" Height="15">
                </MapsMarker>
            </MapsMarkerSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    public class MarkerData
    {
        public double Latitude { get; set; }
        public double Longitude { get; set; }
    }
}

Pattern 2: Binding Data with Color Mapping

模式2：绑定数据与颜色映射

csharp

<SfMaps>
    <MapsLayers>
        <MapsLayer ShapeDataSource="@ShapeData" 
                   ShapePropertyPath="@ShapePropertyPath"
                   DataSource="@DataSource" TValue="DataType">
            <MapsShapeSettings ColorValuePath="Population">
                <MapsShapeColorMappings>
                    <MapsShapeColorMapping From="0" To="50000" Color="#B3E5FC"></MapsShapeColorMapping>
                    <MapsShapeColorMapping From="50000" To="100000" Color="#81D4FA"></MapsShapeColorMapping>
                </MapsShapeColorMappings>
            </MapsShapeSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

csharp

<SfMaps>
    <MapsLayers>
        <MapsLayer ShapeDataSource="@ShapeData" 
                   ShapePropertyPath="@ShapePropertyPath"
                   DataSource="@DataSource" TValue="DataType">
            <MapsShapeSettings ColorValuePath="Population">
                <MapsShapeColorMappings>
                    <MapsShapeColorMapping From="0" To="50000" Color="#B3E5FC"></MapsShapeColorMapping>
                    <MapsShapeColorMapping From="50000" To="100000" Color="#81D4FA"></MapsShapeColorMapping>
                </MapsShapeColorMappings>
            </MapsShapeSettings>
        </MapsLayer>
    </MapsLayers>
</SfMaps>

Pattern 3: Handling Map Click Events

模式3：处理地图点击事件

csharp

<SfMaps @ref="mapInstance" OnShapeSelected="ShapeSelected" 
        OnMarkerClick="MarkerClicked">
    <MapsLayers>
        <MapsLayer UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    private SfMaps mapInstance;

    private void MarkerClicked(MarkerClickEventArgs args)
    {
        Console.WriteLine($"Marker clicked at: {args.Latitude}, {args.Longitude}");
    }

    private void ShapeSelected(ShapeSelectedEventArgs args)
    {
        Console.WriteLine($"Shape selected: {args.Data}");
    }
}

csharp

<SfMaps @ref="mapInstance" OnShapeSelected="ShapeSelected" 
        OnMarkerClick="MarkerClicked">
    <MapsLayers>
        <MapsLayer UrlTemplate="https://tile.openstreetmap.org/level/tileX/tileY.png">
        </MapsLayer>
    </MapsLayers>
</SfMaps>

@code {
    private SfMaps mapInstance;

    private void MarkerClicked(MarkerClickEventArgs args)
    {
        Console.WriteLine($"Marker clicked at: {args.Latitude}, {args.Longitude}");
    }

    private void ShapeSelected(ShapeSelectedEventArgs args)
    {
        Console.WriteLine($"Shape selected: {args.Data}");
    }
}

Key Features Summary

核心功能总结

Multiple Map Providers: Support for Google Maps, Bing Maps, Azure Maps, and OpenStreetMap
Rich Geospatial Features: Markers, polygons, polylines, annotations, and bubbles
Data Visualization: Color mapping, choropleth support, legends, and data labels
Interactivity: Click handling, hover tooltips, zoom/pan controls, keyboard navigation
Layer Management: Multi-layer support with visibility toggling and dynamic updates
Export Capabilities: PNG, SVG, and PDF export with legends and labels
Internationalization: Multi-language support and RTL text rendering
Accessibility: WCAG compliance with keyboard navigation and screen reader support
Customization: Theme Studio integration, CSS customization, marker styling
Performance: Optimized rendering for large datasets and marker clustering

多地图提供商： 支持Google Maps、Bing Maps、Azure Maps和OpenStreetMap
丰富的地理空间功能： 标记、多边形、折线、注释和气泡
数据可视化： 颜色映射、分级统计图支持、图例和数据标签
交互性： 点击处理、悬停工具提示、缩放/平移控件、键盘导航
图层管理： 多层支持，包含可见性切换与动态更新
导出功能： 导出为PNG、SVG和PDF格式，包含图例和标签
国际化： 多语言支持与RTL文本渲染
无障碍： 符合WCAG标准，支持键盘导航与屏幕阅读器
自定义： Theme Studio集成、CSS自定义、标记样式
性能： 针对大型数据集和标记聚类优化的渲染