syncfusion-react-maps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion React Maps

实现Syncfusion React Maps

A comprehensive skill for implementing the Syncfusion React Maps component to visualize geographical data with rich interactivity, multiple layers, markers, bubbles, legends, and map provider integration.
本技能全面介绍如何实现Syncfusion React Maps组件,以具备丰富交互性、多层级结构、标记、气泡、图例和地图提供商集成的方式可视化地理数据。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Display geographical data on interactive maps
  • Visualize location-based information with markers, bubbles, or data labels
  • Create choropleth maps with color-coded regions based on data values
  • Integrate map providers like Bing Maps, OpenStreetMap, or Azure Maps
  • Render custom shapes from GeoJSON data files
  • Build multi-layer maps with overlays and sublayers
  • Add navigation lines to show routes or connections between locations
  • Implement zooming and panning for map exploration
  • Display statistical data on geographical regions
  • Create interactive legends for data interpretation
  • Support multiple projections (Mercator, Miller, Eckert, etc.)
  • Handle user interactions like tooltips, selection, and highlighting
在以下场景中使用本技能:
  • 在交互式地图上展示地理数据
  • 使用标记、气泡或数据标签可视化基于位置的信息
  • 根据数据值创建带有颜色编码区域的分级统计图
  • 集成Bing Maps、OpenStreetMap或Azure Maps等地图提供商
  • 从GeoJSON数据文件渲染自定义形状
  • 构建带有覆盖层和子图层的多层级地图
  • 添加导航线以显示地点之间的路线或连接
  • 实现缩放和平移功能以探索地图
  • 在地理区域上展示统计数据
  • 创建用于数据解读的交互式图例
  • 支持多种投影方式(墨卡托、米勒、埃克特等)
  • 处理提示框、选择和高亮等用户交互

Component Overview

组件概述

The Syncfusion React Maps component is a powerful data visualization tool that renders geographical data using Scalable Vector Graphics (SVG). It supports:
  • Any number of layers and sublayers for complex visualizations
  • GeoJSON data binding for custom shape rendering
  • Map providers (Bing, OpenStreetMap, Azure) as base layers
  • 6 types of projections for different map representations
  • Visual elements: Markers, Bubbles, Navigation Lines, Annotations, Data Labels, Legends
  • Interactive features: Zooming, Panning, Tooltips, Selection, Highlighting
  • Accessibility: WCAG 2.1 compliant with keyboard navigation
  • Globalization: RTL support, internationalization, localization
Syncfusion React Maps组件是一款强大的数据可视化工具,使用可缩放矢量图形(SVG)渲染地理数据。它支持:
  • 任意数量的图层和子图层,用于复杂可视化
  • GeoJSON数据绑定,用于自定义形状渲染
  • 地图提供商(Bing、OpenStreetMap、Azure)作为基础图层
  • 6种投影方式,用于不同的地图呈现
  • 视觉元素:标记、气泡、导航线、注释、数据标签、图例
  • 交互功能:缩放、平移、提示框、选择、高亮
  • 无障碍性:符合WCAG 2.1标准,支持键盘导航
  • 全球化:支持RTL、国际化、本地化

Key Capabilities

核心功能

Data Visualization Elements

数据可视化元素

  • Markers: Pin locations with custom shapes, templates, and clustering
  • Bubbles: Display data magnitude with size-based bubbles
  • Data Labels: Show information directly on map shapes
  • Color Mapping: Apply colors based on data values (equal, range, desaturation)
  • Navigation Lines: Draw connections between locations with curves and arrows
  • Legends: Provide visual keys for data interpretation
  • 标记:使用自定义形状、模板和聚类功能标记位置
  • 气泡:基于大小展示数据量级
  • 数据标签:在地图形状上直接显示信息
  • 颜色映射:根据数据值应用颜色(等值、范围、饱和度调整)
  • 导航线:使用曲线和箭头绘制地点之间的连接
  • 图例:提供用于数据解读的视觉索引

Layer Architecture

