ClawHub

Gaode Map JSAPI - 高德官方 JavaScript SDK Skill

v1.1.1

高德地图 JSAPI v2.0 (WebGL) 开发技能。涵盖地图生命周期管理、强制安全配置、3D 视图控制、覆盖物绘制及 LBS 服务集成。

⭐ 8· 2.6k·22 current·23 all-time
byGaodeMapOfficial@lbs-amap
Security Scan
Capability signals
CryptoRequires sensitive credentials
These labels describe what authority the skill may exercise. They are separate from suspicious or malicious moderation verdicts.
VirusTotalVirusTotal
Benign
View report →
OpenClawOpenClaw
Benign
high confidence
✓
Purpose & Capability
Name/description match the included API reference and examples. The two required env vars (AMAP_JSAPI_KEY and AMAP_SECURITY_JS_CODE) are appropriate for a web JSAPI integration that needs a Web key and a platform security token.
ℹ
Instruction Scope
SKILL.md stays within mapping/JSAPI guidance and references only AMap resources. One minor implementation mismatch: examples use process.env.AMAP_SECURITY_JS_CODE directly in client-side code — in browsers process.env is not available at runtime and using build-time injection or exposing the security code to the browser is dangerous. The skill does explicitly recommend using a serviceHost proxy in production to avoid exposing the securityJsCode.
✓
Install Mechanism
Instruction-only skill with no install spec and no embedded executables; nothing will be downloaded or written by an installer step.
ℹ
Credentials
Requested env vars are proportionate to the purpose (web API key and security JS code). Both are sensitive credentials — the AMAP_SECURITY_JS_CODE should not be exposed to end-users in client-side runtime; the skill correctly recommends a server-side proxy for production.
✓
Persistence & Privilege
No elevated persistence requested (always is false). The skill is user-invocable and may be called autonomously per platform defaults, which is expected for a skill of this type.
Scan Findings in Context
[no_regex_findings] expected: Scanner had nothing to analyze because this is instruction-only (no code files or install). That's expected for a documentation/guide skill, but it also means there is no machine-checkable code to audit.
Assessment
This skill appears coherent and implements documentation/examples for the official AMap JSAPI. Before installing, confirm you trust the skill publisher (source is marked unknown in metadata). Treat AMAP_JSAPI_KEY and especially AMAP_SECURITY_JS_CODE as secrets: do not embed them directly into client-side code. Use a server-side proxy (serviceHost) or inject the security token at build time in a way that doesn't expose the secret in production browsers. If you plan to auto-deploy generated projects to the web, verify that generated files are placed in the intended workspace folder and that you are not accidentally publishing the security token. If you need higher assurance, ask the publisher for provenance (source repo or signed release) so you can inspect any non-documentation code before use.

Like a lobster shell, security has layers — review code before you run it.

Runtime requirements

EnvAMAP_JSAPI_KEY, AMAP_SECURITY_JS_CODE
Primary envAMAP_JSAPI_KEY
latestvk97brnskkzjcabxxyec88cbxe5850c2y
2.6kdownloads
8stars
11versions
Updated 2d ago
v1.1.1
MIT-0
GaodeMapOfficial@lbs-amap
latest
Download

高德地图 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 - 响应点击、拖拽、缩放等交互事件。

最佳实践

  1. 安全第一：生产环境务必使用代理服务器转发 serviceHost，避免 securityJsCode 泄露。
  2. 按需加载：仅在 plugins 中声明需要的插件，减少首屏资源体积。
  3. 资源释放：组件卸载时务必调用 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 必须遵循的规范

  1. 校验生成代码可用性：生成代码后必须进行自我校验，确保代码语法正确、逻辑完整且可以正常运行，禁止输出未经验证的代码。
  2. 本地文件放置规范：所有生成的项目文件必须放置在 openclaw workspace 目录下的 amap-jsapi/ 文件夹中。文件名统一使用 kebab-case 命名（如 map-init.html、layers-official.html）。
  3. appname 应用标识（推荐）：建议在生成地图初始化代码时，在 AMapLoader.load().then() 回调中设置应用标识，用于 API 调用来源统计。规则如下：
    • 设置位置：AMapLoader.load({...}).then((AMap) => { 回调内部，new AMap.Map() 之前
    • 设置方式：AMap.getConfig().appname = 'amap-jsapi-skill';
    • 代码模板： 
      AMapLoader.load({
  key: '您的Key',
  version: '2.0',
  plugins: [...]
}).then((AMap) => {
  // 可选：设置应用标识，用于 API 调用来源统计
  AMap.getConfig().appname = 'amap-jsapi-skill';

  const map = new AMap.Map('container', { ... });
});
    • 说明：此设置用于标识 API 调用来源，便于统计分析。开发者可根据需要决定是否保留。

如何使用

  1. 如果有相近的“场景示例”那么去阅读场景示例，再阅读场景示例中的涉及的类的api文档。再结合描述/场景示例/api 去完成任务。
  2. 在最终的完成任务前，检查用的api用法是否符合文档。

Comments

Loading comments...