syncfusion-angular-maps

实现 Syncfusion Angular Maps

实现 Syncfusion Angular Maps 组件的全面指南，帮助你使用交互功能、多图层和丰富的自定义选项可视化地理数据。

何时使用此技能

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

• 可视化地理数据 - 在世界地图、国家地图、区域地图或自定义地理形状上显示统计数据
• 创建交互式地图 - 构建支持缩放、平移、选择、高亮和工具提示交互的地图
• 标注位置 - 添加标记、气泡或注释，以突出显示特定地理位置
• 显示地图图层 - 使用 GeoJSON 数据或地图提供商（Bing、OpenStreetMap、Azure）处理多个叠加图层
• 为区域设置颜色编码 - 根据数据值应用颜色映射，以实现分级统计图或热力图可视化
• 自定义地图可视化 - 创建非地理类可视化，例如座位布局、楼层平面图或体育场地图
• 导航和路线规划 - 在标记之间绘制导航线或路线
• 导出和打印地图 - 生成可打印或可导出的地图可视化
• 构建仪表板 - 将地图集成到 Angular 应用程序中，用于商业智能或分析

组件概览

Syncfusion Angular Maps 组件（@syncfusion/ej2-angular-maps）是一款强大的数据可视化工具，可使用可缩放矢量图形（SVG）渲染地理数据。它支持：

• 多个图层和子图层，用于实现复杂的可视化效果
• GeoJSON 数据绑定，用于自定义形状和区域
• 地图提供商（Bing Maps、OpenStreetMap、Azure Maps）作为基础图层
• 六种投影类型（Mercator、Equirectangular、Miller、Eckert3、Eckert5、Eckert6、Winkel3、AitOff）
• 丰富的可视化元素 - 标记、气泡、数据标签、图例、导航线、注释
• 交互功能 - 缩放、平移、工具提示、选择、高亮
• 响应式且无障碍设计，符合 WCAG 标准

文档和导航指南

入门

📄 阅读： references/getting-started.md

首次实现 Maps 或设置新的 Angular 项目时：

• 安装依赖项（@syncfusion/ej2-angular-maps 软件包）
• 设置 Angular 环境并导入 MapsModule
• 使用世界地图数据创建第一个基础地图
• 了解功能的模块注入（MarkerService、BubbleService 等）
• 添加 CSS 主题和样式
• 运行应用程序

图层和数据绑定

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

处理地图图层、形状数据和数据源绑定时：

• 了解图层结构和配置
• 加载 GeoJSON 形状数据（shapeData 属性）
• 绑定外部数据源（dataSource、shapeDataPath、shapePropertyPath）
• 创建多个图层和子图层
• 图层类型（基础图层与子图层）
• 在图层之间切换（baseLayerIndex）
• 为非地理类可视化渲染自定义形状
• GeometryType 选项（Geographic 与 Normal）

标记

📄 阅读： references/markers.md

添加和自定义位置标记时：

• 使用纬度/经度数据添加标记
• 标记形状（Balloon、Circle、Cross、Diamond、Image、Rectangle、Star、Triangle）
• 自定义标记模板
• 标记样式（大小、颜色、边框、不透明度）
• 使用数据绑定创建动态标记
• 标记聚类
• 标记动画和过渡效果
• 标记工具提示和事件
• 在标记之间创建路线

数据可视化功能

📄 阅读： references/data-visualization.md

用于通过气泡、颜色、标签和图例可视化数据：

• 气泡 - 根据大小可视化定量数据
• 颜色映射 - 范围颜色映射、等值颜色映射、去饱和颜色映射
• 数据标签 - 在地图上显示形状名称或数据值
• 图例 - 为颜色映射和气泡添加图例
• 导航线 - 绘制地点之间的连线
• 注释 - 在特定位置添加自定义 HTML 内容
• 组合使用多种可视化功能

用户交互

📄 阅读： references/user-interactions.md

用于实现交互式地图行为：

• 缩放 - 鼠标滚轮缩放、双指捏合缩放、双击缩放、缩放工具栏
• 平移 - 鼠标拖动和平移触控操作
• 工具提示 - 图层工具提示、标记工具提示、气泡工具提示
• 选择 - 形状选择、标记选择、气泡选择
• 高亮 - 悬停高亮效果
• 交互式图例 - 点击图例项以显示或隐藏形状
• 事件处理（点击、悬停、缩放、平移事件）
• 触控和移动设备支持

