syncfusion-aspnetcore-maps（同步融合 aspnetcore 映射）

Implementing Syncfusion Maps for ASP.NET Core

The Syncfusion Maps component is a powerful tool for visualizing geographical data using Scalable Vector Graphics (SVG). It supports GeoJSON data, multiple layers, map providers (Bing, Azure, OpenStreetMap), and rich interactive features like zooming, panning, tooltips, and selection.

When to Use This Skill

Use the Syncfusion Maps component when you need to:

• Visualize geographical data - Display country, state, or regional data on interactive maps
• Create choropleth maps - Show data distribution using color mapping across regions
• Plot location markers - Display points of interest, offices, stores, or custom locations
• Render bubble maps - Visualize quantitative data with size-based bubbles on geographical locations
• Integrate map providers - Use Bing Maps, Azure Maps, or OpenStreetMap as base layers
• Show custom shapes - Render custom GeoJSON shapes for specific regions or areas
• Build interactive dashboards - Create zoomable, pannable maps with tooltips and selection
• Display navigation routes - Show navigation lines connecting different locations
• Overlay annotations - Add custom HTML/text annotations on maps
• Create multi-layer visualizations - Combine multiple data layers on a single map

Component Overview

Key Capabilities:

• 📍 Multiple Layers - Support for unlimited layers and sublayers with independent configuration
• 🗺️ GeoJSON Support - Load and render custom geographical shapes
• 🌐 Map Providers - Integration with Bing Maps, Azure Maps, and OpenStreetMap
• 🎨 Color Mapping - Visualize data with equal, range, and desaturation color schemes
• 📌 Markers & Bubbles - Plot locations with customizable markers and size-based bubbles
• 🏷️ Data Labels - Display shape names and data values with smart positioning
• 🎯 Interactivity - Zoom, pan, tooltip, selection, and highlight features
• 📊 Legend - Interactive legends for color mapping, markers, and bubbles
• ✏️ Annotations - Custom HTML overlays at specific coordinates
• 🌍 Projections - Support for 6 map projection types
• 🖨️ Export - Print and export maps to PNG, JPEG, SVG, PDF formats
• ♿ Accessibility - WCAG compliant with keyboard navigation and screen reader support

Documentation and Navigation Guide

Getting Started and Installation

📄 Read: references/getting-started.md

When user needs to:

• Set up the Maps component for the first time
• Install NuGet packages and configure dependencies
• Add tag helpers and script references
• Create a basic map with GeoJSON data
• Understand the minimal setup requirements

Layers and GeoJSON Data

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

When user needs to:

• Understand map layer architecture
• Work with GeoJSON format and custom shapes
• Add multiple layers or sublayers
• Load GeoJSON from files or URLs
• Configure layer visibility and ordering
• Handle layer-specific settings

Data Binding and Population

📄 Read: references/data-binding.md

When user needs to:

• Bind data source to map shapes
• Configure ShapeDataPath and ShapePropertyPath
• Match data records to geographical shapes
• Bind data from JSON, databases, or APIs
• Update data dynamically
• Transform data for visualization

Markers

📄 Read: references/markers.md

When user needs to:

• Add location markers to maps
• Use different marker types (Circle, Image, Letter, Template)
• Customize marker appearance (size, color, borders)
• Position markers using latitude/longitude
• Add marker tooltips and events
• Implement marker clustering
• Create custom marker templates

Bubbles

📄 Read: references/bubbles.md

When user needs to:

• Create bubble visualizations on maps
• Size bubbles based on data values
• Configure bubble colors and opacity
• Set minimum and maximum bubble radius
• Add bubble tooltips
• Implement multiple bubble sets
• Handle bubble selection

Data Labels

📄 Read: references/data-labels.md

When user needs to:

• Display labels on map shapes
• Configure label positioning and alignment
• Use smart label modes (Trim, Hide, None)
• Customize label fonts and styling
• Create template-based labels
• Handle label intersections
• Add labels to markers and bubbles