图层架构

  • Main Layer: Base map from GeoJSON or map provider
  • Sublayers: Overlay additional shapes on top of main layer
  • Multi-layer Support: Stack multiple layers for rich visualizations
  • 主图层:来自GeoJSON或地图提供商的基础地图
  • 子图层:在主图层上叠加额外形状
  • 多层级支持:堆叠多个图层以实现丰富的可视化效果

Map Providers

地图提供商

  • Bing Maps: Satellite, aerial, and road views
  • OpenStreetMap: Free tile layer provider
  • Azure Maps: Microsoft's map service
  • Hybrid Approach: Combine GeoJSON shapes with provider tiles
  • Bing Maps:卫星图、航拍图和道路视图
  • OpenStreetMap:免费切片图层提供商
  • Azure Maps:微软的地图服务
  • 混合方式:将GeoJSON形状与提供商切片图层结合

User Interactions

用户交互

  • Zooming: Mouse wheel, double-click, pinch, toolbar controls
  • Panning: Drag to explore different regions
  • Tooltips: Show data on hover
  • Selection: Highlight shapes on click
  • Reset: Return to initial view
  • 缩放:鼠标滚轮、双击、捏合、工具栏控件
  • 平移:拖动以探索不同区域
  • 提示框:悬停时显示数据
  • 选择:点击高亮形状
  • 重置:返回初始视图

Documentation and Navigation Guide

文档与导航指南

API Reference

API参考

📄 Read: references/api-reference.md
  • Complete MapsComponent properties reference
  • All available methods with examples
  • Comprehensive events documentation
  • Layer, marker, bubble, and data label settings
  • Legend, zoom, and tooltip configuration
  • Quick reference code examples
  • Type definitions and parameters
📄 阅读: references/api-reference.md
  • 完整的MapsComponent属性参考
  • 所有可用方法及示例
  • 全面的事件文档
  • 图层、标记、气泡和数据标签设置
  • 图例、缩放和提示框配置
  • 快速参考代码示例
  • 类型定义和参数

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and package dependencies
  • Basic Maps component implementation
  • GeoJSON data structure and binding
  • CSS theme imports
  • Module injection pattern (feature-based)
  • First world map example
  • Data source binding with shapeDataPath and shapePropertyPath
📄 阅读: references/getting-started.md
  • 安装和包依赖
  • 基础Maps组件实现
  • GeoJSON数据结构与绑定
  • CSS主题导入
  • 模块注入模式(基于功能)
  • 第一个世界地图示例
  • 使用shapeDataPath和shapePropertyPath绑定数据源

Layers and Structure

图层与结构

📄 Read: references/layers-and-sublayers.md
  • Understanding layer architecture
  • Main layer vs sublayer differences
  • Creating multi-layer maps
  • Layer types and stacking order
  • Layer-specific settings and configuration
  • When to use multiple layers
📄 阅读: references/layers-and-sublayers.md
  • 理解图层架构
  • 主图层与子图层的区别
  • 创建多层级地图
  • 图层类型和堆叠顺序
  • 图层特定设置与配置
  • 何时使用多个图层

Markers

标记

📄 Read: references/markers.md
  • Adding markers to pinpoint locations
  • Marker data source structure (latitude, longitude)
  • Marker shapes and custom templates
  • Marker clustering for dense data
  • Dynamic marker updates
  • Interactive markers with click events
  • Marker tooltips and labels
📄 阅读: references/markers.md
  • 添加标记以精确定位
  • 标记数据源结构(纬度、经度)
  • 标记形状和自定义模板
  • 密集数据的标记聚类
  • 动态标记更新
  • 带点击事件的交互式标记
  • 标记提示框和标签

Data Visualization Elements

数据可视化元素

📄 Read: references/data-visualization.md
  • Bubble visualization for data magnitude
  • Configuring bubble size and colors
  • Data label setup and formatting
  • Smart label modes (trim, hide, none)
  • Label templates for custom content
  • Combining bubbles with data labels
  • Best practices for visual hierarchy
📄 阅读: references/data-visualization.md
  • 用于展示数据量级的气泡可视化
  • 配置气泡大小和颜色
  • 数据标签设置与格式化
  • 智能标签模式(截断、隐藏、无)
  • 用于自定义内容的标签模板
  • 气泡与数据标签的结合
  • 视觉层次结构最佳实践

