@uiw/react-amap

The MassMarks component is designed for scenarios requiring the display of a very large number of markers on an AMap map. It optimizes performance for high-density data points.

You can import it from the main package or install it separately:

import { MassMarks } from '@uiw/react-amap';
// OR
import { MassMarks } from '@uiw/react-amap-mass-marks';

The library provides a React wrapper for the AMap (Gaode Maps) SDK. It uses an APILoader component to automatically load the AMap SDK via script tags.

For most common use cases, you can use the provided high-level components (like Map and various controls). For complex requirements, the Map component provides access to the underlying AMap instance, allowing you to perform any action supported by the native AMap API.

Key Features:

• Automatic SDK loading (including third-party SDKs).
• Full TypeScript support with AMap SDK type definitions.
• Supports React Hooks (requires React 16.8+).
• Zero dependencies on other component libraries.
• Modular architecture (split into multiple packages for on-demand use).

The InfoWindow component is used to pop up a detailed information window on the map. Note that the map only allows one InfoWindow to be displayed at a time.

You can install it via the main package or separately:

npm install @uiw/react-amap
# or
npm install @uiw/react-amap-info-window

import { InfoWindow } from '@uiw/react-amap';
// or
import { InfoWindow } from '@uiw/react-amap-info-window';

The AutoComplete component provides a way to implement location search suggestions. You can either use the default UI provided by the Amap JS API (which automatically listens to input events on a specified element) or manually trigger AMap.AutoComplete.search based on your own form control events.

To use it, you can import it from the main @uiw/react-amap package or install @uiw/react-amap-auto-complete separately.

import { AutoComplete } from '@uiw/react-amap';
// OR
import { AutoComplete } from '@uiw/react-amap-auto-complete';

The useMapContext hook allows you to access the map, container, and AMap objects throughout your component tree without manually passing them as props. This is useful for building custom components that need direct access to the AMap instance.

When using useMapContext, you can destructure the following from the context:

• AMaps: The global AMap object (accessible via state.AMaps).
• map: The current map instance (accessible via state.map).
• container: The HTML container element (accessible via state.container).
• state: The current state object.
• dispatch: A dispatch function for state updates.

import { useMapContext } from '@uiw/react-amap';

const MyComponent = () => {
  const { AMaps, map, container, state, dispatch } = useMapContext();
  // Use AMaps, map, etc. to interact with the map
  return null;
};

You can define the text content of a Text component by passing children. Note that if you provide children, the text prop will be ignored.

<Text
  anchor="center"
  position={new AMap.LngLat(116.396923, 39.918203)}
>
  <div style={{ color: 'red' }}>
    Custom HTML content
  </div>
</Text>

If you provide children to the Marker component, the icon property will be overridden. This allows you to render arbitrary React components (like custom divs with background images or interactive buttons) as the marker itself.

<Marker position={new AMap.LngLat(116.205467, 39.907761)}>
  <div style={{ background: 'red', color: '#fff' }}>
    Custom Marker Content
  </div>
</Marker>

When you need to add thousands of point markers to a map, LabelMarker is a better choice than the standard Marker. Unlike MassMarks, LabelMarker can render both icons and text information, and maintains good performance even with tens of thousands of data points. It also supports collision avoidance (avoidance/避让) features via the rank property and JSAPI 2.0 capabilities.

To use it, you can import it from the main @uiw/react-amap package or install and use @uiw/react-amap-marker separately.

import { LabelMarker } from '@uiw/react-amap';
// OR
import { LabelMarker } from '@uiw/react-amap-marker';

CircleMarker is used to create circular overlays on the map that act as dot markers.

Key Difference from Circle: Unlike the Circle class (which is a vector graphic that changes size relative to the map scale), CircleMarker maintains a constant size in pixels regardless of the map zoom level.

You can import it from the main package or install it separately:

import { CircleMarker } from '@uiw/react-amap';
// or
import { CircleMarker } from '@uiw/react-amap-circle-marker';

import { CircleMarker } from '@uiw/react-amap';

<CircleMarker
  center={new AMap.LngLat(116.407394, 39.904211)}
  radius={10}
  fillColor='rgba(0,0,255,1)'
  fillOpacity={0.5}
/>

To render only the text without an icon, set the icon prop to null.

import { Map, APILoader, LabelMarker } from '@uiw/react-amap';

<LabelMarker 
  visible={true}
  name="No Icon"
  icon={null}
  text={{
    content: 'Text only',
    direction: 'top',
    offset: [0, 0],
    style: {
      strokeColor: '#ffffff',
      fontSize: 14,
      fillColor: '#60666E',
      strokeWidth: 4,
      backgroundColor: 'rgba(0,0,0,0)',
    },
  }}
  position={[116.466994, 39.984904]}
/>

The Map component is the foundation of the library. It provides the map, container, and AMap objects to all child components via React Context.

Requirements:

1. The <Map> component must be wrapped in an <APILoader> component to load the AMap SDK.
2. Other map components (like markers, polylines, etc.) must be used as children of <Map>.
3. The parent container of the <Map> component must have a defined width and height, otherwise the map may fail to render.

To use it, import Map and APILoader from @uiw/react-amap (or Map from @uiw/react-amap-map).

import { Map, APILoader } from '@uiw/react-amap';

const Demo = () => (
  <div style={{ width: '100%', height: '300px' }}>
    <APILoader akey="YOUR_AMAP_AKEY">
      <Map />
    </APILoader>
  </div>
);

export default Demo;

If you are contributing to or developing with the source code of the @uiw/react-amap repository, use the following commands:

• npm install: Install project dependencies.
• npm run build: Compile all packages.
• npm run start: Run the documentation website.
• npm run watch:amap: Watch for changes in JS and .d.ts type file compilation outputs.