l7-mapkit

name

l7-mapkit

description

React components for AntV L7 geospatial visualization. Use when building maps, geospatial visualizations, or location-based UIs with React. Covers GaodeMapScene, MapScene, PointLayer, LineLayer, PolygonLayer, HeatmapLayer, RasterLayer, ImageLayer, Marker, Popup, Control, CustomControl, and Legend components. Triggers on map visualization, geospatial data, choropleth, heatmap, scatter plot on map, route visualization, image overlay, map controls, or any L7-related React component usage.

L7 MapKit Skill

React components for AntV L7 geospatial visualization library.

npm 包名: @antv/l7-mapkit 当前版本: 0.2.0 安装: npm install @antv/l7-mapkit

注意：安装时请使用 ^0.2.0 或 latest，早期版本（如 0.1.0）可能存在问题。

Quick Start

import { GaodeMapScene, PointLayer } from '@antv/l7-mapkit';

function App() {
  const data = {
    type: 'FeatureCollection',
    features: [
      { type: 'Feature', geometry: { type: 'Point', coordinates: [120.19, 30.26] }, properties: { value: 80 } },
    ],
  };

  return (
    <GaodeMapScene
      style={{ width: '100%', height: '400px' }}
      mapConfig={{ zoom: 10, center: [120.19, 30.26] }}
    >
      <PointLayer
        source={data}
        colorField="value"
        colorValues={['#fee5d9', '#fc4e2a', '#800026']}
        size={8}
        shape="circle"
        onClick={(e) => console.log(e.feature.properties)}
      />
    </GaodeMapScene>
  );
}

Core Concepts

Flat Props API

All layer components use flat props for visual mapping and event binding:

<PointLayer
  source={data}
  colorField="value"
  colorValues={['red', 'blue']}
  sizeField="count"
  sizeValues={[5, 20]}
  onClick={handleClick}
/>

Component Composition

Components nest inside Scene components:

<GaodeMapScene>
  <PointLayer />      {/* Data layers */}
  <LineLayer />
  <Marker />          {/* Interactive components */}
  <Popup />
  <Control />         {/* Map controls */}
  <CustomControl>
    <MyLegend />
  </CustomControl>
</GaodeMapScene>

Scene Components

GaodeMapScene

高德地图容器。必须在最外层包裹所有地图组件。在 WeaveFox 场景下无需配置高德地图 Key，已内置。

<GaodeMapScene
  style={{ width: '100%', height: '400px' }}
  mapConfig={{
    zoom: 10,
    center: [120.19, 30.26],
    style: 'light',      // 'light' | 'dark' | 'normal'
    pitch: 0,
    rotation: 0,
  }}
  onLoaded={(scene) => console.log('Map loaded')}
  onClick={(e) => console.log(e.lngLat)}
>
  {/* children */}
</GaodeMapScene>

Props:

• style / className: Container styles
• mapConfig: Map configuration (zoom, center, style, pitch, rotation)
• sceneConfig: L7 Scene configuration
• onLoaded: Scene loaded callback
• onClick / onMouseMove / onZoomChange: Scene events

MapScene

内置地图容器，无第三方依赖。

<MapScene
  style={{ width: '100%', height: '400px' }}
  mapConfig={{ zoom: 10, center: [120.19, 30.26] }}
>
  {/* Same children as GaodeMapScene */}
</MapScene>

Layer Components

All layers share these common props:

Prop	Type	Description
source	any	Required. GeoJSON, array, or URL
sourceConfig	object	Parser config { parser: { type: 'json', x: 'lng', y: 'lat' } }
color	string	Fixed color
colorField	string	Color mapping field
colorValues	string[] | fn	Color mapping values
size	number	Fixed size (px)
sizeField	string	Size mapping field
sizeValues	number[] | fn	Size mapping range [min, max]
shape	string	Shape type
style	object	Layer style { opacity, stroke, strokeWidth }
visible	boolean	Show/hide layer
zIndex	number	Layer stacking order
onClick	fn	Click event
onMouseEnter	fn	Mouse enter event
onLoaded	fn	Layer loaded callback

PointLayer

<PointLayer
  source={data}
  colorField="value"
  colorValues={['#fee5d9', '#fc4e2a', '#800026']}
  size={8}
  shape="circle"        // 'circle' | 'square' | 'triangle' | 'hexagon' | 'pentagon' | 'octogon' | 'hexagram' | 'rhombus' | 'vesica'
/>

Shapes:

• 几何形状: circle, square, triangle, hexagon, pentagon, octogon, hexagram, rhombus, vesica
• 3D 柱状: cylinder, triangleColumn, hexagonColumn, squareColumn
• 文字: text (配合 shapeField 使用)
• 图标: 通过 LoadImage 加载后引用

🌟 性能提示: 若使用简单的圆点，建议用 simple 代替 circle 以获得更好的性能。

LineLayer

<LineLayer
  source={geojson}
  color="#1890ff"
  size={2}
  shape="line"          // 'line' | 'arc' | 'arc3d' | 'greatcircle'
  style={{ opacity: 0.8 }}
/>

PolygonLayer

<PolygonLayer
  source={geoData}
  shape="fill"          // 'fill' | 'extrude'
  colorField="value"
  colorValues={['#edf8e9', '#006d2c']}
  style={{ opacity: 0.6 }}
  active               // Enable hover highlight
