组合式函数集成第三方 sdk 应封装加载、初始化、状态管理、错误处理与资源清理全链路，用缓存 promise 避免重复加载和竞态，ref 存实例、reactive 管状态，按功能拆分 usemapinstance/usemapcontrol/usemapmarkers，强化 typescript 类型支持。
在组合式函数中集成第三方 SDK，关键不是“加载完就用”，而是把加载、初始化、状态管理、错误处理和资源清理全链路收束到一个可复用、可测试、响应式的逻辑单元里。它不是写个 onMounted 里 new 一个地图实例那么简单。
封装加载逻辑，避免重复与竞态
第三方 SDK（如百度地图 GL、Google Maps JS API）通常依赖全局脚本加载，且只应加载一次。直接在组件里动态插入 script 容易引发重复加载、多组件并发请求、或加载未完成就调用的竞态问题。
- 用一个带缓存的 Promise 封装加载过程，例如
loadBMapGL(ak)返回已 resolve 的同一实例，后续调用直接复用 - 加载失败时 reject 并提供明确错误信息（比如 AK 无效、网络超时、BMapGL 未挂载），方便上层统一提示或降级
- 不依赖
index.html硬编码 script，确保开发、测试、微前端等环境可控
用 reactive 或 ref 管理 SDK 实例与状态
SDK 实例本身不是响应式对象，但它的状态（如地图中心、缩放级别、标注列表）需要被 Vue 响应式系统追踪，才能驱动视图更新。
- 用
ref(null)存 SDK 实例引用，便于后续调用方法（如mapRef.value.setCenter()） - 用
reactive({ center: { lng: 0, lat: 0 }, zoom: 12 })管理可变状态，配合 watch 同步到 SDK，也支持双向绑定（如拖拽后自动更新 center） - 避免把整个 BMapGL 对象塞进 reactive —— 它含大量非数据属性，会触发不必要的依赖收集
按功能拆分组合函数，职责清晰
一个地图组件往往包含定位、标注、绘制、事件监听等多个能力。不要把所有逻辑揉进一个 useMap 里，而是分层抽象：
-
useMapInstance：专注加载、初始化、销毁（onUnmounted中清除监听器、释放 DOM 引用） -
useMapControl：封装缩放、平移、地图类型切换等控制逻辑 -
useMapMarkers：管理标注增删改、聚合、点击交互，接收markersprop 并响应式同步 - 每个函数只暴露必要的返回值（实例、状态、操作函数），不泄露内部实现细节
类型安全与 TypeScript 友好设计
第三方 SDK 往往缺乏完整类型定义，或类型分散难维护。组合函数是补全类型的最佳位置。
- 为加载函数返回明确类型，如
Promise<typeof bmapgl></typeof>，配合declare module 'BMapGL'补充全局类型 - props 接口与 SDK 配置项对齐（如
mapOptions: BMapGL.MapOptions），让 IDE 提示可用字段 - 事件回调参数使用 SDK 原生类型（如
BMapGL.MouseEvent），而非 any
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
