高德地图 JSAPI v2.0 开发技能
本指南包含地图初始化、覆盖物、事件、图层等核心模块的 API 说明和代码示例，旨在帮助开发者快速集成高德地图并遵循正确的使用方式。
快速开始
1. 引入加载器
使用 script 标签加载 loader.js：
<script src="https://webapi.amap.com/loader.js"></script>
2. 安全密钥配置 (强制)
重要：自 v2.0 起，必须在加载地图前配置安全密钥，否则无法通过鉴权。详情及后端代理示例请参考 安全策略。
> 安全提示：安全密钥属于敏感凭据，请通过环境变量 AMAP_SECURITY_JS_CODE 传入，禁止在代码中硬编码。生产环境务必使用 serviceHost 代理方式，避免前端暴露密钥。
// 在调用 AMapLoader.load 前执行
window._AMapSecurityConfig = {
securityJsCode: process.env.AMAP_SECURITY_JS_CODE, // 通过环境变量安全获取
// serviceHost: 'https://your-proxy-domain/_AMapService', // 生产环境：建议使用代理转发
};
3. 初始化地图
import AMapLoader from '@amap/amap-jsapi-loader';
AMapLoader.load({
key: '您的Web端开发者Key', // 必填
version: '2.0', // 指定版本
plugins: ['AMap.Scale', 'AMap.ToolBar'] // 预加载插件
}).then((AMap) => {
// 可选：设置应用标识，用于 API 调用来源统计
AMap.getConfig().appname = 'amap-jsapi-skill';
const map = new AMap.Map('container', {
viewMode: '3D', // 开启3D视图
zoom: 11, // 初始缩放级别
center: [116.39, 39.90] // 初始中心点
});
map.addControl(new AMap.Scale());
}).catch(e => console.error(e));
场景示例
地图控制
- 生命周期：
references/map-init.md- 掌握load、Map实例创建及destroy销毁流程。 - 视图交互：
references/view-control.md- 控制zoom(缩放)、center(平移)、pitch(俯仰)、rotation(旋转)。
覆盖物绘制
- 点标记：
references/marker.md- 使用Marker(基础)、LabelMarker(海量避让) 标注位置。 - 矢量图形：
references/vector-graphics.md- 绘制Polyline(轨迹、线)、Polygon(区域、面)、Circle(范围、圆)。 - 信息展示：
references/info-window.md- 通过InfoWindow展示详细信息。 - 右键菜单：
references/context-menu.md- 自定义地图或覆盖物的右键交互。
图层管理
- 基础图层：
references/layers.md- 标准、卫星、路网及 3D 楼块图层。 - 自有数据：
references/custom-layers.md- 集成Canvas、WMS/WMTS,GLCustomLayer地图上叠加 Canvas、WMS图层、 Threejs图层。
服务与插件
- LBS 服务：
references/geocoder.md- 地理编码/逆地理编码（地址/坐标互转）。references/routing.md- 路径规划（驾车/步行/公交）。references/search.md- POI 搜索与输入提示。
- 事件系统：
references/events.md- 响应点击、拖拽、缩放等交互事件。
最佳实践
- 安全第一：生产环境务必使用代理服务器转发
serviceHost，避免securityJsCode泄露。 - 按需加载：仅在
plugins中声明需要的插件，减少首屏资源体积。 - 资源释放：组件卸载时务必调用
map.destroy()，防止 WebGL 上下文内存泄漏。
API Reference
JSAPI 文档分为以下几个类别：
Foundation Classes
LngLat / Bounds / Pixel / Size
Information Window
InfoWindow
Events
Event
Map
Map / MapsEvent
Official Layers
TileLayer / Traffic / Satellite / RoadNet / Buildings / DistrictLayer / IndoorMap
Standard Layers
WMS / WMTS / MapboxVectorTileLayer
Custom Layers
HeatMap / VectorLayer / LabelsLayer / CustomLayer / Flexible / ImageLayer / CanvasLayer / GLCustomLayer
Markers
Marker / Text / Icon / LabelMarker / ElasticMarker / MarkerCluster / MassMarks / MoveAnimation / AnimationCallback / EasingCallback
Context Menu
ContextMenu
Vector Graphics
Polygon / Polyline / BezierCurve / Circle / CircleMarker / Ellipse / Rectangle / GeoJSON
Overlay Groups
LayerGroup / OverlayGroup
Controls
Control / Scale / ToolBar / ControlBar / MapType / HawkEye
Tools
RangingTool / MouseTool / PolygonEditor / PolylineEditor / CircleEditor / BezierCurveEditor / EllipseEditor / RectangleEditor
Services
WebService / WebServiceCallback
Search
AutoComplete / AutoCompleteSearchCallback / PlaceSearch / searchCallback / CloudDataSearch / CloudDataSearchCallback
Geocoder
Geocoder / GeocoderCallback / ReGeocoderCallback / convertFrom
Routing
Driving / DrivingCallback / DrivingResult / DriveStepBasic / DriveStepDetail / TruckDriving / Walking / WalkingCallback / WalkingResult / Transfer / TransferCallback / TransferResult / Riding / RidingCallback / RidingResult / DragRoute / DragRouteTruck / GraspRoad / GraspRoadCallback
Other Services
DistrictSearch / Weather / WeatherLiveResult / WeatherForecastResult / StationSearch / LineSearch
Geolocation
Geolocation / GeolocationCallBack / GeolocationResult / CitySearch
Common Library
GeometryUtil / DomUtil / Browser / Util
使用 skills 必须遵循的规范
- 校验生成代码可用性：生成代码后必须进行自我校验，确保代码语法正确、逻辑完整且可以正常运行，禁止输出未经验证的代码。
- 本地文件放置规范：所有生成的项目文件必须放置在 openclaw workspace 目录下的
amap-jsapi/文件夹中。文件名统一使用 kebab-case 命名（如map-init.html、layers-official.html）。 -
appname 应用标识（推荐）：建议在生成地图初始化代码时，在
AMapLoader.load().then()回调中设置应用标识，用于 API 调用来源统计。规则如下：
- 设置位置：AMapLoader.load({...}).then((AMap) => {回调内部，new AMap.Map()之前
- 设置方式：AMap.getConfig().appname = 'amap-jsapi-skill';
- 代码模板：
```javascript
AMapLoader.load({
key: '您的Key',
version: '2.0',
plugins: [...]
}).then((AMap) => {
// 可选：设置应用标识，用于 API 调用来源统计
AMap.getConfig().appname = 'amap-jsapi-skill';const map = new AMap.Map('container', { ... });
});
```
- 说明：此设置用于标识 API 调用来源，便于统计分析。开发者可根据需要决定是否保留。如何使用
- 如果有相近的“场景示例”那么去阅读场景示例，再阅读场景示例中的涉及的类的api文档。再结合描述/场景示例/api 去完成任务。
- 在最终的完成任务前，检查用的api用法是否符合文档。
