syncfusion-react-maps

实现 Syncfusion React Maps

全面介绍如何实现 Syncfusion React Maps 组件，使用丰富的交互功能、多个图层、标记、气泡、图例和地图提供商集成来可视化地理数据。

何时使用此技能

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

• 在交互式地图上显示地理数据
• 使用标记、气泡或数据标签可视化基于位置的信息
• 创建分级统计地图，根据数据值为区域着色
• 集成地图提供商，例如 Bing Maps、OpenStreetMap 或 Azure Maps
• 从 GeoJSON 数据文件渲染自定义形状
• 构建包含叠加层和子图层的多图层地图
• 添加导航线，显示位置之间的路线或连接
• 实现缩放和平移，以便探索地图
• 在地理区域上显示统计数据
• 创建用于解读数据的交互式图例
• 支持多种投影（Mercator、Miller、Eckert 等）
• 处理用户交互，例如工具提示、选择和高亮显示

组件概述

Syncfusion React Maps 组件是一款功能强大的数据可视化工具，可使用可缩放矢量图形（SVG）渲染地理数据。它支持：

• 任意数量的图层和子图层，用于复杂可视化
• GeoJSON 数据绑定，用于渲染自定义形状
• 地图提供商（Bing、OpenStreetMap、Azure）作为底图
• 6 种投影类型，用于呈现不同的地图视图
• 可视化元素：标记、气泡、导航线、注释、数据标签、图例
• 交互功能：缩放、平移、工具提示、选择、高亮显示
• 无障碍功能：符合 WCAG 2.1 标准，支持键盘导航
• 全球化：支持 RTL、国际化和本地化

主要功能

数据可视化元素

• 标记：使用自定义形状、模板和聚类标注位置
• 气泡：使用基于大小的气泡显示数据量级
• 数据标签：直接在地图形状上显示信息
• 颜色映射：根据数据值应用颜色（相等、范围、去饱和）
• 导航线：使用曲线和箭头绘制位置之间的连接
• 图例：提供用于解读数据的可视化标识

图层架构

• 主图层：来自 GeoJSON 或地图提供商的底图
• 子图层：在主图层上叠加其他形状
• 多图层支持：堆叠多个图层，实现丰富的可视化效果

地图提供商

• Bing Maps：卫星、航拍和道路视图
• OpenStreetMap：免费的瓦片图层提供商
• Azure Maps：Microsoft 的地图服务
• 混合方式：将 GeoJSON 形状与提供商瓦片结合

用户交互

• 缩放：鼠标滚轮、双击、捏合和工具栏控件
• 平移：拖动以探索不同区域
• 工具提示：悬停时显示数据
• 选择：单击时高亮显示形状
• 重置：返回初始视图

文档与导航指南

API 参考

📄 阅读： references/api-reference.md

• MapsComponent 属性完整参考
• 所有可用方法及示例
• 全面的事件文档
• 图层、标记、气泡和数据标签设置
• 图例、缩放和工具提示配置
• 快速参考代码示例
• 类型定义和参数

入门指南

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• Maps 组件的基本实现
• GeoJSON 数据结构和绑定
• CSS 主题导入
• 模块注入模式（基于功能）
• 首个世界地图示例
• 使用 shapeDataPath 和 shapePropertyPath 绑定数据源

图层与结构

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

• 了解图层架构
• 主图层与子图层的区别
• 创建多图层地图
• 图层类型与堆叠顺序
• 图层专属设置与配置
• 何时使用多个图层

标记

📄 阅读： references/markers.md

• 添加标记以标出位置
• 标记数据源结构（纬度、经度）
• 标记形状与自定义模板
• 为密集数据聚合标记
• 动态更新标记
• 带点击事件的交互式标记
• 标记工具提示与标签

数据可视化元素

📄 阅读： references/data-visualization.md

• 用气泡可视化数据量级
• 配置气泡大小和颜色
• 设置和格式化数据标签
• 智能标签模式（裁剪、隐藏、不显示）
• 用标签模板自定义内容
• 结合使用气泡与数据标签
• 视觉层次的最佳实践

