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

npm install react-bmap

需要 React 18+（react / react-dom 为 peer 依赖）。在百度地图开放平台申请一个浏览器端 ak 密钥即可使用，申请流程可参考开发前准备。

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

import { BMapProvider } from 'react-bmap';

function Root() {
  return (
    <BMapProvider ak="您的密钥" version="4.0">
      <App />
    </BMapProvider>
  );
}

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

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

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

import { Map } from 'react-bmap';

<div style={{ width: '100%', height: 500 }}>
  <Map center={{ lng: 116.404, lat: 39.915 }} zoom={12} />
</div>

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

import { Map, Marker, InfoWindow, NavigationControl, ScaleControl } from 'react-bmap';

<Map center={{ lng: 116.404, lat: 39.915 }} zoom={12}>
  <Marker position={{ lng: 116.404, lat: 39.915 }} />
  <InfoWindow position={{ lng: 116.404, lat: 39.915 }} content="天安门" />
  <NavigationControl />
  <ScaleControl />
</Map>

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

import { useState } from 'react';
import { Map, Marker } from 'react-bmap';

function ClickToAddMarker() {
  const [points, setPoints] = useState([{ lng: 116.404, lat: 39.915 }]);

  return (
    <Map
      center={{ lng: 116.404, lat: 39.915 }}
      zoom={12}
      onClick={(e) => setPoints((prev) => [...prev, e.point])}
    >
      {points.map((p, i) => (
        <Marker key={i} position={p} />
      ))}
    </Map>
  );
}

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

import { useRef } from 'react';
import { Map, type MapRef } from 'react-bmap';

function FlyToDemo() {
  const mapRef = useRef<MapRef>(null);

  return (
    <>
      <button onClick={() => mapRef.current?.flyTo({ lng: 116.404, lat: 39.915 })}>飞到天安门</button>
      <Map ref={mapRef} center={{ lng: 116.404, lat: 39.915 }} zoom={12} />
    </>
  );
}

React-BMap 还提供了检索类 Hook（驾车/步行/公交路线、地理编码、地点检索等）和完整的覆盖物、控件、图层组件，覆盖大部分 JSAPI 4.0 的能力。完整的组件清单、API 细节和更多示例可参考 react-bmap 仓库文档。