syncfusion-javascript-maps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Maps (TypeScript & JavaScript)

实现Syncfusion Maps（TypeScript & JavaScript）

The Syncfusion Maps component is a powerful tool for visualizing geographical data, displaying interactive maps with layers, markers, bubbles, and advanced features like color mapping and navigation lines. Works in both TypeScript (with full type safety) and JavaScript (ES5 CDN-based or webpack).

Syncfusion Maps组件是一款功能强大的工具，可用于可视化地理数据、展示带有图层、标记、气泡的交互式地图，还支持颜色映射、导航线等高级特性。同时支持TypeScript（具备完整类型安全能力）和JavaScript（基于ES5 CDN或webpack）两种开发模式。

Platform Support

平台支持

This skill covers TypeScript implementation:

TypeScript:

Full type definitions and IDE support
Module-based imports with npm
Webpack/bundler-based setup
Advanced type checking

本指南覆盖TypeScript实现方案：

TypeScript：

完整的类型定义与IDE支持
基于npm的模块导入
基于Webpack/打包工具的项目配置
高级类型检查能力

When to Use This Skill

适用场景

Use this skill when you need to:

Create interactive geographical maps in TypeScript applications
Display data across different geographical regions
Add markers, bubbles, or polygons to map visualizations
Apply color mapping based on data values
Configure map layers and different map providers
Add user interactions like selection and tooltips
Implement state persistence for map settings
Print or export map visualizations
Create navigation lines between locations
Customize map appearance with styling and themes

当你需要完成以下需求时可使用本指南：

在TypeScript应用中创建交互式地理地图
跨不同地理区域展示数据
为地图可视化内容添加标记、气泡或多边形
根据数据值应用颜色映射
配置地图图层与不同地图服务商
添加选择、提示框等用户交互能力
实现地图配置的状态持久化
打印或导出地图可视化内容
创建不同地点之间的导航线
通过样式与主题自定义地图外观

Maps Overview

Maps组件概览

The Syncfusion Maps component provides:

Multiple Map Providers: Support for OpenStreetMap, Bing Maps, and other providers
Data Visualization: Bubbles, polygons, and color mapping for data representation
Interactive Features: Markers, tooltips, legends, annotations, and navigation lines
User Interactions: Selection, zooming, panning, and mouse events
Customization: Extensive styling options and theming capabilities
State Management: Save and restore map state and viewport settings
Export: Print functionality and export capabilities

Syncfusion Maps组件提供以下能力：

多地图服务商支持：支持OpenStreetMap、Bing Maps等服务商
数据可视化能力：可通过气泡、多边形、颜色映射实现数据展示
交互式特性：支持标记、提示框、图例、注释、导航线
用户交互能力：支持选择、缩放、平移、鼠标事件
自定义能力：丰富的样式选项与主题配置能力
状态管理：支持保存与恢复地图状态和视口设置
导出能力：支持打印与导出功能

Documentation and Navigation Guide

文档与导航指南

API Reference Guide

API参考指南

📄 Read: references/api-reference-guide.md

Core Maps Class - Main component and its properties
Configuration Interfaces - All available settings and options
- CenterPosition, ZoomSettings, LayerSettings
- MarkerSettings, BubbleSettings, ShapeSettings
- NavigationLineSettings, LegendSettings, Annotation
- TooltipSettings, SelectionSettings, HighlightSettings
- DataLabelSettings, ColorMappingSettings
- TitleSettings, SubTitleSettings, and more
Event Arguments - Event handler parameters and data structures
- IMarkerClickEventArgs, IMarkerRenderingEventArgs
- IShapeSelectedEventArgs, IBubbleClickEventArgs
- IMapZoomEventArgs, IMapPanEventArgs
- ITooltipRenderEventArgs, IMouseEventArgs, and more
Enumerations - Predefined constants and types
- ExportType, MapsTheme, ProjectionType
- LegendPosition, LegendMode, LegendShape
Methods - Available component methods
- appendTo(), refresh(), destroy(), export(), print()
Quick API Reference Table - At-a-glance property mapping

📄 阅读： references/api-reference-guide.md

