JSAPI GL 开发指南
百度地图 JSAPI WebGL 版本开发指南。包含地图初始化、覆盖物、事件、图层等核心模块的 API 说明和代码示例,旨在帮助开发者快速集成百度地图并遵循正确的使用方式。
边界与版本
- 本 skill 只负责浏览器前端代码。直接获取地点、路线、地址或天气答案时使用
baidu-map(本连接器 MCP 工具);服务端调用代码使用baidu-map-webapi。 - 默认使用 BMapGL:加载
https://api.map.baidu.com/api?v=1.0&type=webgl&...,命名空间为BMapGL。 - 仅当用户明确要求 JSAPI 3.0,或现有项目已经使用 3.0 时,才沿用
BMapJS。不得在同一实现中混用BMapGL与BMapJS。
AK 来源
本 skill 需要浏览器端 AK:
- 优先读取环境变量
BMAP_JSAPI_KEY。 - 无值时,按
references/get-ak.md引导用户在控制台创建浏览器端 AK,不要自行编造或复用服务端 AK。 - 需要个性化底图样式时,
style_id只能由用户在开放平台控制台创建后提供,不得猜测。
若用户只要求审查代码、解释 API 或提供不执行的结构示例,且任务不需要真实运行,不要为了填充示例而创建 AK。交付可运行页面时不得写入假 AK 或遮掩后的 AK。
何时适用
在以下场景中参考这些指南:
- 创建新的地图页面或组件
- 在地图上添加标注、折线、多边形等覆盖物
- 处理地图交互事件(点击、拖拽、缩放等)
- 配置地图样式或切换图层
- 调试地图渲染或性能问题
快速参考
0. 基础概念
references/base-classes.md- 基础类:Point、Bounds、Size、Pixel、Iconreferences/constants.md- 通用常量:搜索状态码、POI 类型
1. 地图
references/map-init.md- 地图初始化:资源引入、创建实例、配置选项、交互与视图控制
2. 地图覆盖物
references/overlay-common.md- 覆盖物通用操作:添加/移除、显示/隐藏、批量清除references/marker.md- 点标记:构造参数、位置/图标/旋转/置顶/拖拽方法references/polyline.md- 折线:构造参数、线条样式、坐标操作、编辑模式references/polygon.md- 多边形:构造参数、边框/填充样式、带孔多边形、编辑模式references/circle.md- 圆形:构造参数、中心点/半径、样式设置、编辑模式references/custom-overlay.md- 自定义覆盖物:DOM 创建、属性传递、事件绑定、旋转控制references/info-window.md- 信息窗口:构造参数、内容/尺寸设置、最大化、与 Marker 配合使用
3. 事件
references/map-events.md- 地图事件:绑定方式、交互事件、视图变化事件、生命周期事件references/overlay-events.md- 覆盖物事件:通用事件、拖拽事件、矢量图形事件
4. 地图样式
references/map-style.md- 个性化地图:自定义地图外观(颜色、显隐),实现深色主题、简洁地图等效果
5. 图层服务
references/xyz-layer.md- 第三方图层:加载 XYZ/TMS/WMS/WMTS 标准瓦片references/mvt-layer.md- 矢量瓦片:加载 MVT/PBF 格式瓦片,支持样式表达式、特征交互、状态管理
6. 路径规划
references/route-common.md- 通用配置:构造参数、渲染选项、回调函数、数据结构、状态常量references/driving-route.md- 驾车:策略枚举、途经点、路况、收费、拖拽references/walking-route.md- 步行:转向类型、拖拽references/riding-route.md- 骑行:骑行搜索references/transit-route.md- 公交:市内/跨城策略、交通方式、换乘
7. 其他LBS服务
references/local-search.md- 本地检索:普通/范围/周边检索、结果处理、翻页、POI 数据结构references/geocoder.md- 地理编码:正地理编码(地址→坐标)、逆地理编码(坐标→地址)references/convertor.md- 坐标转换:GPS/高德/谷歌坐标转百度坐标
文档使用顺序
- 常用且稳定的实现模式先读取上面的本地
references/文件。 - 本地 reference 未覆盖的精确参数、返回字段、限制、错误码或版本差异,明确告知用户需以百度地图开放平台官方文档为准。不得用未经核实的记忆补齐精确字段。
参考文件路径相对于本 SKILL.md:
references/map-init.md
每个参考文件包含:
- 功能简要说明
- 完整代码示例及解释
- API 参数说明和注意事项
AK 故障排查
references/get-ak.md- 当浏览器端 AK 缺失、失效或白名单不匹配时读取