图例

📄 阅读： references/legend.md

• 启用和配置图例
• 定位策略（绝对定位、停靠）
• 图例对齐选项（近端、居中、远端）
• 交互式图例
• 图例模式（默认、交互式）
• 自定义图例外观
• 将图例与颜色映射同步

颜色映射

📄 阅读： references/color-mapping.md

• 颜色映射类型（等值、范围、去饱和）
• 根据数据值应用颜色
• 设置 colorValuePath
• 创建分级统计地图
• 多条颜色映射规则
• 自定义配色方案
• 数据可视化策略

导航线

📄 阅读： references/navigation-lines.md

• 在位置之间创建线条
• 线条样式（宽度、颜色、虚线数组）
• 曲线和角度
• 用箭头指示方向
• 使用场景（路线、连接、流向）
• 线条动画效果

地图提供方

📄 阅读： references/map-providers.md

• 支持的提供方概览
• 何时使用 GeoJSON，何时使用地图提供方
• Bing Maps 设置和 API 密钥
• 集成 OpenStreetMap（免费）
• 配置 Azure Maps
• 瓦片图层类型（卫星、航空、道路）
• 混合方案（在提供方瓦片上叠加 GeoJSON）

用户交互

📄 阅读： references/user-interactions.md

• 启用和配置缩放
• 缩放系数和工具栏控件
• 平移功能
• 工具提示配置和模板
• 选择和高亮形状
• 鼠标滚轮和双击缩放
• 触控设备上的捏合缩放
• 重置到初始视图

注释和多边形

📄 阅读： references/annotations-polygon.md

• 向地图添加自定义注释
• 使用多边形绘制自定义形状
• 定位和对齐
• 交互式注释
• 覆盖层的使用场景

自定义

• 地图投影（Mercator、Miller、Eckert、Winkel Tripel、Aitoff、Equirectangular）
• 配置标题和副标题
• 边框与背景样式
• 调整外边距和内边距
• 自定义 CSS 类
• 主题集成
• 响应式设计模式

高级功能

📄 阅读： references/advanced-features.md

• 国际化（i18n）
• 本地化（l10n）
• 无障碍功能（符合 WCAG 标准、键盘导航）
• 跨会话持久化状态
• 打印和导出功能
• 事件处理模式
• 通过 ref 访问组件方法
• 性能优化技巧
• 从 EJ1 迁移到 EJ2 的指南

快速入门示例

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

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;

模块注入指南

地图功能采用模块化设计。只注入所需模块：

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>

只为正在使用的功能注入模块，以尽可能减小包体积。

常见使用场景

分级统计地图（按颜色区分区域）

目标：使用不同颜色显示国家／地区的统计数据

方法：

1. 使用 dataSource、shapeDataPath、shapePropertyPath 绑定数据源
2. 配置 shapeSettings.colorValuePath，指定数据字段
3. 使用值与颜色的配对配置 colorMapping
4. 添加 Legend 以便解读

示例：人口密度地图、选举结果、COVID-19 统计数据

---

位置标记地图

目标：使用自定义标记显示特定位置

方法：

1. 在 LayerDirective 内添加 MarkersDirective
2. 提供包含纬度／经度的标记数据
3. 自定义标记的形状、大小和模板
4. 添加工具提示以显示标记信息

示例：门店定位、分支办公室、旅游景点

---

多图层叠加

目标：在底图上突出显示特定区域

方法：

1. 第一层：底图（例如，整个国家）
2. 添加 type="SubLayer" 图层以突出显示区域
3. 为子图层设置不同样式（不同颜色、边框）
4. 控制图层的可见性和顺序

示例：在国家地图上突出显示州、销售区域

---

路线可视化

目标：显示地点之间的连接或路线

方法：

1. 为起点／终点添加标记
2. 使用 NavigationLineDirective 绘制线条
3. 配置线条曲线、箭头和样式
4. 可选择为线条添加动画

示例：航线、航运路线、迁徙模式

---

地图服务集成

目标：使用真实世界的卫星／街道地图作为底图