/>

Shapes:

• fill: 平面填充（默认）
• extrude: 3D 挤出，需配合 size 设置高度

HeatmapLayer

<HeatmapLayer
  source={points}
  colorValues={['#f7fbff', '#08306b']}
  shape="heatmap"       // 'heatmap' | 'heatmap3d' | 'hexagon' | 'grid'
/>

ImageLayer

<ImageLayer
  source={{
    data: '/images/overlay.png',
    bounds: [73, 3, 135, 53]  // [minLng, minLat, maxLng, maxLat]
  }}
  style={{ opacity: 0.8 }}
/>

Interactive Components

Marker

// Default marker
<Marker longitude={120.19} latitude={30.26} />

// Custom content
<Marker longitude={120.19} latitude={30.26} onClick={handleClick}>
  <div style={{ background: 'red', borderRadius: '50%', width: 24, height: 24 }} />
</Marker>

// Draggable
<Marker longitude={120.19} latitude={30.26} option={{ draggable: true }} />

Popup

<Popup longitude={120.19} latitude={30.26} closeButton onClose={handleClose}>
  <div style={{ padding: 12 }}>
    <h4>Location Name</h4>
    <p>Description here</p>
  </div>
</Popup>

MarkerLayer

Batch markers with clustering:

<MarkerLayer
  data={[{ longitude: 120.19, latitude: 30.26, name: 'A' }]}
  cluster
  clusterOption={{ radius: 80, maxZoom: 16 }}
  renderMarker={(item) => {
    const el = document.createElement('div');
    el.textContent = item.name;
    return el;
  }}
/>

Controls

Built-in Control

<Control type="zoom" position="topleft" />
<Control type="scale" position="bottomleft" />
<Control type="layerSwitch" position="topright" />
<Control type="fullscreen" position="topright" />
<Control type="geoLocate" position="topright" />
<Control type="mapTheme" position="topright" />
<Control type="mouseLocation" position="bottomright" />
<Control type="exportImage" position="topright" />

Positions: topleft, topright, bottomleft, bottomright

CustomControl

<CustomControl position="topright">
  <div style={{ background: 'white', padding: 12, borderRadius: 4 }}>
    <h4>Legend</h4>
    <div><span style={{ color: '#f00' }}>●</span> High</div>
    <div><span style={{ color: '#00f' }}>●</span> Low</div>
  </div>
</CustomControl>

Hooks

useScene

import { useScene } from '@antv/l7-mapkit';

function MyComponent() {
  const scene = useScene();
  useEffect(() => {
    scene.fitBounds([[120, 30], [121, 31]]);
  }, [scene]);
  return null;
}

useLayer

import { useLayer } from '@antv/l7-mapkit';

function LayerEnhancement() {
  const layer = useLayer();
  useEffect(() => {
    layer.setBlend('normal');
  }, [layer]);
  return null;
}

// Usage
<PointLayer source={data}>
  <LayerEnhancement />
</PointLayer>

Legend Components

import { LegendCategories, LegendRamp } from '@antv/l7-mapkit';

// Categorical legend
<LegendCategories
  items={[
    { color: '#f00', label: 'Category A' },
    { color: '#0f0', label: 'Category B' },
  ]}
/>

// Gradient legend
<LegendRamp
  colors={['#fee5d9', '#fc4e2a', '#800026']}
  labels={['Low', 'Medium', 'High']}
/>

Data Format

GeoJSON (Recommended)

const data = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [120.19, 30.26] },
      properties: { value: 100, name: 'Hangzhou' },
    },
  ],
};

<PointLayer source={data} colorField="value" sizeField="value" />

JSON Array with Parser

const data = [
  { lng: 120.19, lat: 30.26, value: 100 },
];

<PointLayer
  source={data}
  sourceConfig={{ parser: { type: 'json', x: 'lng', y: 'lat' } }}
  colorField="value"
/>

Common Patterns

See references/patterns.md for detailed examples:

• Choropleth map (分级统计图)
• Scatter plot on map (地图散点)
• Route visualization (路径可视化) - line, arc, arc3d, greatcircle, flowline
• Heatmap density (热力密度) - heatmap, hexagon
• Image overlay with annotations (图片标注) - LoadImage + shapeField
• Clustered markers (聚合标注)
• Multi-layer composition (多图层组合)
• Interactive filtering (交互过滤)
• Dynamic data updates (动态数据)

API Reference

See the following reference files for complete props documentation:

• references/scene.md - Scene 组件 (GaodeMapScene, MapScene)
• references/layers.md - 图层组件 (PointLayer, LineLayer, PolygonLayer, HeatmapLayer, RasterLayer, ImageLayer)
• references/interactive.md - 交互组件 (Marker, Popup, MarkerLayer, LoadImage)
• references/controls.md - 控件组件 (Control, CustomControl, ZoomControl, ScaleControl, FullscreenControl, GeoLocateControl, MapThemeControl, MouseLocationControl, ExportImageControl)
• references/legends.md - 图例组件 (LegendCategories, LegendRamp, LegendProportion, LegendIcon)
• references/hooks.md - Hooks (useScene, useLayer)