Color Mapping

📄 Read: references/color-mapping.md

When user needs to:

• Apply colors to shapes based on data
• Configure equal color mapping (value-to-color)
• Set up range color mapping (min-max ranges)
• Use desaturation color mapping (gradient opacity)
• Create choropleth maps
• Define custom color palettes
• Handle accessibility and contrast

Legend

📄 Read: references/legend.md

When user needs to:

• Add legend to maps
• Configure legend positioning and alignment
• Enable interactive legend (toggle, highlight)
• Customize legend shapes and text
• Create legends for color mapping
• Add legends for markers and bubbles
• Implement legend paging for many items

Annotations

📄 Read: references/annotations.md

When user needs to:

• Add custom HTML content to maps
• Position annotations at specific coordinates
• Create text or template-based annotations
• Style and align annotations
• Handle annotation z-index and layering
• Add dynamic annotations
• Create responsive annotations

User Interactions

📄 Read: references/user-interactions.md

When user needs to:

• Enable zooming (mouse wheel, pinch, toolbar)
• Configure panning features
• Add tooltips with custom templates
• Implement shape selection and multi-selection
• Enable highlight on hover
• Handle click events
• Add navigation lines between locations
• Set zoom levels and constraints

Map Providers Integration

📄 Read: references/map-providers.md

When user needs to:

• Integrate Bing Maps (Road, Aerial, Hybrid)
• Set up Azure Maps with API keys
• Use OpenStreetMap (OSM) tiles
• Configure custom tile servers
• Combine providers with GeoJSON layers
• Handle provider authentication
• Compare provider features and limitations

Advanced Features

When user needs to:

• Render polygons with custom data
• Add navigation lines with arrows
• Print or export maps to images/PDF
• Implement internationalization (i18n)
• Configure localization (l10n)
• Enable accessibility features
• Implement state persistence
• Use programmatic methods
• Optimize performance
• Migrate from EJ1 to EJ2

Quick Start Example

Basic Map with GeoJSON and Color Mapping

@using Newtonsoft.Json
@using Syncfusion.EJ2.Maps

@{
    // Load GeoJSON data
    string geoJson = System.IO.File.ReadAllText("wwwroot/scripts/MapsData/WorldMap.json");
    var worldMapData = JsonConvert.DeserializeObject(geoJson);

    // Load data source
    string dataJson = System.IO.File.ReadAllText("wwwroot/scripts/MapsData/population.json");
    var populationData = JsonConvert.DeserializeObject(dataJson);

    // Define color mapping
    var colorMapping = new List<MapsColorMapping> {
        new MapsColorMapping { From = 0, To = 100000000, Color = "#C6E7F0", Label = "< 100M" },
        new MapsColorMapping { From = 100000000, To = 500000000, Color = "#6AB7D6", Label = "100M - 500M" },
        new MapsColorMapping { From = 500000000, To = 1500000000, Color = "#1A7FA0", Label = "> 500M" }
    };

    var propertyPath = new[] { "name" };
}

<ejs-maps id="maps" height="600px">
    <e-maps-titlesettings text="World Population by Country">
        <e-maps-titlesettings-textstyle size="16px" fontWeight="500"></e-maps-titlesettings-textstyle>
    </e-maps-titlesettings>

    <e-maps-legendsettings visible="true" position="Bottom"></e-maps-legendsettings>

    <e-maps-layers>
        <e-maps-layer shapeData="worldMapData"
                      dataSource="populationData"
                      shapeDataPath="Country"
                      shapePropertyPath="propertyPath">
            <e-layersettings-shapesettings
                fill="#E5E5E5"
                colorValuePath="Population"
                colorMapping="colorMapping">
            </e-layersettings-shapesettings>

            <e-layersettings-tooltipsettings visible="true" valuePath="Country">
                <e-tooltipsettings-template>
                    <div style="padding: 8px;">
                        <strong>${Country}</strong><br/>
                        Population: ${Population}
                    </div>
                </e-tooltipsettings-template>
            </e-layersettings-tooltipsettings>
        </e-maps-layer>
    </e-maps-layers>