Legend

图例

📄 Read: references/legend.md
  • Enabling and configuring legends
  • Positioning strategies (absolute, dock)
  • Legend alignment options (near, center, far)
  • Interactive legends
  • Legend modes (default, interactive)
  • Customizing legend appearance
  • Syncing legends with color mapping
📄 阅读: references/legend.md
  • 启用和配置图例
  • 定位策略(绝对、停靠)
  • 图例对齐选项(近、中、远)
  • 交互式图例
  • 图例模式(默认、交互式)
  • 自定义图例外观
  • 图例与颜色映射同步

Color Mapping

颜色映射

📄 Read: references/color-mapping.md
  • Color mapping types (equal, range, desaturation)
  • Applying colors based on data values
  • Setting up colorValuePath
  • Creating choropleth maps
  • Multiple color mapping rules
  • Custom color schemes
  • Visual data representation strategies
📄 阅读: references/color-mapping.md
  • 颜色映射类型(等值、范围、饱和度调整)
  • 根据数据值应用颜色
  • 设置colorValuePath
  • 创建分级统计图
  • 多组颜色映射规则
  • 自定义配色方案
  • 视觉数据呈现策略

Navigation Lines

导航线

📄 Read: references/navigation-lines.md
  • Creating lines between locations
  • Line styling (width, color, dash array)
  • Curved lines and angles
  • Arrow indicators for direction
  • Use cases (routes, connections, flows)
  • Animation effects on lines
📄 阅读: references/navigation-lines.md
  • 创建地点之间的连线
  • 线条样式(宽度、颜色、虚线数组)
  • 曲线和角度
  • 方向箭头指示器
  • 使用场景(路线、连接、流动)
  • 线条动画效果

Map Providers

地图提供商

📄 Read: references/map-providers.md
  • Overview of supported providers
  • When to use GeoJSON vs map providers
  • Bing Maps setup and API keys
  • OpenStreetMap integration (free)
  • Azure Maps configuration
  • Tile layer types (satellite, aerial, road)
  • Hybrid approaches (GeoJSON overlays on provider tiles)
📄 阅读: references/map-providers.md
  • 支持的提供商概述
  • 何时使用GeoJSON vs 地图提供商
  • Bing Maps设置和API密钥
  • OpenStreetMap集成(免费)
  • Azure Maps配置
  • 切片图层类型(卫星、航拍、道路)
  • 混合方式(在提供商切片图层上叠加GeoJSON)

User Interactions

用户交互

📄 Read: references/user-interactions.md
  • Enabling and configuring zooming
  • Zoom factor and toolbar controls
  • Panning functionality
  • Tooltip configuration and templates
  • Selection and highlighting shapes
  • Mouse wheel and double-click zoom
  • Pinch zoom for touch devices
  • Reset to initial view
📄 阅读: references/user-interactions.md
  • 启用和配置缩放
  • 缩放因子和工具栏控件
  • 平移功能
  • 提示框配置和模板
  • 形状选择与高亮
  • 鼠标滚轮和双击缩放
  • 触摸设备的捏合缩放
  • 重置到初始视图

Annotations and Polygons

注释与多边形

📄 Read: references/annotations-polygon.md
  • Adding custom annotations to maps
  • Polygon rendering for custom shapes
  • Positioning and alignment
  • Interactive annotations
  • Use cases for overlays
📄 阅读: references/annotations-polygon.md
  • 向地图添加自定义注释
  • 渲染自定义形状的多边形
  • 定位与对齐
  • 交互式注释
  • 覆盖层使用场景

Customization

