@zero-bits/amap

企业级高精度、高拓展性的 React 高德地图 (AMap) 组件库。

基于 @amap/amap-jsapi-loader 与 React Hooks 构建，专注于解决复杂大屏业务、千万级轨迹动画渲染、以及严苛的 React 闭包性能难题。

核心特性

• ⚡️ 极致性能：底层彻底摒弃无脑 Re-render，引入高级引用代理，规避了 instance.on/off 重复绑定的性能深渊。
• 🛡️ 内存安全：杜绝了 React useEffect 闭包卸载陷阱，保证一切地图资源按需销毁，实现真正的零内存泄露。
• 🧩 React Portal 挂载：Marker 完美支持复杂的 React JSX 节点渲染，状态流转浑然一体。
• 🚀 海量轨迹渲染：深度封装 PathSimplifier 引擎，轻松应对大屏设备上的百万级流光轨迹渲染与巡航动画。
• 📦 异步稳态：所有 Utils 与 SDK Loader 使用稳健的异步状态机，彻底消除异步时序导致的白屏、空指针异常。

安装与引入

确保你已经在项目中安装了高德基础类型支持：

npm install @amap/amap-jsapi-loader @amap/amap-jsapi-types
npm install @zero-bits/amap

基础使用指南

1. 基础加载与地图渲染 (Loader & AmapMap)

任何地图组件必须包裹在 Loader 与 AmapMap 内。AmapMap 采用了原生 Context 下发实例，支持随处使用。

import React from 'react';
import { Loader, AmapMap } from '@zero-bits/amap';

export default function App() {
  return (
    <Loader amapKey="你的_AMAP_KEY" securityCode="你的安全密钥">
      <AmapMap
        style={{ width: '100vw', height: '100vh' }}
        zoom={11}
        center={[116.397428, 39.90923]}
        viewMode="3D"
        mapStyle="amap://styles/dark" // 支持自定义地图样式
      >
        {/* 其他地图组件放置于此 */}
      </AmapMap>
    </Loader>
  );
}

2. 标记点 (Marker)

利用 React Portal 技术，你可以直接将任何 React 组件、甚至是包含状态的组件写在 <Marker> 里，无需拼写 HTML 字符串。

import { Marker } from '@zero-bits/amap';
import { Button } from 'antd'; // 可自由使用 UI 库组件

export default function MyMap() {
  return (
    <Marker 
      position={[116.397428, 39.90923]} 
      offset={[-20, -20]}
      onClick={(e) => console.log('Marker被点击', e)}
    >
      <div className="custom-marker-node">
        <div className="pulse-dot" />
        <span>北京总部</span>
        <Button size="small">查看详情</Button>
      </div>
    </Marker>
  )
}

3. 高性能轨迹流光动画 (PathSimplifier)

用于展示交通路网流光、车辆历史轨迹等海量点位巡航功能。

import { useRef, useEffect } from 'react';
import { PathSimplifier } from '@zero-bits/amap';

const trajectoryData = [
  {
    name: "车辆 A 历史轨迹",
    path: [ [116.4, 39.9], [116.45, 39.95], [116.5, 39.9] ]
  }
];

export default function Demo() {
  const pathRef = useRef(null);

  useEffect(() => {
    // 你可以直接操作底层导航器实例，控制巡航
    pathRef.current?.start('car_1'); 
  }, []);

  return (
    <PathSimplifier
      ref={pathRef}
      data={trajectoryData}
      getPath={(d) => d.path}
      getHoverTitle={(d) => d.name}
      autoSetFitView={true}
      navigators={[
        { id: 'car_1', pathIndex: 0, loop: true, speed: 5000 }
      ]}
      renderOptions={{
        pathLineStyle: { lineWidth: 6, strokeStyle: '#1890ff' }
      }}
    />
  );
}

4. 静态图层 (TileLayer)

轻松引入高德官方内置的路况图、卫星图、路网图，支持响应式切换。

import { TileLayer } from '@zero-bits/amap';

export default function Layers() {
  return (
    <>
      {/* 卫星图 */}
      <TileLayer.Satellite zIndex={10} />

      {/* 实时路况图 */}
      <TileLayer.Traffic autoRefresh={true} interval={180} zIndex={11} />

      {/* 路网图层 */}
      <TileLayer.RoadNet zIndex={12} />
    </>
  )
}

5. 地图控件 (Control)

内置官方类型控件与完全自定义的 DOM 控件。

import { Control } from '@zero-bits/amap';

export default function Controls() {
  return (
    <>
      {/* 官方自带：地图类型切换 */}
      <Control.MapType position="RT" defaultType={1} showRoad={true} />

      {/* 自定义控件：悬浮在左下角的图例 */}
      <Control.Custom position="LB">
        <div style={{ background: '#fff', padding: 12, borderRadius: 4 }}>
          <h4>业务图例</h4>
          <ul>
            <li>🔴 故障设备</li>
            <li>🟢 正常设备</li>
          </ul>
        </div>
      </Control.Custom>
    </>
  )
}

6. 基础折线 (Trajectory)

如果你仅需要画一条静态的线而不需要强大的渲染引擎，使用基础的 Trajectory 即可。

import { Trajectory } from '@zero-bits/amap';

<Trajectory
  path={[ [116.4, 39.9], [116.45, 39.95] ]}
  options={{
    strokeColor: '#ff0000',
    strokeWeight: 8,
    strokeOpacity: 0.8
  }}
  fitView={true}
/>

7. 搜索输入框聚合 (AutoComplete)

高德自动提示搜索服务的 React 封装，传入你的原生 input 元素 ID 即可实现地点搜索。

import { AutoComplete } from '@zero-bits/amap';

export default function SearchBar() {
  return (
    <div>
      <input id="my-search-box" placeholder="请输入地点..." />
      <AutoComplete 
        input="my-search-box"
        city="全国"
        onSelect={(e) => {
          console.log('用户选择了：', e.poi.name, e.poi.location);
        }} 
      />
    </div>
  )
}

高阶工具函数 Utils

本库不仅提供了组件，还提供了健壮的异步 API 封装。无需操心高德插件是否加载完成，所有方法返回安全的 Promise：

import { search, getAddressByLngLat, districtSearch } from '@zero-bits/amap/src/utils';

async function mapToolsDemo() {
  // 1. 根据关键字进行服务搜索
  const { status, result } = await search('天安门');

  // 2. 逆地理编码（经纬度 -> 真实地址）
  const address = await getAddressByLngLat(116.39, 39.9);

  // 3. 行政区划查询 (获取省份下辖的城市、边界等)
  const boundaries = await districtSearch('北京市');
}