核心Maps类 - 主组件及其属性
配置接口 - 所有可用设置与选项
- CenterPosition, ZoomSettings, LayerSettings
- MarkerSettings, BubbleSettings, ShapeSettings
- NavigationLineSettings, LegendSettings, Annotation
- TooltipSettings, SelectionSettings, HighlightSettings
- DataLabelSettings, ColorMappingSettings
- TitleSettings, SubTitleSettings等
事件参数 - 事件处理函数参数与数据结构
- IMarkerClickEventArgs, IMarkerRenderingEventArgs
- IShapeSelectedEventArgs, IBubbleClickEventArgs
- IMapZoomEventArgs, IMapPanEventArgs
- ITooltipRenderEventArgs, IMouseEventArgs等
枚举 - 预定义常量与类型
- ExportType, MapsTheme, ProjectionType
- LegendPosition, LegendMode, LegendShape
方法 - 可用的组件方法
- appendTo(), refresh(), destroy(), export(), print()
快速API参考表 - 可快速查阅的属性映射表

Getting Started & Setup

入门与配置

📄 Read: references/getting-started.md

Installation and package setup
Creating your first map
Setting up the map container
Basic TypeScript configuration and initialization

📄 阅读： references/getting-started.md

安装与包配置
创建你的第一个地图
配置地图容器
基础TypeScript配置与初始化

Data & Layers

数据与图层

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

Populating maps with geographical data
Working with map layers (OSM, Bing, Geometry)
Data binding patterns
Multiple layer configuration

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

为地图填充地理数据
处理地图图层（OSM、Bing、几何图层）
数据绑定模式
多图层配置

Markers & Navigation

标记与导航

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

Adding markers to map locations
Creating navigation lines between locations
Customizing marker appearance and templates
Interactive marker features and events
Marker clustering for performance

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

为地图点位添加标记
创建点位之间的导航线
自定义标记外观与模板
交互式标记特性与事件
用于性能优化的标记聚类

Visualization Features

可视化特性

📄 Read: references/visualization-features.md

Bubble visualization for data points
Polygon rendering on maps
Color mapping strategies (range, equal, desaturation)
Adding data labels to map elements
Combining multiple visualization types

📄 阅读： references/visualization-features.md

针对数据点的气泡可视化
地图上的多边形渲染
颜色映射策略（区间、等值、去饱和度）
为地图元素添加数据标签
组合多种可视化类型

Legends & Annotations

图例与注释

📄 Read: references/legends-and-annotations.md

Configuring and customizing legends
Legend positioning and modes (List, Interactive)
Adding annotations and overlays
Tooltip configuration and formatting
Data label styling

📄 阅读： references/legends-and-annotations.md

配置与自定义图例
图例位置与模式（列表、交互式）
添加注释与覆盖层
提示框配置与格式化
数据标签样式设置

Map Providers & Selection

地图服务商与选择能力

📄 Read: references/map-providers-and-selection.md

Using different map providers (OpenStreetMap, Bing Maps)
User interaction events (click, zoom, pan)
Selection and highlighting features
Provider comparison and setup guides
Advanced selection patterns

📄 阅读： references/map-providers-and-selection.md

使用不同地图服务商（OpenStreetMap、Bing Maps）
用户交互事件（点击、缩放、平移）
选择与高亮特性
服务商对比与配置指南
高级选择模式

Customization & Persistence

自定义与持久化

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

CSS customization and theming
Built-in themes and custom styling
State persistence and viewport management
Print and export functionality (PNG, SVG, PDF)
Advanced styling techniques
Performance optimization

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

CSS自定义与主题配置
内置主题与自定义样式
状态持久化与视口管理
打印与导出功能（PNG、SVG、PDF）
高级样式技巧
性能优化

Troubleshooting

故障排查

📄 Read: references/troubleshooting.md

Common issues and solutions
Setup problems (container, tiles, markers)
Data loading and color mapping issues
Performance optimization tips
Browser compatibility considerations
TypeScript and JavaScript specific issues

📄 阅读： references/troubleshooting.md

常见问题与解决方案
配置问题（容器、瓦片、标记）
数据加载与颜色映射问题
性能优化建议
浏览器兼容性注意事项
TypeScript与JavaScript专属问题

Quick Start Example

快速入门示例

TypeScript:

typescript

import { Maps, Marker } from '@syncfusion/ej2-maps';

// Inject required modules
Maps.Inject(Marker);