自定义

  • Map projections (Mercator, Miller, Eckert, Winkel Tripel, Aitoff, Equirectangular)
  • Title and subtitle configuration
  • Border and background styling
  • Margin and padding adjustments
  • Custom CSS classes
  • Theme integration
  • Responsive design patterns
  • 地图投影(墨卡托、米勒、埃克特、温克尔三重、艾托夫、等距圆柱)
  • 标题和副标题配置
  • 边框和背景样式
  • 边距和内边距调整
  • 自定义CSS类
  • 主题集成
  • 响应式设计模式

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Internationalization (i18n)
  • Localization (l10n)
  • Accessibility (WCAG compliance, keyboard navigation)
  • State persistence across sessions
  • Printing and export functionality
  • Event handling patterns
  • Accessing component methods via ref
  • Performance optimization techniques
  • Migration guide from EJ1 to EJ2
📄 阅读: references/advanced-features.md
  • 国际化(i18n)
  • 本地化(l10n)
  • 无障碍性(符合WCAG标准、键盘导航)
  • 跨会话状态持久化
  • 打印和导出功能
  • 事件处理模式
  • 通过ref访问组件方法
  • 性能优化技巧
  • 从EJ1迁移到EJ2的指南

Quick Start Example

快速入门示例

tsx
import * as React from 'react';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';
import { world_map } from './world-map'; // GeoJSON data
import '@syncfusion/ej2-react-maps/styles/material.css';

function MapExample() {
  const data = [
    { Country: 'United States', Population: 331000000, Membership: 'Permanent' },
    { Country: 'Russia', Population: 145900000, Membership: 'Permanent' },
    { Country: 'China', Population: 1439000000, Membership: 'Permanent' },
    { Country: 'India', Population: 1380000000, Membership: 'Non-Permanent' },
    { Country: 'Brazil', Population: 212500000, Membership: 'Non-Permanent' }
  ];

  return (
    <MapsComponent
      titleSettings={{ text: 'World Map with Country Membership' }}
      legendSettings={{ visible: true }}
    >
      <Inject services={[Legend]} />
      <LayersDirective>
        <LayerDirective
          shapeData={world_map}
          shapeDataPath='Country'
          shapePropertyPath='name'
          dataSource={data}
          shapeSettings={{
            colorValuePath: 'Membership',
            colorMapping: [
              { value: 'Permanent', color: '#D84444' },
              { value: 'Non-Permanent', color: '#316DB5' }
            ]
          }}
        />
      </LayersDirective>
    </MapsComponent>
  );
}

export default MapExample;
tsx
import * as React from 'react';
import { MapsComponent, LayersDirective, LayerDirective, Inject, Legend } from '@syncfusion/ej2-react-maps';
import { world_map } from './world-map'; // GeoJSON data
import '@syncfusion/ej2-react-maps/styles/material.css';

function MapExample() {
  const data = [
    { Country: 'United States', Population: 331000000, Membership: 'Permanent' },
    { Country: 'Russia', Population: 145900000, Membership: 'Permanent' },
    { Country: 'China', Population: 1439000000, Membership: 'Permanent' },
    { Country: 'India', Population: 1380000000, Membership: 'Non-Permanent' },
    { Country: 'Brazil', Population: 212500000, Membership: 'Non-Permanent' }
  ];

  return (
    <MapsComponent
      titleSettings={{ text: 'World Map with Country Membership' }}
      legendSettings={{ visible: true }}
    >
      <Inject services={[Legend]} />
      <LayersDirective>
        <LayerDirective
          shapeData={world_map}
          shapeDataPath='Country'
          shapePropertyPath='name'
          dataSource={data}
          shapeSettings={{
            colorValuePath: 'Membership',
            colorMapping: [
              { value: 'Permanent', color: '#D84444' },
              { value: 'Non-Permanent', color: '#316DB5' }
            ]
          }}
        />
      </LayersDirective>
    </MapsComponent>
  );
}

export default MapExample;

Module Injection Guide

模块注入指南

Maps features are modular. Inject only the modules you need:
tsx
import { 
  MapsComponent, 
  Inject,
  Legend,        // For legends
  DataLabel,     // For data labels
  Marker,        // For markers
  Bubble,        // For bubbles
  MapsTooltip,   // For tooltips
  Zoom,          // For zooming and panning
  Highlight,     // For highlighting shapes
  Selection,     // For selecting shapes
  NavigationLine,// For navigation lines
  Annotations,   // For annotations
  Polygon        // For polygons
} from '@syncfusion/ej2-react-maps';

