腾讯地图小程序开发技能

## 目录结构

### API 文档

所有API文档位于 `references/` 目录：

#### 地图组件文档
- **references/map_component_guide.md** - 完整的小程序地图组件文档
  - 地图基础属性：longitude、latitude、scale、rotate、skew等
  - 标记点（marker）：在地图上显示标注，支持自定义图标、气泡、标签
  - 路线（polyline）：绘制路线和彩虹线，支持箭头、文本标注
  - 多边形（polygon）：绘制闭合区域，支持虚线边框
  - 圆形（circle）：显示圆形覆盖物
  - 点聚合：大量标记点的聚合展示
  - 自定义气泡：callout、customCallout
  - 地图事件：点击、视野变化、标记点点击等
  - 碰撞检测：marker碰撞关系配置
  - 地图控件：指南针、比例尺、3D楼块等

#### MapContext API文档
`references/mapContext_api/` 目录包含32个API文档：

**地图控制类**
- MapContext.md - MapContext总览
- wx.createMapContext.md - 创建MapContext实例
- MapContext.getCenterLocation.md - 获取地图中心点坐标
- MapContext.moveToLocation.md - 移动到指定位置
- MapContext.getRegion.md - 获取地图视野范围
- MapContext.getScale.md - 获取地图缩放级别
- MapContext.getRotate.md - 获取地图旋转角度
- MapContext.getSkew.md - 获取地图倾斜角度
- MapContext.setCenterOffset.md - 设置地图中心点偏移
- MapContext.setBoundary.md - 限制地图显示范围
- MapContext.includePoints.md - 缩放视野包含所有坐标点

**标记点管理类**
- MapContext.addMarkers.md - 添加标记点
- MapContext.removeMarkers.md - 移除标记点
- MapContext.translateMarker.md - 平移标记点（带动画）
- MapContext.moveAlong.md - 沿路径移动标记点（轨迹回放）
- MapContext.setLocMarkerIcon.md - 设置定位点图标

**点聚合类**
- MapContext.initMarkerCluster.md - 初始化点聚合配置
- MapContext.addMarkers.md - 添加聚合标记点

**覆盖物类**
- MapContext.addGroundOverlay.md - 添加自定义图片图层
- MapContext.updateGroundOverlay.md - 更新自定义图片图层
- MapContext.removeGroundOverlay.md - 移除自定义图片图层
- MapContext.addArc.md - 添加弧线
- MapContext.removeArc.md - 移除弧线

**可视化图层类**
- MapContext.addVisualLayer.md - 添加可视化图层
- MapContext.removeVisualLayer.md - 移除可视化图层
- MapContext.executeVisualLayerCommand.md - 执行可视化图层指令

**自定义图层类**
- MapContext.addCustomLayer.md - 添加个性化图层
- MapContext.removeCustomLayer.md - 移除个性化图层

**坐标转换类**
- MapContext.toScreenLocation.md - 经纬度转屏幕坐标
- MapContext.fromScreenLocation.md - 屏幕坐标转经纬度

**其他功能**
- MapContext.openMapApp.md - 拉起地图APP选择导航
- MapContext.eraseLines.md - 擦除或置灰已添加的线段
- MapContext.on.md - 监听地图事件

#### 位置服务API文档
`references/wx_location_api/` 目录包含12个API文档：

**基础定位**
- wx.getLocation.md - 获取当前的地理位置、速度
- wx.getFuzzyLocation.md - 获取模糊位置（隐私保护）

**地图选点**
- wx.chooseLocation.md - 打开地图选择位置
- wx.choosePoi.md - 选择POI点

**位置展示**
- wx.openLocation.md - 使用内置地图查看位置

**持续定位**
- wx.startLocationUpdate.md - 开启小程序前后台时均接收位置消息
- wx.startLocationUpdateBackground.md - 开启小程序进入前后台时均接收位置消息
- wx.stopLocationUpdate.md - 停止接收位置消息
- wx.onLocationChange.md - 监听实时地理位置变化事件
- wx.onLocationChangeError.md - 监听实时地理位置错误事件
- wx.offLocationChange.md - 取消监听实时地理位置变化事件
- wx.offLocationChangeError.md - 取消监听实时地理位置错误事件

#### 后端服务文档
后端服务能力统一通过 wx.request 直连腾讯位置服务 WebService API，全参数自由调用（文档位于 `references/webservice/`，调用方式见工作流程「1. 理解用户需求」）：

