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

npm install @baidumap/react-bmap

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

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

import { BMapProvider } from '@baidumap/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 '@baidumap/react-bmap';

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

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

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

<Map center={{ lng: 116.404, lat: 39.915 }} zoom={12} style={{ width: '100%', height: 500 }}>
  <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 '@baidumap/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}
      style={{ width: '100%', height: 500 }}
      onClick={(e) => setPoints((prev) => [...prev, e.point])}
    >
      {points.map((p, i) => (
        <Marker key={i} position={p} />
      ))}
    </Map>
  );
}

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

import { Map, useMapRef } from '@baidumap/react-bmap';

// 子组件在 <Map> 内部，才能通过 useMapRef 读到地图上下文
function FlyButton() {
  const map = useMapRef();
  return <button onClick={() => map?.flyTo({ lng: 116.404, lat: 39.915 }, 15)}>飞到天安门</button>;
}

function FlyToDemo() {
  return (
    <Map center={{ lng: 116.404, lat: 39.915 }} zoom={12} style={{ width: '100%', height: 500 }}>
      <FlyButton />
    </Map>
  );
}

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