<MapsComponent>
  <Inject services={[Legend, Marker, MapsTooltip, Zoom]} />
  {/* Your layers */}
</MapsComponent>
Only inject modules for features you're using to minimize bundle size.
Maps功能采用模块化设计。仅注入你需要的模块:
tsx
import { 
  MapsComponent, 
  Inject,
  Legend,        // For legends
  DataLabel,     // For data labels
  Marker,        // For markers
  Bubble,        // For bubbles
  MapsTooltip,   // For tooltips
  Zoom,          // For zooming and panning
  Highlight,     // For highlighting shapes
  Selection,     // For selecting shapes
  NavigationLine,// For navigation lines
  Annotations,   // For annotations
  Polygon        // For polygons
} from '@syncfusion/ej2-react-maps';

<MapsComponent>
  <Inject services={[Legend, Marker, MapsTooltip, Zoom]} />
  {/* Your layers */}
</MapsComponent>
仅注入你正在使用的功能模块,以最小化包体积。

Common Use Cases

常见使用场景

Choropleth Map (Color-Coded Regions)

分级统计图(颜色编码区域)

Goal: Display statistical data with color-coded countries/regions
Approach:
  1. Bind data source with
    dataSource
    ,
    shapeDataPath
    ,
    shapePropertyPath
  2. Configure
    shapeSettings.colorValuePath
    to specify data field
  3. Set up
    colorMapping
    with value-color pairs
  4. Add
    Legend
    for interpretation
Example: Population density map, election results, COVID-19 statistics

目标: 使用颜色编码的国家/区域展示统计数据
方法:
  1. 使用
    dataSource
    shapeDataPath
    shapePropertyPath
    绑定数据源
  2. 配置
    shapeSettings.colorValuePath
    以指定数据字段
  3. 设置带有值-颜色对的
    colorMapping
  4. 添加
    Legend
    以辅助解读
示例: 人口密度地图、选举结果、COVID-19统计数据

Location Markers Map

位置标记地图

Goal: Show specific locations with custom markers
Approach:
  1. Add
    MarkersDirective
    inside
    LayerDirective
  2. Provide marker data with latitude/longitude
  3. Customize marker shapes, sizes, and templates
  4. Add tooltips for marker information
Example: Store locator, branch offices, tourist attractions

目标: 使用自定义标记展示特定位置
方法:
  1. LayerDirective
    内添加
    MarkersDirective
  2. 提供包含纬度/经度的标记数据
  3. 自定义标记形状、大小和模板
  4. 为标记添加提示框
示例: 店铺定位器、分支机构、旅游景点

Multi-Layer Overlay

多层级覆盖

Goal: Highlight specific regions on a base map
Approach:
  1. First layer: Base map (e.g., entire country)
  2. Additional layers with
    type="SubLayer"
    : Highlighted regions
  3. Style sublayers distinctly (different colors, borders)
  4. Control layer visibility and order
Example: State highlights on country map, sales regions

目标: 在基础地图上高亮特定区域
方法:
  1. 第一层:基础地图(例如整个国家)
  2. 额外设置
    type="SubLayer"
    的图层:高亮区域
  3. 为子图层设置独特样式(不同颜色、边框)
  4. 控制图层可见性和顺序
示例: 国家地图上的州高亮、销售区域

Route Visualization

路线可视化

Goal: Show connections or routes between locations
Approach:
  1. Add markers for start/end points
  2. Use
    NavigationLineDirective
    to draw lines
  3. Configure line curves, arrows, and styling
  4. Optionally animate lines
Example: Flight routes, shipping lanes, migration patterns

目标: 展示地点之间的连接或路线
方法:
  1. 为起点/终点添加标记
  2. 使用
    NavigationLineDirective
    绘制线条
  3. 配置曲线、箭头和线条样式
  4. 可选地为线条添加动画效果
示例: 飞行路线、航运航线、迁移模式

Map Provider Integration

地图提供商集成