地图服务提供方

📄 阅读： references/map-providers.md

用于集成外部地图服务：

• 地图服务提供方支持概述
• Bing Maps 集成和 API 密钥配置
• OpenStreetMap（OSM）集成
• Azure Maps 集成
• 服务提供方特有的功能和限制
• 将地图服务提供方与形状图层组合使用
• URL 模板和瓦片服务
• 缩放级别配置

多边形形状

📄 阅读： references/polygon-shapes.md

用于绘制和自定义多边形：

• 向地图添加多边形叠加层
• 多边形配置和数据结构
• 设置多边形样式（填充、边框、不透明度）
• 多边形事件（点击、悬停）
• 使用场景（高亮区域、边界、区域）
• 动态渲染多边形

自定义和样式设置

📄 阅读： references/customization.md

用于主题和视觉自定义：

• CSS 自定义和主题覆盖
• 形状样式（填充、边框、配色方案）
• 响应式设计模式
• 地图投影 - 选择和配置投影类型
• 背景自定义（颜色、图像）
• 标题和副标题样式
• 边框和边距配置

本地化和国际化

📄 阅读： references/localization.md

用于地图内容全球化：

• 国际化（i18n）设置
• 针对不同语言的本地化（l10n）
• 从右到左（RTL）支持
• 不同区域设置的数字格式
• 工具提示/标签中的货币格式
• 日期和时间格式
• 特定区域设置的渲染

高级功能

📄 阅读： references/advanced-features.md

用于高级功能和 API：

• 打印和导出 - 打印地图，导出为 PNG/JPEG/SVG/PDF
• 状态持久化 - 保存和恢复地图状态
• 公共方法 - 以编程方式控制（刷新、打印、导出等）
• 事件参考 - 可用事件完整列表
• 创建路线 - 绘制标记之间的导航路线
• 自定义路径渲染 - 高级路径和线条自定义
• 下钻导航 - 创建分层地图导航

无障碍访问

📄 阅读： references/accessibility.md

用于实现无障碍地图：

• WCAG 2.1 合规指南
• 键盘导航支持
• ARIA 属性和角色
• 屏幕阅读器兼容性
• 高对比度主题支持
• 焦点指示器和管理
• 形状和标记的替代文本

快速开始

安装

# Install the Maps package
npm install @syncfusion/ej2-angular-maps --save

基本实现

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map'; // GeoJSON data

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer [shapeData]='shapeData'></e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
}

使用数据绑定和颜色映射

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [dataSource]='dataSource'
          shapeDataPath='Country'
          shapePropertyPath='name'
          [shapeSettings]='shapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public dataSource: object[] = [
    { Country: 'United States', Population: 331002651, Code: 'US' },
    { Country: 'India', Population: 1380004385, Code: 'IN' },
    { Country: 'China', Population: 1439323776, Code: 'CN' }
  ];
  
  public shapeSettings: object = {
    colorValuePath: 'Population',
    colorMapping: [
      { from: 0, to: 100000000, color: '#C5E8B7' },
      { from: 100000001, to: 500000000, color: '#5BC85A' },
      { from: 500000001, to: 2000000000, color: '#238B45' }
    ]
  };
}

常见模式

模式 1：带标记和工具提示的地图

import { Component } from '@angular/core';
import { MapsModule, MarkerService, MapsTooltipService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  providers: [MarkerService, MapsTooltipService],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [markerSettings]='markerSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public markerSettings: object[] = [{
    visible: true,
    dataSource: [
      { latitude: 40.7128, longitude: -74.0060, name: 'New York' },
      { latitude: 51.5074, longitude: -0.1278, name: 'London' },
      { latitude: 35.6762, longitude: 139.6503, name: 'Tokyo' }
    ],
    shape: 'Circle',
    fill: '#FF6347',
    height: 15,
    width: 15,
    tooltipSettings: {
      visible: true,
      valuePath: 'name'
    }
  }];
}

模式 2：带缩放和图例的交互式地图