- `webservice/capability_matrix.md` - 场景指南（场景一~五、前置条件、示例代码、错误码、最佳实践）
- `webservice/advanced-services.md` - 五个场景之外的高级与专项服务索引（需申请开通的能力、开通方式与工单模板）
- `webservice/api-geocoder.md` / `webservice/api-search.md` / `webservice/api-direction.md` / `webservice/api-location-weather.md` / `webservice/api-tools.md` - 直连参数文档（与 tencentmap-webservice-skill 同步）

### 示例代码

`assets/examples/` 目录包含3个小程序示例项目：

#### minicode-location/ - 定位功能示例
获取用户位置并在地图上标记

#### minicode-marker/ - 标记点示例
添加自定义标记点与气泡

#### minicode-markerCluster/ - 点聚合示例
大量标记点的聚合展示

每个示例目录下提供工程骨架（app.js / app.json / index/index.js 等），
页面结构（`.wxml`）与样式（`.wxss`）源码以代码块形式内联在该目录的 `README.md` 中，
使用时按文件名复制到对应路径即可组成完整可运行项目。

## 工作流程

### 1. 理解用户需求

当用户询问小程序地图相关问题时，首先明确：
- **功能类型**：地图显示、定位、标记点、路线规划、搜索、地图控制等
- **平台**：微信小程序
- **是否需要后端服务**：判断是否需要调用腾讯位置服务API（POI搜索、路线规划、地理编码、天气、IP定位、坐标转换等）。需要时统一通过 wx.request 直连 WebService API，按 `references/webservice/` 下文档给完整示例。
  超出这些场景时（货车路线、地址验真、室内/海外搜索、排线调度、AI 搜等），
  读 `references/webservice/advanced-services.md` 查是否有对应的高级服务接口（多为需申请开通的服务）。

### 2. Key 处理（需要后端服务时）

按此顺序自动获取 Key：`Client(key=...)` → `~/.tencentmap/tempkey.json`。各来源的 Key 会全部进入候选池。

1. **用户提供 Key**——先调用 `client.save_key("<key>")` 保存到本地配置，再执行主任务。保存后该 Key 自动进入候选池首位，后续请求无需再传。
2. **本地无可用 Key**——读取 `tempkey-guide.md`，按流程引导用户申请临时体验 Key（申请成功后由 `save_config.py` 持久化到 `~/.tencentmap/tempkey.json`）。
3. **Key 报错**——调用 `client.switch_key()` 轮询候选池切换到下一个可用 Key，并告知用户切换情况；全部不可用时，说明每个 Key 的失败原因与修正方式。

### 2.5 前置检查：可视化图层 layerId（涉及可视化图层时）

当用户需求涉及**可视化图层接口**（`MapContext.addVisualLayer` / `MapContext.removeVisualLayer` / `MapContext.executeVisualLayerCommand`）时：

