| name | tencentmap-jsapi-gl-skill |
| description | 腾讯地图 JavaScript GL（JSAPIGL）开发指南。适用于地图应用或者工具的编写。在编写、审查或调试使用腾讯地图 API的代码时应运用此技能。适用于涉及地图初始化、覆盖物展示、图层控制、事件处理、控件交互、可视化渲染、地图工具、检索、路线规划、查地址、行政区划、ip定位、几何计算、三维模型展示、性能优化的任务。当用户提及 腾讯地图、 jsapi、jsapi-gl或相关地图开发需求时自动触发。 |
| version | 1.0.2 |
| metadata | {"openclaw":{"requires":{"bins":[""],"env":["TMAP_JSAPI_KEY"]},"primaryEnv":"TMAP_JSAPI_KEY"}} |
腾讯地图JSAPI GL开发技能
帮助用户使用腾讯地图 JavaScript API GL 进行地图功能开发，包含基础地图功能和数据可视化功能。
目录结构
API 文档
示例代码
前置检查：API Key
有 Key（env 变量 TMAP_JSAPI_KEY 或 ~/.tencentmap/tempkey.json）直接使用；无 Key 时向用户输出以下选项：
用户选择"申请临时 Key" → 读取 tempkey-guide.md 按其中步骤执行
工作流程
1. 理解用户需求
当用户询问腾讯地图API相关问题时：
- 明确用户需要的功能类型（基础地图/可视化）
- 确定具体要使用的类或功能
2. 查询 API 文档
在 references/jsapigl/docs/ 或 references/visualization/docs/ 中查找相关API文档：
- 搜索关键词（如"点标记"、"热力图"）
- 阅读对应类的说明、配置参数、方法
3. 查找示例代码
在对应 demos 目录中查找示例：
- JS API示例：
references/jsapigl/demos/
- 可视化示例：
references/visualization/demos/
- 示例命名格式：
功能分类_具体示例.html
4. 提供解决方案
根据文档和示例，为用户提供：
使用示例
用户问题: "如何在地图上添加标记点？"
执行流程:
- 读取
references/jsapigl/docs/点标记.md 了解 MultiMarker API
- 查看
references/jsapigl/demos/ 中的点标记相关示例
- 提供完整的代码示例和说明
用户问题: "怎么画一个热力图？"
执行流程:
- 读取
references/visualization/docs/热力图.md 了解 Heat API
- 查看
references/visualization/demos/ 中的热力图示例
- 说明数据格式和配置选项
快速开始模板
基础地图初始化：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>腾讯地图示例</title>
<script src="https://map.qq.com/api/gljs?v=3&key={TMAP_JSAPI_KEY}"></script>
</head>
<body>
<div id="map" style="width:100%;height:500px;"></div>
<script>
var map = new TMap.Map("map", {
zoom: 12,
center: new TMap.LatLng(39.984104, 116.307503)
});
</script>
</body>
</html>
可视化图层示例（热力图）：
var heat = new TMap.visualization.Heat({
radius: 50,
height: 100,
gradientColor: {
0: '#13B06A',
0.4: '#13B06A',
0.8: '#E9AB1D',
0.9: '#E9AB1D',
1: '#E05649'
}
}).addTo(map);
heat.setData([
{ lat: 39.984104, lng: 116.307503, count: 100 },
{ lat: 39.984504, lng: 116.307803, count: 80 }
]);
注意事项
JS API GL
- 版本: 当前为 GL 版本，支持3D地图和WebGL渲染
- 浏览器兼容: 现代浏览器，IE11+（需polyfill）
- 坐标系: 使用 gcj02 坐标系
- 地图创建（重要）: 地图创建的容器一定要有固定宽高，尤其是flex布局下
- API使用（重要）: 所有功能的API调用都必须使用文档中出现的接口、属性、事件，不能自己编造；
- API传参（重要）: 所有的API传入参数必须严格遵守api文档中说明的格式，如果不确定就去看看对应demo，包括demo中的数据格式；
- 附加库的使用: 使用附加库需要在API加载URL中添加
libraries 参数
| 附加库 | libraries 值 | 命名空间 | 说明 |
|---|
| 地图工具 | tools | TMap.tools | 几何编辑器、测量工具 |
| 几何计算库 | geometry | TMap.geometry | 距离/面积计算、几何关系判断 |
| 服务类库 | service | TMap.service | 地点搜索、路线规划、行政区划等 |
| 地图视角附加库 | view | TMap (扩展方法) | 观察者视角操作地图 |
| 模型库 | model | TMap.model | GLTF/3DTiles/3DMarker 模型 |
| 天气图层 | weather | TMap.weather | 云图、温度图等气象图层 |
| 矢量数据图层 | vector | TMap.vector | GeoJSON/MVT 矢量数据图层 |
| 可视化库 | visualization | TMap.visualization | 可视化API的能力 |
使用示例：
<script src="https://map.qq.com/api/gljs?v=1&libraries=tools,geometry,service,model&key={TMAP_JSAPI_KEY}"></script>
可视化 API
- 数据格式: 可视化图层需要特定格式的数据输入
- 性能: 大数据量时注意性能优化
- 层级: 可视化图层可以设置显示层级
- 事件: 支持点击、悬停等交互事件
- API使用（重要）: 所有功能的API调用都必须使用文档中出现的接口、属性、事件，不能自己编造
- API传参（重要）: 所有的API传入参数必须严格遵守api文档中说明的格式，如果不确定就去看看对应demo，包括demo中的数据格式；
最佳实践
- 模块化加载: 使用模块化方式按需加载API
- 错误处理: 添加地图加载失败的处理逻辑
- 内存管理: 及时销毁不需要的图层和覆盖物
- 性能优化: 大数据集使用聚合或抽稀