const map = new Maps({
    center: { latitude: 37.6872, longitude: -122.0808 },
    zoomSettings: { maxZoom: 13, minZoom: 1 },
    layers: [
        {
            urlTemplate: 'https://tile.openstreetmap.org/level/tileX/tileY.png',
            type: 'OSM',
            markerSettings: {
                dataSource: [
                    { latitude: 37.6872, longitude: -122.0808, name: 'San Francisco' }
                ]
            }
        }
    ]
});

map.appendTo('#map');

TypeScript：

typescript

import { Maps, Marker } from '@syncfusion/ej2-maps';

// 注入所需模块
Maps.Inject(Marker);

const map = new Maps({
    center: { latitude: 37.6872, longitude: -122.0808 },
    zoomSettings: { maxZoom: 13, minZoom: 1 },
    layers: [
        {
            urlTemplate: 'https://tile.openstreetmap.org/level/tileX/tileY.png',
            type: 'OSM',
            markerSettings: {
                dataSource: [
                    { latitude: 37.6872, longitude: -122.0808, name: 'San Francisco' }
                ]
            }
        }
    ]
});

map.appendTo('#map');

Common Patterns

常用模式

Pattern 1: Data Visualization with Color Mapping

模式1：带颜色映射的数据可视化

Use color mapping when displaying data that varies across regions (population, revenue, etc.):

Choose mapping type: range, equal, or desaturation
Define data source and property mapping
Configure color ranges for visual representation
Enable legends for clarity

当展示跨区域变化的数据（人口、营收等）时使用颜色映射：

选择映射类型：区间、等值、去饱和度
定义数据源与属性映射
配置颜色区间实现可视化展示
启用图例提升可读性

Pattern 2: Multi-Layer Maps

模式2：多层地图

Combine multiple data sources using layers:

Create separate layers for different data types
Use markers for specific locations
Overlay bubbles for aggregated data
Combine with color mapping for regions

使用图层组合多个数据源：

为不同数据类型创建独立图层
使用标记标注特定点位
叠加气泡展示聚合数据
结合区域颜色映射能力

Pattern 3: Interactive User Experience

模式3：交互式用户体验

Enhance map interactivity:

Add tooltips for hover information
Enable selection highlighting
Implement custom events (click, double-click)
Provide zoom and pan controls

增强地图交互性：

为悬停场景添加提示框信息
启用选择高亮
实现自定义事件（点击、双击）
提供缩放与平移控制

Pattern 4: Navigation & Route Planning

模式4：导航与路线规划

Show connections between locations:

Use navigation lines to draw routes
Add markers at key waypoints
Include distance or duration information
Style routes distinctly

展示点位之间的连接：

使用导航线绘制路线
在关键途经点添加标记
包含距离或时长信息
为路线设置独特样式

Key Features at a Glance

核心特性速览

Feature	Purpose	Use When
Markers	Point locations	Marking specific addresses or coordinates
Bubbles	Sized data points	Showing relative magnitude of data
Polygons	Region shading	Highlighting geographical areas
Color Mapping	Data visualization	Displaying regional statistics or metrics
Layers	Data organization	Managing multiple data sources
Navigation Lines	Route visualization	Showing connections or journeys
Legends	Visual reference	Explaining colors, sizes, or symbols
Annotations	Custom overlays	Adding labels or custom content
Tooltips	Hover information	Providing context on hover
State Persistence	User experience	Remembering user's viewport/settings

特性	用途	适用场景
标记（Markers）	标注点位	标记特定地址或坐标
气泡（Bubbles）	可变大小数据点	展示数据的相对量级
多边形（Polygons）	区域着色	高亮地理区域
颜色映射（Color Mapping）	数据可视化	展示区域统计数据或指标
图层（Layers）	数据组织	管理多个数据源
导航线（Navigation Lines）	路线可视化	展示连接或行程
图例（Legends）	视觉参考	说明颜色、大小或符号含义
注释（Annotations）	自定义覆盖层	添加标签或自定义内容
提示框（Tooltips）	悬停信息	悬停时提供上下文信息
状态持久化（State Persistence）	用户体验	记忆用户的视口/设置

Next Steps

后续步骤

Choose your starting reference based on your immediate need
Follow the implementation examples provided
Combine features as needed for your use case
Refer to troubleshooting guide if you encounter issues

根据你的即时需求选择对应的参考文档
按照提供的实现示例操作
根据你的使用场景按需组合特性
如果遇到问题可参考故障排查指南