1. **首先检查用户是否已提供 layerId**。layerId 是可视化图层 ID，由用户在腾讯位置服务控制台创建获得，**无法猜测或凭空生成**。
2. **用户未提供 layerId → 必须先向用户询问获取，不得擅自使用占位符或编造值**。展示以下话术：

   > 可视化图层需要 `layerId`（可视化图层 ID），在腾讯位置服务控制台创建图层后获得：
   > - 创建可视化图层（获得 layerId）：https://lbs.qq.com/dev/console/layers/layerEdit
   > - 图层创建后还需满足两个前置条件：
   >   1. map 组件需配置 `subkey` 参数，且该 subkey 与 layerId 绑定；
   >   2. 需在[图层绑定页面](https://lbs.qq.com/dev/console/layers/layerBind)授权当前小程序 APPID，否则真机调用会失败。
   >
   > 请提供您的 layerId（以及已绑定它的 subkey，若与默认不同）。

3. **用户提供 layerId 后**：确认 `subkey` 已配置、告知用户在图层绑定页面完成 APPID 授权（如未完成），再进入代码编写。
4. **代码中不得硬编码占位符**（如 `YOUR_LAYER_ID`），应使用用户提供的实际值。

### 3. 查询 API 文档

根据需求类型读取对应的 references 文件：

- **地图显示/组件相关** → 读取 `references/map_component_guide.md`
- **地图控制/MapContext** → 读取 `references/mapContext_api/` 下对应文件
- **可视化图层** → 读取 `references/mapContext_api/MapContext.addVisualLayer.md`、`MapContext.removeVisualLayer.md`、`MapContext.executeVisualLayerCommand.md`、`MapContext.on.md`（visualLayerEvent 事件）
- **定位和用户位置相关** → 读取 `references/wx_location_api/` 下对应文件
- **LBS后端服务（WebService 直连）** → 读取 `references/webservice/capability_matrix.md` 确认场景 → 读取 `references/webservice/` 下对应 `api-*.md`

对于大文件，使用 grep 搜索关键信息，例如marker：
```bash
grep -n "marker\|标记点" references/map_component_guide.md
```

### 4. 查找示例代码

根据需求在 `assets/examples/` 目录查找对应示例：

- **定位功能** → `assets/examples/minicode-location/`
- **标记点功能** → `assets/examples/minicode-marker/`
- **点聚合功能** → `assets/examples/minicode-markerCluster/`
- **可视化图层** → 暂无对应示例项目，以 `references/mapContext_api/` 下的 addVisualLayer 文档为准

读取示例代码的关键文件：
```bash
# 查看页面逻辑与工程骨架
cat assets/examples/minicode-marker/index/index.js

# 查看页面结构（.wxml）与样式（.wxss）源码
cat assets/examples/minicode-marker/README.md
```

### 5. 提供解决方案

根据文档和示例，为用户提供：
- 完整的代码示例（WXML + JS + WXSS）
- API参数详细说明
- 注意事项和最佳实践
- 权限处理建议


## 注意事项

### 地图组件

1. **坐标系**：
   - 小程序地图使用 **GCJ-02**（国测局坐标，火星坐标）
   - `wx.getLocation({ type: 'gcj02' })` 直接返回GCJ-02坐标
   - GPS设备返回的WGS-84坐标需要转换

2. **组件尺寸**：
   - `<map>` 标签建议设置宽高

3. **个性化地图**：
   - 需要在微信公众平台购买并配置
   - 使用 `subkey` 参数传入专属KEY
   - 使用 `layer-style` 指定样式

4. **权限声明**：
   - 自2022年7月14日后发布的小程序，使用位置接口需在 `app.json` 中声明
   ```json
   {
     "permission": {
       "scope.userLocation": {
         "desc": "你的位置信息将用于小程序位置接口的效果展示"
       }
     }
   }
   ```

5. **API规范（非常重要）**：
   - 所有API调用必须使用文档中定义的接口、属性、事件
   - 所有参数必须严格遵守文档格式要求
   - 不确定的参数格式请查阅对应demo

### 位置服务

1. **调用频率限制**：
   - 基础库 2.17.0 起，`wx.getLocation` 增加调用频率限制
   - 避免高频率调用，推荐使用持续定位接口

2. **高精度定位**：
   - 开启高精度定位会增加接口耗时
   - 可设置 `highAccuracyExpireTime` 控制超时时间

3. **持续定位**：
   - 使用 `wx.onLocationChange` 进行持续定位
   - 页面卸载时调用 `wx.stopLocationUpdate` 停止定位

### 腾讯位置服务后端服务

1. **申请Key**：读取 `tempkey-guide.md` 按其中步骤执行

2. **商业授权**：
   - 商业使用需要授权（政府公共事务及公益组织除外）
   - 详见腾讯位置服务官网说明

3. **前置条件**（域名白名单、Key 白名单策略）见 `references/webservice/capability_matrix.md`「1. 直连前置条件」

4. **错误码**：直连返回完整 WebService 状态码（110/112/113/120/121/190/199 等），对照 `references/webservice/capability_matrix.md` 错误处理章节

5. **签名校验**：开启签名校验的 Key 直连需按 WebService 签名规范自行计算 sig 并随请求传递

6. **配额**：直连使用 WebService 配额体系

### 性能优化

1. **标记点优化**：
   - 标记点过多时使用点聚合功能
   - 及时移除不需要的标记点

2. **数据更新**：
   - 避免频繁 `setData` 更新地图数据
   - 使用 `setting` 对象批量更新属性

3. **路线优化**：
   - 路线点位过多时进行抽稀处理
   - 使用 `polyline` 的 `colorList` 绘制彩虹线

4. **内存管理**：
   - 及时移除不需要的图层和覆盖物
   - 页面卸载时清理地图资源

详细的快速开始指南、常见场景和最佳实践，参见 `quick_start_and_best_practices.md`。

## 相关链接

- [微信小程序地图组件文档](https://developers.weixin.qq.com/miniprogram/dev/component/map.html)
- [微信小程序位置API文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.getLocation.html)
- [腾讯位置服务官网](https://lbs.qq.com/)
- [微信小程序地图插件使用指南](https://developers.weixin.qq.com/miniprogram/dev/framework/plugin/using.html)
- [腾讯位置服务WebService API文档](https://lbs.qq.com/service/webService/webServiceGuide/webServiceOverview)