import { Component } from '@angular/core';
import { MapsModule, ZoomService, LegendService } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  providers: [ZoomService, LegendService],
  template: `
    <ejs-maps 
      id='maps-container'
      [zoomSettings]='zoomSettings'
      [legendSettings]='legendSettings'>
      <e-layers>
        <e-layer 
          [shapeData]='shapeData'
          [dataSource]='dataSource'
          shapeDataPath='Country'
          shapePropertyPath='name'
          [shapeSettings]='shapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public shapeData: object = world_map;
  
  public dataSource: object[] = [
    { Country: 'United States', Category: 'High' },
    { Country: 'Canada', Category: 'Medium' },
    { Country: 'Mexico', Category: 'Low' }
  ];
  
  public shapeSettings: object = {
    colorValuePath: 'Category',
    colorMapping: [
      { value: 'High', color: '#E74C3C' },
      { value: 'Medium', color: '#F39C12' },
      { value: 'Low', color: '#27AE60' }
    ]
  };
  
  public zoomSettings: object = {
    enable: true,
    toolbars: ['Zoom', 'ZoomIn', 'ZoomOut', 'Pan', 'Reset']
  };
  
  public legendSettings: object = {
    visible: true,
    position: 'Bottom'
  };
}

模式 3：带子图层的多图层地图

import { Component } from '@angular/core';
import { MapsModule } from '@syncfusion/ej2-angular-maps';
import { world_map } from './world-map';
import { usa_map } from './usa-map';
import { california } from './california';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MapsModule],
  template: `
    <ejs-maps id='maps-container'>
      <e-layers>
        
        <e-layer 
          [shapeData]='usaMap'
          [shapeSettings]='baseShapeSettings'>
        </e-layer>
        
        
        <e-layer 
          type='SubLayer'
          [shapeData]='californiaMap'
          [shapeSettings]='sublayerShapeSettings'>
        </e-layer>
      </e-layers>
    </ejs-maps>
  `
})
export class AppComponent {
  public usaMap: object = usa_map;
  public californiaMap: object = california;
  
  public baseShapeSettings: object = {
    fill: '#E5E5E5',
    border: { color: '#000000', width: 0.5 }
  };
  
  public sublayerShapeSettings: object = {
    fill: '#FFD700',
    border: { color: '#FF6347', width: 2 }
  };
}

关键配置选项

图层设置

• shapeData - 形状的 GeoJSON 数据
• dataSource - 要绑定的外部数据
• shapeDataPath - 用于标识形状的 dataSource 字段
• shapePropertyPath - shapeData 中与 dataSource 匹配的字段
• shapeSettings - 形状的视觉样式
• type - 图层类型（'Layer' 或 'SubLayer'）

形状设置

• fill - 形状填充颜色
• border - 边框配置（颜色、宽度、不透明度）
• colorValuePath - 用于颜色映射的数据字段
• colorMapping - 颜色范围或值的数组
• autofill - 为形状自动生成颜色

标记设置

• visible - 显示/隐藏标记
• dataSource - 包含纬度/经度的标记数据
• shape - 标记形状类型
• height / width - 标记尺寸
• template - 自定义 HTML 模板
• tooltipSettings - 标记工具提示配置

缩放设置

• enable - 启用/禁用缩放
• zoomFactor - 初始缩放级别
• maxZoom / minZoom - 缩放限制
• toolbars - 缩放控件按钮
• mouseWheelZoom - 启用鼠标滚轮缩放
• pinchZooming - 启用触摸捏合缩放

图例设置

• visible - 显示/隐藏图例
• position - 图例位置（Top、Bottom、Left、Right）
• mode - 图例模式（'Default'、'Interactive'）
• type - 图例类型（'Layers'、'Bubbles'、'Markers'）

常见用例

用例 1：按地区划分的销售仪表板

创建分级统计地图，以颜色编码的地区显示各个国家或州的销售数据，并提供交互式工具提示和图例。适用于商业智能仪表板。

用例 2：门店定位地图

使用自定义标记图标显示门店位置，在密集区域进行聚类，并通过工具提示展示门店详情。与地图服务商集成，以呈现街道级细节。

用例 3：选举结果可视化

使用颜色映射显示各选区/州的选举结果，并提供下钻功能以探索详细的地区数据。

用例 4：实时追踪仪表板

绘制车辆、货物或资产的位置，使用动画标记、显示路线的导航线以及实时数据更新。

用例 5：天气或环境数据

使用颜色渐变和地理区域数据标签，可视化温度、降雨量、空气质量或其他环境指标。

用例 6：COVID-19 或疾病传播追踪

按地区使用气泡大小和颜色强度显示病例数、疫苗接种率或感染率。

用例 7：航线可视化

使用导航线显示城市之间的航线，并提供机场标记和交互式选择功能。

用例 8：自定义座位布局

使用自定义 GeoJSON 形状创建非地理可视化，例如剧院、体育场或交通工具中的选座布局。

模块注入要求

Maps 组件使用必须注入的特定功能服务：

import { 
  MapsModule,
  MarkerService,          // For markers
  BubbleService,          // For bubbles
  DataLabelService,       // For data labels
  LegendService,          // For legends
  MapsTooltipService,     // For tooltips
  ZoomService,            // For zoom and pan
  SelectionService,       // For selection
  HighlightService,       // For highlighting
  NavigationLineService,  // For navigation lines
  AnnotationsService,     // For annotations
  PolygonService          // For polygons
} from '@syncfusion/ej2-angular-maps';

@Component({
  providers: [
    MarkerService,
    LegendService,
    MapsTooltipService,
    ZoomService
    // Add only the services you need
  ]
})

API 参考文档

完整 API 目录

📘 完整 API 参考指南 - 所有 Maps API 的综合文档

按类别划分的快速 API 链接

核心组件

• MapsComponent - 具有 20 多个属性和方法的主要地图组件
• print() - 打印功能
• export() - 导出为图像/PDF
• refresh() - 刷新地图
• addLayer() - 动态添加图层

图层配置

• LayerSettings - 图层配置模型
• ShapeSettings - 形状样式配置
• shapeData - GeoJSON 形状数据
• dataSource - 外部数据绑定

标记和气泡

• MarkerSettings - 标记配置
• BubbleSettings - 气泡可视化
• DataLabelSettings - 数据标签

用户交互

• ZoomSettings - 缩放和平移配置
• TooltipSettings - 工具提示配置
• SelectionSettings - 选择行为
• HighlightSettings - 高亮行为

自定义

• LegendSettings - 图例配置
• ColorMappingSettings - 分级统计图的颜色映射
• NavigationLineSettings - 导航线
• Annotation - 自定义注释

关键事件（共 25 个以上）

• load - 地图加载前
• loaded - 地图加载后
• shapeSelected - 形状选择事件
• markerClick - 标记点击事件
• zoom - 缩放事件
• pan - 平移事件

枚举

• ProjectionType - 地图投影类型（Mercator、Miller、Eckert 等）
• MarkerType - 标记形状（Balloon、Circle、Diamond 等）
• LayerType - 图层与子图层
• GeometryType - 地理与常规几何

事件接口

• ILoadEventArgs - 加载事件参数
• IShapeSelectedEventArgs - 选择事件参数
• IMarkerClickEventArgs - 标记点击事件参数

特定上下文的 API 参考

每份参考指南都包含相关的 API 表：

• getting-started.md - 核心设置 API
• layers-and-data.md - 图层和数据绑定 API
• markers.md - 标记 API 和事件
• data-visualization.md - 气泡、颜色映射和图例 API
• user-interactions.md - 缩放、平移、工具提示和选择 API
• map-providers.md - 地图提供程序 API
• customization.md - 外观和样式 API
• accessibility.md - 无障碍相关 API

---

后续步骤

1. 从 getting-started.md 开始，设置你的第一个地图
2. 探索 layers-and-data.md，了解数据绑定
3. 添加 markers.md，绘制位置
4. 实现 user-interactions.md，支持缩放、平移和工具提示
5. 查看 customization.md，了解样式和主题
6. 检查 accessibility.md，确保符合 WCAG 标准

---

软件包： @syncfusion/ej2-angular-maps
文档： Syncfusion Angular Maps 文档
演示： Syncfusion Angular Maps 演示