agri-map-components

基于 Leaflet + React 的农业专用地图组件库，提供地块管理、标注点、道路、灌溉渠、农机轨迹等农业场景专用组件。

更新日志

v2.0.13 (2026-06-15)

新增

• ZoomControl 开发预览页面：新增 /map-creation/zoom-control 页面，展示缩放控件的基础用法、位置配置和样式配置

修复

• DualScaleControl：修复 position 属性不生效问题，组件不再依赖 MapContainer 的 dualScaleControl 配置，可独立显示
• DualScaleControl Demo：移除 position 相关文档和示例，保持与组件实现一致

v2.0.12 (2026-06-15)

新增

• autoFit 自动适配：PlotLayer、Marker、Road、Irrigation、Track 组件支持 autoFit 属性，支持 'one'（首次渲染执行一次）和 'always'（每次渲染都执行）两种模式
• useAutoFit Hook：统一的自动适配地图视野 Hook，支持自定义 maxZoom、padding、animate、duration 参数

v2.0.11 (2026-06-12)

修复

• Loading 组件：修复条件 hook 调用 ESLint 错误，重构代码结构确保 hooks 在每次渲染时按相同顺序调用

v2.0.10 (2026-06-12)

新增

• Loading open 属性：新增 open 属性控制显示/隐藏，支持 <Loading open={loading} /> 用法

v2.0.9 (2026-06-12)

新增

• PlotLayer 坐标格式自动检测：支持 [lng, lat]（经度在前）和 [lat, lng]（纬度在前）两种坐标格式自动检测
• 输出格式保持一致：编辑回调返回的坐标格式与输入保持一致
• coordinate-format 示例页面：新增坐标格式演示页面

v2.0.8 (2026-06-01)

新增

• TrackPlayer 时间轴功能：新增 onTimelineUpdate 回调，暴露完整时间轴数据
• useTimeline Hook：提供时间轴数据计算逻辑（progress、时间戳、格式化时间等）
• 时间轴 UI 交互：Demo 支持滑块拖动跳转、实时进度显示、时间戳标签
• TimelineProgressInfo 类型：完整的时间轴进度信息接口定义

v2.0.7 (2026-05-27)

新增

• Panel 面板组件：新增地图面板组件，支持在地图上渲染 React 内容
• 9 种预设位置：topleft, topright, bottomleft, bottomright, topcenter, bottomcenter, leftcenter, rightcenter, center
• 自定义坐标定位：支持对象形式精确控制位置
• 位置选择器 Demo：提供交互式位置选择演示
• useMap 示例更新：UseMapExample 使用 Panel 组件展示地图信息

v2.0.6 (2026-05-25)

新增

• LocationMarker 田块核田定位组件：新增用户位置标记组件，支持 GPS 定位显示
• SMIL 动画：内置 SVG 图标带脉冲光环动画效果
• 精度圈显示：可显示 GPS 定位精度范围
• 方向指示：支持航向角显示

特性

• 🗺️ 地块管理 - 支持大规模地块数据渲染，提供绘制、剪辑、移动等编辑功能
• 📍 标注点 - 多种预设图标，支持自定义 SVG 图标、3D 标签、聚合功能
• 🛤️ 道路绘制 - 田间道路绘制与管理，支持距离显示、蚁行动画
• 💧 灌溉渠 - 灌溉渠绘制与流向箭头显示，支持双向绘制
• 🚜 农机轨迹 - 农机作业轨迹显示，支持轨迹回放、状态分段
• 🌍 天地图 - 内置天地图图层支持（矢量/卫星/地形）
• 📐 双向标尺 - 地图比例尺组件
• 🔲 面板系统 - 地图面板组件，支持多种定位方式
• ⚡ 高性能 - 支持上万条地块数据渲染，视口内渲染、空间索引
• 🛡️ 错误边界 - 内置 ErrorBoundary 组件，优雅处理渲染错误
• 📊 性能监控 - PerformanceDashboard 实时监控组件性能

安装

npm install @wenle_2523097/agri-map
# 或
yarn add @wenle_2523097/agri-map

依赖版本

确保项目已安装以下依赖：

npm install leaflet@^1.9.4 react@>=18.0.0 react-dom@>=18.0.0

快速开始

import 'leaflet/dist/leaflet.css';
import { MapContainer, TianDiTuLayer, PlotLayer, Marker } from '@wenle_2523097/agri-map';

function App() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <MapContainer
        center={[30.0, 120.0]}
        zoom={12}
        tianDiTuLayer={{ apiKey: 'your-tianditu-key' }}
        dualScaleControl
      >
        <PlotLayer dataSource={plotData} />
        <Marker dataSource={markers} />
      </MapContainer>
    </div>
  );
}