</ejs-maps>

Map with Markers

@using Newtonsoft.Json
@using Syncfusion.EJ2.Maps

@{
    var worldMapData = JsonConvert.DeserializeObject(System.IO.File.ReadAllText("wwwroot/scripts/MapsData/WorldMap.json"));

    var cities = new[]
    {
        new { Name = "New York", Latitude = 40.7128, Longitude = -74.0060, Population = "8.4M" },
        new { Name = "Tokyo", Latitude = 35.6762, Longitude = 139.6503, Population = "13.9M" },
        new { Name = "London", Latitude = 51.5074, Longitude = -0.1278, Population = "9.0M" },
        new { Name = "Sydney", Latitude = -33.8688, Longitude = 151.2093, Population = "5.3M" }
    };
}

<ejs-maps id="maps" height="600px">
    <e-maps-zoomsettings enable="true" zoomFactor="2"></e-maps-zoomsettings>

    <e-maps-layers>
        <e-maps-layer shapeData="worldMapData">
            <e-layersettings-shapesettings fill="#C3E6ED"></e-layersettings-shapesettings>

            <e-layersettings-markersettings>
                <e-layersettings-markersetting
                    visible="true"
                    dataSource="cities"
                    shape="Circle"
                    fill="#FF6347"
                    height="15"
                    width="15">
                    <e-layersettings-markersetting-tooltipsettings
                        visible="true"
                        valuePath="Name">
                        <e-markersetting-tooltipsettings-template>
                            <div style="padding: 8px;">
                                <strong>${Name}</strong><br/>
                                Population: ${Population}
                            </div>
                        </e-markersetting-tooltipsettings-template>
                    </e-layersettings-markersetting-tooltipsettings>
                </e-layersettings-markersetting>
            </e-layersettings-markersettings>
        </e-maps-layer>
    </e-maps-layers>
</ejs-maps>

API Reference

Maps Class

The primary Maps component class with properties, methods, and events for controlling map behavior and appearance.

Namespace: Syncfusion.EJ2.Maps Assembly: Syncfusion.EJ2.dll Official API Reference

Core Properties (63 total)

Maps Events (28 total)

MapsLayer Class

Defines the configuration for individual map layers supporting geometry data, map providers, and data binding.

Official API Reference

Key Properties

MapsZoomSettings Class

Manages map zoom and pan behavior.

Official API Reference

Key Properties

MapsShapeSettings Class

Configures appearance and behavior of shapes in the map.

Official API Reference

Key Properties

MapsMarker Class

Defines markers to be displayed on the map at specified coordinates.

Official API Reference

Key Properties

Related Classes (40+ classes available)

Enumerations

ProjectionType

Defines supported map projections.

MarkerType

Defines available marker shapes.

MapsTheme

Defines available themes.

TooltipGesture

Defines tooltip display modes.

LegendType

Defines legend types.

Common Patterns

Pattern 1: Choropleth Map with Data Binding

Use Case: Visualize statistical data across regions with color-coded shapes.

@{
    var colorMapping = new List<MapsColorMapping> {
        new MapsColorMapping { Value = "Low", Color = "#90EE90" },
        new MapsColorMapping { Value = "Medium", Color = "#FFD700" },
        new MapsColorMapping { Value = "High", Color = "#FF6347" }
    };
}

<e-maps-layer shapeData="@geoJsonData"
              dataSource="@statisticsData"
              shapeDataPath="RegionName"
              shapePropertyPath="@(new[] { "name" })">
    <e-layersettings-shapesettings
        colorValuePath="DataLevel"
        colorMapping="colorMapping">
    </e-layersettings-shapesettings>
</e-maps-layer>

Pattern 2: Interactive Map with Zoom and Selection

Use Case: Enable user interaction for detailed exploration.

