Vue-BMap 为 Vue 3 项目提供了一套百度地图组件与组合式函数，覆盖地图、标注、路线、图层等常见能力，方便 Vue 开发者快速集成地图功能。

npm install @baidumap/vue-bmap

仅支持 Vue 3（vue 为 peer 依赖，>=3.3）。组件库会自动加载地图脚本，无需在 index.html 手动引入 <script>。在百度地图开放平台申请一个浏览器端 ak 密钥即可使用，申请流程可参考开发前准备。

BMapProvider 负责加载地图脚本并把密钥、版本传递给子组件，通常放在应用最外层，只需写一次。

<script setup>
import { BMapProvider } from '@baidumap/vue-bmap';
</script>

<template>
  <BMapProvider ak="您的密钥" version="4.0">
    <App />
  </BMapProvider>
</template>

• version="4.0"（默认）：WebGL 三维地图，支持旋转、俯仰、3D

• version="3.0"：传统 2D 地图，更轻量

Map 必须有确定的宽高，容器没有高度时地图不会显示。

<script setup>
import { Map } from '@baidumap/vue-bmap';
</script>

<template>
  <Map :center="{ lng: 116.404, lat: 39.915 }" :zoom="12" style="width: 100%; height: 500px" />
</template>

覆盖物、控件都作为 Map 的子元素声明：

<script setup>
import { Map, Marker, InfoWindow, NavigationControl, ScaleControl } from '@baidumap/vue-bmap';
</script>

<template>
  <Map :center="{ lng: 116.404, lat: 39.915 }" :zoom="12" style="width: 100%; height: 500px">
    <Marker :position="{ lng: 116.404, lat: 39.915 }" />
    <InfoWindow :position="{ lng: 116.404, lat: 39.915 }" content="天安门" />
    <NavigationControl />
    <ScaleControl />
  </Map>
</template>

原生 JSAPI 增删标注要手动调用 map.addOverlay() / map.removeOverlay() 命令式维护一份和地图状态脱节的引用列表。Vue-BMap 里标注只是响应式数据的映射，增删改直接改数据，不需要自己同步覆盖物的生命周期：

<script setup>
import { ref } from 'vue';
import { Map, Marker } from '@baidumap/vue-bmap';

const points = ref([{ lng: 116.404, lat: 39.915 }]);
const addPoint = (e) => points.value.push(e.point);
</script>

<template>
  <Map :center="{ lng: 116.404, lat: 39.915 }" :zoom="12" style="width: 100%; height: 500px" @click="addPoint">
    <Marker v-for="(p, i) in points" :key="i" :position="p" />
  </Map>
</template>

多数覆盖物、控件、图层组件都遵循这个模式：props 描述当前状态，组件内部负责与 JSAPI 实例同步，卸载时自动清理。只有在需要主动触发命令式行为（比如飞到某个坐标、读取地图截图）时，才需要在 Map 内部的子组件里通过 useMapRef() 拿到底层句柄：

<!-- FlyButton.vue：子组件在 <Map> 内部，才能通过 useMapRef 读到地图上下文 -->
<script setup>
import { useMapRef } from '@baidumap/vue-bmap';

const map = useMapRef();
</script>

<template>
  <button @click="map?.flyTo({ lng: 116.404, lat: 39.915 }, 15)">飞到天安门</button>
</template>

<!-- 父组件：把 FlyButton 放进 <Map> 内 -->
<script setup>
import { Map } from '@baidumap/vue-bmap';
import FlyButton from './FlyButton.vue';
</script>

<template>
  <Map :center="{ lng: 116.404, lat: 39.915 }" :zoom="12" style="width: 100%; height: 500px">
    <FlyButton />
  </Map>
</template>

Vue-BMap 还提供了检索类组合式函数（驾车/步行/公交路线、地理编码、地点检索等）和完整的覆盖物、控件、图层组件，覆盖大部分 JSAPI 4.0 的能力。完整的组件清单、API 细节和更多示例可参考 vue-bmap 文档。如果想共建源码或者提出issue，可以到 vue-bmap github 仓库 联系我们。