核心组件

MapContainer 地图容器

集成配置功能的地图容器组件，替代 react-leaflet MapContainer。

<MapContainer
  center={[30.0, 120.0]}
  zoom={12}
  theme="light"
  tianDiTuLayer={{ apiKey: 'your-key', layerType: 'vector' }}
  dualScaleControl
  fullscreen
>
  {/* 子组件 */}
</MapContainer>

| 属性 | 类型 | 说明 | |------|------|------| | center | [number, number] | 地图中心点 | | zoom | number | 缩放级别 | | theme | 'light' \| 'dark' | 主题 | | tianDiTuLayer | TianDiTuLayerConfig | 天地图配置 | | dualScaleControl | boolean | 显示双向标尺 | | fullscreen | boolean \| FullscreenControlConfig | 全屏控件 | | loading | boolean \| LoadingProps | 加载状态 | | config | ConfigContextValue | 组件默认配置 |

PlotLayer 地块图层

高性能地块渲染组件，支持大规模数据渲染。

<PlotLayer
  dataSource={plots}
  onClick={(data) => console.log('点击地块:', data)}
  style={(data) => ({
    color: data.status === 'planting' ? '#4CAF50' : '#9E9E9E',
    fillOpacity: 0.6,
  })}
  editMode={['create', 'delete']}
  onCreate={(result) => console.log('新建地块:', result)}
  showLabel={true}
  labelFields={['name', 'area']}
/>

核心功能：

• 大规模数据渲染（空间索引 + 视口内渲染）
• 绘制、剪辑、移动、删除编辑模式
• 动态样式（根据数据状态变化）
• 标签显示（支持多字段）
• 轨迹回退功能

Marker 标注点

地图标注点组件，支持多种图标和编辑功能。

<Marker
  dataSource={markers}
  icon="point"
  iconSize={[48, 48]}
  editMode={['create', 'move', 'delete']}
  cluster={true}
  onClusterClick={(count, markers) => console.log('聚合点击:', count)}
/>

核心功能：

• 预设图标（point, position, drone, marker-* 等）
• 自定义 SVG 图标
• 3D 标签动画（12 种动画效果）
• 聚合功能（supercluster）
• 编辑模式（创建、移动、删除）
• Tooltip 和 Popup 支持

Road 田间道路

田间道路绘制与管理组件。

<Road
  dataSource={roads}
  path={{ color: '#795548', weight: 3 }}
  showDistance={true}
  antPath="selected"
  editMode={['create', 'edit', 'delete']}
  onCreate={(result) => console.log('新建道路:', result)}
/>

核心功能：

• 路径样式配置
• 距离显示
• 蚁行动画（全部/选中）
• 编辑模式

Irrigation 灌溉渠

灌溉渠绘制与流向显示组件。

<Irrigation
  dataSource={channels}
  path={{ color: '#2196F3', weight: 4 }}
  showArrows={true}
  editMode={['create', 'edit', 'delete', 'reverse']}
  onReverse={(result) => console.log('反转流向:', result)}
/>

核心功能：

• 流向箭头显示
• 双向绘制（进水口/出水口）
• 编辑模式（创建、编辑、删除、反转流向）

Track 农机轨迹

农机作业轨迹显示组件，支持轨迹回放。

<Track
  dataSource={trackData}
  displayMode="track"
  markerZoomThreshold={14}
  showStartEndMarkers
  miniMap
/>

核心功能：

• 双模式渲染（Marker 模式 / Track 模式）
• 状态分段着色（作业/非作业）
• 轨迹动画
• 起点/终点标记
• 小地图概览
• 轨迹回放（TrackPlayer）

MiniMap 小地图

在主地图上显示轨迹概览的小地图组件。

<MiniMap
  position="bottomright"
  simplified
  simplifyTolerance={3}
/>

核心功能：

• 显示主地图视口位置
• 简化轨迹渲染
• 自定义位置和尺寸

Panel 面板

在地图上渲染 React 内容的覆盖层组件。

<Panel position="topleft" offset={{ x: 16, y: 16 }}>
  <InfoCard />
</Panel>

<Panel position="center">
  <LoadingOverlay />
</Panel>

支持位置：

• 四角：topleft, topright, bottomleft, bottomright
• 边缘中点：topcenter, bottomcenter, leftcenter, rightcenter
• 居中：center
• 自定义：{ top: 20, right: 50, left: '50%' }

TianDiTuLayer 天地图

天地图底图组件，支持多种图层风格。

// 矢量底图
<TianDiTuLayer apiKey="your-key" layerType="vector" />

