地理可视化组件

aimapui

触发条件： 用户需要创建地图、地图可视化、地理数据展示时，必须使用此 skill。覆盖 AiMap 容器、6 种基础图层（Point/Line/Polygon/Heatmap/Raster/Image）、13 种复合图层（行政区划下钻/气泡/路径/弧线流向/图标/字标/聚合/蜂窝/填充/卫星/GeoTIFF/H3/PMTiles）、15 种控件。特殊控件：DrawControl（交互绘制）、ImageCalibrationControl（图片配准/地图校准）、AnnotationControl（标注）。

Version

见 frontmatter version 字段。当前：@antv/aimapui / @antv/aimapui-cli → 0.4.4

Install

npm install @antv/aimapui @antv/l7
# or
pnpm add @antv/aimapui @antv/l7

注意: @antv/l7 版本必须 ≥ 2.29.1，低于此版本会导致部分功能异常（如控件渲染、动态 import 等）。

> **注意:** 使用组件前必须引入样式文件 `import '@antv/aimapui/style.css'`，否则控件、弹窗、图例等样式不生效。

### CDN 引用（IIFE）

```html
<script src="https://unpkg.com/@antv/l7"></script>
<script src="https://unpkg.com/@antv/aimapui/dist/index.iife.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@antv/aimapui/dist/style.css" />

Quick Start

import { AiMap, PointLayer } from '@antv/aimapui';
import '@antv/aimapui/style.css';

<AiMap map={{ basemap: 'gaode', center: [121.4, 31.2], zoom: 12, style: 'dark' }} autoFit>
  <PointLayer
    source={data}
    sourceType="json"
    sourceConfig={{ x: 'lng', y: 'lat' }}
    color="#5B8FF9"
    size={8}
    shape="circle"
  />
</AiMap>

🔑 Weavefox 场景 Token 说明：在内网 / Weavefox 环境中，高德底图（basemap: 'gaode'）无需手动设置 token —— 组件内置默认 token 可用，且访问域名已在高德侧加入白名单。直接按 Quick Start 的写法省略 token 字段即可。仅当使用 Mapbox / 天地图 / 百度 / 腾讯 / Google 等其余底图时，才需要自行申请并传入 token。

Architecture

• AiMap — Container component, manages Scene/Map lifecycle; supports autoFit for automatic viewport fitting
• Layers — 6 base types: PointLayer, LineLayer, PolygonLayer, HeatmapLayer, RasterLayer, ImageLayer。⚠️ 必须用 aimapui 封装的 React 组件（声明式、生命周期托管、含 schema/autoFit/EventBus）；禁止绕过去 new L7 同名图层类 + scene.addLayer() 重新实现（这 6 个类名与 L7 同名，from '@antv/l7' 会拿到原生图层类）
• Composite Layers — Business-ready (13 types): BubbleLayer, RouteLayer, ArcFlowLayer, IconLayer, GlyphLayer, ChinaDistrict, MarkerClusterLayer, HexagonLayer, FillLayer, SatelliteLayer, TiffRasterLayer, H3Layer, PMTilesLayer
• Controls — ZoomControl, ResetViewControl, ScaleControl, FullscreenControl, GeoLocateControl, MapThemeControl, MouseLocationControl, ExportImageControl, LayerSwitchControl, LegendControl, LogoControl, SatelliteLayerControl, DrawControl, ImageCalibrationControl, AnnotationControl (15 types, 12 positions)
• Layer Comparison — LayerCompare（独立容器，非 <AiMap> 内控件）：双屏 / 卷帘对比，内部创建两个 L7 场景并以领航者机制逐帧双向同步相机
• Interactions — Marker, Popup, Tooltip + Maki icon utilities (makiIconUrl, makiPinUrl, createMakiIconMap, createMakiPinMap, MAKI_ICONS, MAKI_ICON_NAMES)
• Legends — LegendCategories, LegendRamp, LegendDiverging, LegendThreshold, LegendSize, LegendLineWidth, LegendProportion, LegendIcon (8 types)
• Mobile — BottomSheet, MobileToolbar, MobileSheetLegend, SearchBar
• Hooks — useResponsive, useScene, useMapPosition, useMapControl, useEventBus, useTheme
  • ⚠️ useScene() / onSceneReady 拿到的是 L7 Scene，可用 setCenter/setZoom/setPitch/setRotation/setZoomAndCenter/fitBounds/panTo/zoomIn/zoomOut 等通用方法；没有 flyTo、easeTo、jumpTo 等 mapbox/maplibre 原生方法（调用会报 is not a function）。「定点飞行」用 scene.setZoomAndCenter(zoom, [lng, lat]) 或 setCenter+setZoom 组合。详见 aimap-container.md 的 Scene 操作方法 小节。
• Utilities — ErrorBoundary, ResponsiveProvider, ThemeProvider, EventBus
• Schema Mode — Render entire map from a single AiMapSchema JSON object
• Build Formats — ESM, CJS, IIFE (CDN), TypeScript declarations
• @antv/aimapui-plot — Separate package for tactical plot/bindtype components (PlotControl, PlotToolbar)

Reference Docs (load as needed)

Common Mistakes

Key Patterns

Visual Mapping (数据驱动样式)

所有图层支持 固定值 和 字段映射 两种模式：

// 固定值
<PointLayer source={data} color="#5B8FF9" size={12} />

// 字段映射
<PointLayer colorField="type" colorValues={['#f00','#0f0','#00f']} sizeField="value" sizeValues={[4,20]} />

详见 → mapping.md

Schema Mode (AI/JSON 驱动地图)

用单个 JSON 对象渲染完整地图，适合 AI 生成或配置化场景：

import { AiMap } from '@antv/aimapui';
const schema = { map: { basemap: 'gaode', center: [121,31], zoom: 12 }, layers: [...], controls: [...] };
<AiMap schema={schema} />

map 和 schema 互斥，禁止同时传入。

详见 → schema-system.md

Composite Layers (复合图层)

复合图层是业务开箱即用的高级组件。各图层详细用法见对应 reference 文件：

Special Controls (特殊控件)

Layer Compare (图层对比)

LayerCompare 是 独立容器（不放入 <AiMap> 内部），在同一区域渲染两个同步场景，支持双屏（split）与卷帘（swipe）对比，可拖动分隔条控制两侧范围。两侧相机逐帧同步，卷帘可拖动地图、双屏联动平滑，sync={false} 可关闭。

<LayerCompare
  mode="swipe"
  map={{ basemap: 'gaode', center: [116.4, 39.91], zoom: 12 }}
  before={<SatelliteLayer provider="gaode" />}
  after={<BubbleLayer source={pois} sourceType="json" sourceConfig={{ x: 'lng', y: 'lat' }} colorField="category" sizeField="value" sizeRange={[8, 26]} />}
/>

详见 → layer-compare.md

Maki Icon Utilities (内置 200+ 矢量图标)

import { makiIconUrl, createMakiIconMap } from '@antv/aimapui';
// 单个图标 → makiIconUrl('cafe', { size: 32, fill: '#333' })
// 批量映射 → createMakiIconMap(['cafe', 'bus', 'hospital'])  // 用于 IconLayer.iconMap

详见 → maki-icons.md