Goal: Use real-world satellite/street map as base
Approach:
  1. Configure layer with
    urlTemplate
    for provider
  2. Set up API keys (Bing, Azure) if required
  3. Overlay GeoJSON shapes as sublayers if needed
  4. Add markers and labels on top
Example: Real estate map, delivery tracking, ride-sharing app
目标: 使用真实世界的卫星/街道地图作为基础
方法:
  1. 使用提供商的
    urlTemplate
    配置图层
  2. 若需要,设置API密钥(Bing、Azure)
  3. 若需要,将GeoJSON形状作为子图层叠加
  4. 在顶部添加标记和标签
示例: 房地产地图、配送跟踪、网约车应用

Decision Trees

决策树

Should I Use GeoJSON or Map Provider?

我应该使用GeoJSON还是地图提供商?

Use GeoJSON when:
  • You need custom shapes or boundaries
  • Data is region/country-based (choropleth maps)
  • No real-world street-level detail needed
  • Offline capability required
  • Full control over styling and data binding
Use Map Provider when:
  • Need real-world satellite/aerial imagery
  • Street-level detail required
  • Real-time map updates desired
  • Users expect familiar map interface (like Google Maps)
Use Both (Hybrid) when:
  • Need real-world base with custom shape overlays
  • Combining statistical regions with street context

使用GeoJSON的场景:
  • 你需要自定义形状或边界
  • 数据基于区域/国家(分级统计图)
  • 不需要真实世界的街道级细节
  • 需要离线能力
  • 需要完全控制样式和数据绑定
使用地图提供商的场景:
  • 需要真实世界的卫星/航拍图像
  • 需要街道级细节
  • 需要实时地图更新
  • 用户期望熟悉的地图界面(如谷歌地图)
同时使用两者(混合模式)的场景:
  • 需要真实世界基础地图并叠加自定义形状
  • 将统计区域与街道背景结合

Which Color Mapping Type?

选择哪种颜色映射类型?

Equal Color Mapping:
  • Use when data has discrete categories (e.g., Membership: Permanent/Non-Permanent)
  • Each unique value gets a specific color
Range Color Mapping:
  • Use when data is numeric and continuous (e.g., Population: 0-1M, 1M-10M, 10M+)
  • Values within ranges get assigned colors
Desaturation Color Mapping:
  • Use for gradient effects based on numeric values
  • Single color with varying saturation levels

等值颜色映射:
  • 当数据具有离散类别时使用(例如成员资格:常任/非常任)
  • 每个唯一值对应特定颜色
范围颜色映射:
  • 当数据为数值型且连续时使用(例如人口:0-1M、1M-10M、10M+)
  • 范围内的值分配对应颜色
饱和度调整颜色映射:
  • 用于基于数值的渐变效果
  • 单一颜色,饱和度水平不同

How Many Layers Should I Use?

我应该使用多少个图层?

Single Layer:
  • Simple visualizations with one data dimension
  • Basic country/region maps
  • When all data fits one layer
Multiple Layers:
  • Highlighting specific regions on base map
  • Combining different data sources
  • Creating visual depth with overlays
  • Showing borders, rivers, cities separately
单一图层:
  • 具有单一数据维度的简单可视化
  • 基础国家/区域地图
  • 所有数据可容纳在一个图层时
多个图层:
  • 在基础地图上高亮特定区域
  • 组合不同数据源
  • 通过覆盖层创建视觉深度
  • 分别展示边界、河流、城市

Key Props Reference

核心属性参考

MapsComponent

MapsComponent

  • titleSettings
    : Configure title and subtitle
  • legendSettings
    : Legend visibility, position, alignment
  • zoomSettings
    : Enable zooming, set initial zoom factor
  • layers
    : Array of layer configurations
  • titleSettings
    :配置标题和副标题
  • legendSettings
    :图例可见性、位置、对齐方式
  • zoomSettings
    :启用缩放,设置初始缩放因子
  • layers
    :图层配置数组

LayerDirective

