@baidumap/jsapi-loader

百度地图 JSAPI 加载器。用一行 load() 统一加载 3.0 / GL / 4.0，自动处理异步回调、代理密钥、以及 SPA 场景下的脚本单次加载。

特性

• 统一入口，一个 version 参数切换 3.0 / gl / 4.0
• SPA 友好：多处/多次调用 load()，脚本只注入一次（模块级单例）
• 内置代理模式（serviceHost），密钥不暴露在前端
• 支持创建地图前需全局声明的配置：apiVersion / uiVersion / coordType
• 完善的错误提示、超时与失败重试
• 提供 TypeScript 类型声明

安装

npm i @baidumap/jsapi-loader

快速开始

import BMapLoader from '@baidumap/jsapi-loader';

BMapLoader.load({
  ak: '您的AK',
  version: '4.0'
}).then((BMap) => {
  const map = new BMap.Map('container');
  map.centerAndZoom(new BMap.Point(116.404, 39.915), 15);
});

load() resolve 出对应版本的命名空间对象：3.0 / 4.0 为 window.BMap，gl 为 window.BMapGL（4.0 下二者相等）。

参数

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | ak | string | — | 开发者密钥。非代理模式必填 | | version | '3.0' \| 'gl' \| '4.0' | '4.0' | JSAPI 版本 | | serviceHost | string | — | 代理模式服务地址（末尾需带 /）。设置后启用代理，URL 不携带 ak | | protocol | 'https' \| 'http' | 'https' | 协议 | | timeout | number | 0 | 加载超时(ms)，0 表示不超时 | | globalConfig | object | — | 创建地图前需在全局命名空间声明的配置，见下 |

globalConfig

apiVersion / uiVersion / coordType 都是 BMapGL.xxx 形式的全局声明，必须在 new Map() 之前设置。加载器会在 resolve 之前自动写入命名空间对象。

| 字段 | 说明 | |------|------| | apiVersion | 4.0 下回退 API 行为，如 'gl' | | uiVersion | 4.0 下回退 UI 样式，如 'gl' | | coordType | 全局坐标系标识，如 'bd09ll' / 'gcj02' |

BMapLoader.load({
  ak: '您的AK',
  version: '4.0',
  globalConfig: { apiVersion: 'gl', uiVersion: 'gl', coordType: 'bd09ll' }
});

版本对照

| version | 入口 URL | 命名空间 | |---------|----------|----------| | 3.0 | …/api?v=3.0&ak=xxx | window.BMap | | gl | …/api?v=1.0&type=webgl&ak=xxx | window.BMapGL | | 4.0 | …/api?v=4.0&ak=xxx | window.BMap（=== window.BMapGL） |

代理模式

将 AK 配置在服务端，前端不再传递 AK，避免密钥泄露。设置 serviceHost 后，加载器会自动声明 window._BMapSecurityConfig，并通过代理地址加载 JSAPI 及后续所有服务请求（瓦片、检索等）。

BMapLoader.load({
  version: '4.0',
  serviceHost: 'https://your-domain.com/_BMapService/' // 末尾 "/" 必需，且不传 ak
});

服务端需将 /_BMapService 反向代理到 https://api.map.baidu.com 并注入 ak。详见官方代理模式文档。

SPA 场景

加载器内部维护模块级单例状态。页面切换、组件多次挂载时反复调用 load()：

• 加载中的并发调用返回同一个 Promise；
• 加载完成后的调用直接返回已缓存的命名空间对象；

脚本始终只注入一次。注意：同一页面只能加载一个版本，若二次调用传入不同 version 或不同 ak 会被拒绝。

API

• load(options?) → Promise<Namespace>：加载并返回命名空间对象。
• reset() → void：清空内部状态并移除全局对象，便于单测与热更新。
• getStatus() → 'notload' | 'loading' | 'loaded' | 'failed'：查询当前状态。

License

MIT