方法：

1. 使用服务商提供的 urlTemplate 配置图层
2. 根据需要设置 API 密钥（Bing、Azure）
3. 如有需要，将 GeoJSON 形状作为子图层叠加
4. 在上层添加标记和标签

示例：房地产地图、配送追踪、网约车应用

决策树

应该使用 GeoJSON 还是地图服务？

使用 GeoJSON 的情况：

• 需要自定义形状或边界
• 数据以区域／国家为单位（分级统计地图）
• 无需真实世界的街道级细节
• 需要离线功能
• 需要完全控制样式和数据绑定

使用地图服务的情况：

• 需要真实世界的卫星／航空影像
• 需要街道级细节
• 需要实时更新地图
• 用户期望使用熟悉的地图界面（例如 Google Maps）

同时使用两者（混合方案）的情况：

• 需要以真实世界地图为底图，并叠加自定义形状
• 将统计区域与街道环境结合

---

应该选择哪种颜色映射类型？

等色映射：

• 数据包含离散类别时使用（例如，会员资格：永久／非永久）
• 每个唯一值都分配一种特定颜色

范围颜色映射：

• 数据为连续数值时使用（例如，人口：0-1M、1M-10M、10M+）
• 为范围内的值分配颜色

去饱和度颜色映射：

• 根据数值创建渐变效果时使用
• 使用单一颜色，并改变其饱和度

---

应该使用多少个图层？

单图层：

• 只有一个数据维度的简单可视化
• 基本的国家／地区地图
• 所有数据都能放在一个图层中

多图层：

• 在底图上突出显示特定区域
• 组合不同的数据源
• 使用叠加层创建视觉层次
• 分别显示边界、河流和城市

关键属性参考

MapsComponent

• titleSettings：配置标题和副标题
• legendSettings：配置图例的可见性、位置和对齐方式
• zoomSettings：启用缩放，设置初始缩放比例
• layers：图层配置数组

LayerDirective

• shapeData：形状的 GeoJSON 数据
• dataSource：要绑定到形状的数据
• shapeDataPath：dataSource 中与形状匹配的字段
• shapePropertyPath：GeoJSON 中与 dataSource 匹配的字段
• shapeSettings：填充、边框和颜色映射
• type："Layer"（主图层）或 "SubLayer"（叠加层）
• markerSettings：标记配置
• bubbleSettings：气泡可视化配置
• dataLabelSettings：标签配置
• tooltipSettings：工具提示自定义配置
• navigationLineSettings：线条可视化配置

常见模式

• 模块注入：仅注入所需服务，以减小打包体积
• 数据绑定：使用 shapeDataPath + shapePropertyPath 自动匹配
• 渐进式增强：从基础地图开始，逐步添加功能
• 响应式设计：地图会自动调整大小，但请在不同视口上进行测试

故障排查快速检查

❌ 地图未显示：

• 确认 GeoJSON 数据已正确导入
• 检查控制台是否有错误
• 确保已导入 CSS

❌ 颜色未应用：

• 确认 shapeDataPath 与数据字段名称匹配
• 确认 shapePropertyPath 与 GeoJSON 属性匹配
• 检查 colorValuePath 是否指向正确的数据字段

❌ 标记未显示：

• 注入 Marker 服务
• 在 MarkerDirective 中设置 visible={true}
• 确认纬度/经度值有效

❌ 缩放不起作用：

• 注入 Zoom 服务
• 设置 zoomSettings.enable={true}
• 检查是否需要 enablePanning

❌ 图例未显示：

• 注入 Legend 服务
• 设置 legendSettings.visible={true}
• 确保已配置颜色映射

后续步骤

1. 从简单开始：从 getting-started.md 开始，创建基础地图
2. 添加数据：按照 data-visualization.md 添加标记/气泡
3. 设置样式：使用 color-mapping.md 实现分级设色效果
4. 添加交互：按照 user-interactions.md 实现缩放/平移
5. 增强功能：根据需要添加高级功能

选择与当前实现阶段和具体需求相匹配的参考文档。