// 卫星影像
<TianDiTuLayer apiKey="your-key" layerType="satellite" />

// 地形图
<TianDiTuLayer apiKey="your-key" layerType="terrain" />

// 自定义叠加层
<TianDiTuLayer
  apiKey="your-key"
  overlayUrl="https://your-server.com/overlay/{z}/{x}/{y}.png"
  overlayOpacity={0.5}
/>

LocationMarker 位置标记

用户位置标记组件，支持 GPS 定位显示。

<LocationMarker
  position={[29.94, 117.90]}
  heading={45}
  accuracy={5}
  showAccuracyRing
  pulseOnMove
/>

核心功能：

• GPS 位置显示
• 航向角指示
• 精度圈显示
• SMIL 脉冲动画

Popup 弹出框

通用的地图弹出窗口组件，可嵌套在任何地图组件内部。

<PlotLayer dataSource={plots}>
  <Popup
    trigger="click"
    placement="top"
    title={(data) => data.name}
  >
    {(data) => (
      <div>
        <h4>{data.name}</h4>
        <p>面积: {data.area}亩</p>
      </div>
    )}
  </Popup>
</PlotLayer>

核心功能：

• 触发方式：click / hover
• 12 种弹出位置
• 支持 title、extra、footer 区域

FullscreenControl 全屏控件

地图全屏切换控件。

<FullscreenControl position="topright" />

ZoomControl 缩放控件

自定义缩放控件，替代 Leaflet 原生控件。

<ZoomControl position="bottomright" controlBg="#333" />

DualScaleControl 双向标尺

地图比例尺组件，同时显示水平和垂直标尺。

<DualScaleControl metric imperial showZoomControl />

Loading 加载状态

显示加载状态的组件。

<Loading />

<Loading icon="loading-dots" description="加载中..." size="large" />

Notification 通知提醒

类似 antd Notification 的通知提醒框，显示在地图右下角。

notification.success({ message: '保存成功', description: '地块已保存' });
notification.error({ message: '错误', description: '操作失败' });

ErrorBoundary 错误边界

捕获子组件树中的 JavaScript 错误。

<ErrorBoundary
  fallback={(error, reset) => (
    <div>
      <p>出错了：{error.message}</p>
      <button onClick={reset}>重试</button>
    </div>
  )}
>
  <YourComponent />
</ErrorBoundary>

PerformanceDashboard 性能监控

实时监控组件渲染性能。

<PerformanceDashboard visible={true} />

Measurement 测量工具

地图测量工具，支持距离和面积测量。

<MeasurementToolbar />

Icons 图标组件

内置 SVG 图标组件库。

import { Icons, CreateIcon, DeleteIcon } from 'agri-map';

// 使用
<CreateIcon />
<Icons.Delete />

SelectIcon 图标选择器

图标选择器组件，用于选择标注图标。

<SelectIcon
  value="point"
  onChange={(icon) => console.log('选择:', icon)}
/>

StyleSelector 样式选择器

线段/多边形样式选择器。

<StyleSelector
  value={{ color: '#1890ff', weight: 2 }}
  onChange={(style) => console.log('样式:', style)}
/>

ColorSwatch 颜色选择器

HSV 颜色选择器组件。

<ColorSwatch value="#1890ff" onChange={(color) => console.log('颜色:', color)} />

Hooks

useMap

获取地图实例。

import { useMap } from 'agri-map';

function MyComponent() {
  const map = useMap();
  // 使用 map 实例...
}

useMapEvents

同时监听多个地图事件。

import { useMapEvents } from 'agri-map';

function MyComponent() {
  const map = useMapEvents({
    click: (e) => console.log('点击:', e.latlng),
    zoomend: () => console.log('缩放:', map?.getZoom()),
  });
}

useGeolocation

GPS 定位 Hook。

import { useGeolocation } from 'agri-map/hooks';

function MyComponent() {
  const { position, heading, error } = useGeolocation({
    enableHighAccuracy: true,
    timeout: 10000,
  });
}

useNearbyPlots

查询附近地块 Hook。

import { useNearbyPlots } from 'agri-map/hooks';

function MyComponent() {
  const { nearbyPlots, distance } = useNearbyPlots(position, plots, {
    maxDistance: 1000,
    limit: 10,
  });
}

useTrackRecording

轨迹记录 Hook。

import { useTrackRecording } from 'agri-map/hooks';

function MyComponent() {
  const { points, isRecording, start, stop, clear } = useTrackRecording();
}

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建库
npm run build

# 构建 Demo
npm run build:demo

# 类型检查
npm run type-check

# 单元测试
npm run test

# E2E 测试
npm run e2e

# Storybook
npm run storybook

许可证

MIT