<ejs-maps id="maps">
    <e-maps-zoomsettings
        enable="true"
        enableSelectionZooming="true"
        toolbars='new string[] {"Zoom", "ZoomIn", "ZoomOut", "Pan", "Reset"}'>
    </e-maps-zoomsettings>

    <e-maps-layers>
        <e-maps-layer shapeData="@mapData">
            <e-layersettings-selectionsettings
                enable="true"
                fill="#8B0000"
                opacity="0.5">
            </e-layersettings-selectionsettings>

            <e-layersettings-highlightsettings
                enable="true"
                fill="#FF6347">
            </e-layersettings-highlightsettings>
        </e-maps-layer>
    </e-maps-layers>
</ejs-maps>

Pattern 3: Multiple Data Layers

Use Case: Overlay multiple data sets on a single map.

<e-maps-layers>
    <!-- Base layer: Country boundaries -->
    <e-maps-layer shapeData="@countryData" type="Layer">
        <e-layersettings-shapesettings fill="#E5E5E5"></e-layersettings-shapesettings>
    </e-maps-layer>

    <!-- Sublayer: State boundaries -->
    <e-maps-layer shapeData="@stateData" type="SubLayer">
        <e-layersettings-shapesettings fill="transparent" border-width="1"></e-layersettings-shapesettings>
    </e-maps-layer>

    <!-- Data layer: Markers -->
    <e-maps-layer type="Layer">
        <e-layersettings-markersettings>
            <e-layersettings-markersetting dataSource="@locations" shape="Circle"></e-layersettings-markersetting>
        </e-layersettings-markersettings>
    </e-maps-layer>
</e-maps-layers>

Pattern 4: Bing Maps Integration

Use Case: Use Bing Maps as base layer with custom data overlay.

<ejs-maps id="maps">
    <e-maps-layers>
        <!-- Bing Maps base layer -->
        <e-maps-layer layerType="Bing" bingMapType="Aerial" key="YOUR_BING_MAPS_KEY">
        </e-maps-layer>

        <!-- Data overlay layer -->
        <e-maps-layer type="SubLayer" shapeData="@customData">
            <e-layersettings-shapesettings fill="#FF6347" opacity="0.5"></e-layersettings-shapesettings>
        </e-maps-layer>
    </e-maps-layers>
</ejs-maps>

Key Properties Reference

Essential Properties

Layer Configuration

Interaction Settings

Common Use Cases

Use Case 1: Sales Dashboard by Region

Create a choropleth map showing sales performance across different regions with color-coded intensity.

Applies: Color mapping, data binding, legend, tooltips

Use Case 2: Store Locator

Display retail store locations on a map with custom markers, allowing users to zoom and click for details.

Applies: Markers, tooltips, zooming, Bing/OSM integration

Use Case 3: Population Density Visualization

Show population density using bubble sizes, with larger bubbles representing higher populations.

Applies: Bubbles, data binding, legend, color mapping

Use Case 4: Election Results Map

Visualize election results by state/region with color coding and interactive selection.

Applies: Color mapping, selection, highlight, data labels, legend

Use Case 5: Shipping Routes Visualization

Display shipping routes between cities using navigation lines with directional arrows.

Applies: Navigation lines, markers, annotations, layers

Use Case 6: Weather Map Dashboard

Overlay weather data on maps with custom annotations and real-time data updates.

Applies: Annotations, dynamic data, multiple layers, map providers

Use Case 7: Real Estate Property Map

Show property listings with custom markers, filtering, and detailed tooltips.

Applies: Markers, custom templates, tooltips, zooming, panning

Related Components

• Chart - For non-geographical data visualization
• HeatMap - For matrix-based heat map visualization
• TreeMap - For hierarchical data visualization
• Diagram - For network and flowchart visualization

Additional Resources

• Syncfusion Maps Documentation
• API Reference
• GeoJSON Format Specification
• Sample GeoJSON Data