LayerDirective

  • shapeData
    : GeoJSON data for shapes
  • dataSource
    : Data to bind to shapes
  • shapeDataPath
    : Field in dataSource matching shapes
  • shapePropertyPath
    : Field in GeoJSON matching dataSource
  • shapeSettings
    : Fill, border, color mapping
  • type
    : "Layer" (main) or "SubLayer" (overlay)
  • markerSettings
    : Marker configurations
  • bubbleSettings
    : Bubble visualizations
  • dataLabelSettings
    : Label configurations
  • tooltipSettings
    : Tooltip customization
  • navigationLineSettings
    : Line visualizations
  • shapeData
    :用于形状的GeoJSON数据
  • dataSource
    :要绑定到形状的数据
  • shapeDataPath
    :数据源中匹配形状的字段
  • shapePropertyPath
    :GeoJSON中匹配数据源的属性
  • shapeSettings
    :填充、边框、颜色映射
  • type
    :"Layer"(主图层)或"SubLayer"(覆盖层)
  • markerSettings
    :标记配置
  • bubbleSettings
    :气泡可视化
  • dataLabelSettings
    :标签配置
  • tooltipSettings
    :提示框自定义
  • navigationLineSettings
    :线条可视化

Common Patterns

常见模式

  • Module Injection: Only inject needed services to reduce bundle size
  • Data Binding: Use shapeDataPath + shapePropertyPath for automatic matching
  • Progressive Enhancement: Start with basic map, add features incrementally
  • Responsive Design: Maps auto-resize, but test on different viewports
  • 模块注入: 仅注入所需服务以减小包体积
  • 数据绑定: 使用shapeDataPath + shapePropertyPath实现自动匹配
  • 渐进式增强: 从基础地图开始,逐步添加功能
  • 响应式设计: 地图自动调整大小,但需在不同视口测试

Troubleshooting Quick Checks

故障排除快速检查

Map not displaying:
  • Verify GeoJSON data is correctly imported
  • Check console for errors
  • Ensure CSS is imported
Colors not applied:
  • Confirm
    shapeDataPath
    matches data field name
  • Verify
    shapePropertyPath
    matches GeoJSON property
  • Check
    colorValuePath
    points to correct data field
Markers not showing:
  • Inject
    Marker
    service
  • Set
    visible={true}
    in MarkerDirective
  • Verify latitude/longitude values are valid
Zoom not working:
  • Inject
    Zoom
    service
  • Set
    zoomSettings.enable={true}
  • Check if
    enablePanning
    is needed
Legend not appearing:
  • Inject
    Legend
    service
  • Set
    legendSettings.visible={true}
  • Ensure color mapping is configured
地图未显示:
  • 验证GeoJSON数据是否正确导入
  • 检查控制台错误
  • 确保已导入CSS
颜色未应用:
  • 确认
    shapeDataPath
    与数据字段名称匹配
  • 验证
    shapePropertyPath
    与GeoJSON属性匹配
  • 检查
    colorValuePath
    指向正确的数据字段
标记未显示:
  • 注入
    Marker
    服务
  • 在MarkerDirective中设置
    visible={true}
  • 验证纬度/经度值有效
缩放功能不工作:
  • 注入
    Zoom
    服务
  • 设置
    zoomSettings.enable={true}
  • 检查是否需要
    enablePanning
图例未显示:
  • 注入
    Legend
    服务
  • 设置
    legendSettings.visible={true}
  • 确保已配置颜色映射

Next Steps

后续步骤

  1. Start Simple: Begin with getting-started.md for basic map
  2. Add Data: Follow data-visualization.md for markers/bubbles
  3. Style It: Use color-mapping.md for choropleth effects
  4. Make Interactive: Implement user-interactions.md for zoom/pan
  5. Enhance: Add advanced features as needed
Choose the reference documentation that matches your current implementation phase and specific requirements.
  1. 从简开始: 参考getting-started.md创建基础地图
  2. 添加数据: 参考data-visualization.md添加标记/气泡
  3. 样式设置: 使用color-mapping.md实现分级统计图效果
  4. 添加交互: 参考user-interactions.md实现缩放/平移
  5. 功能增强: 根据需要添加高级功能
选择与你当前实现阶段和特定需求匹配的参考文档。