qm-map-maplibre-gl 0.0.8 → 0.1.0

package/README.md

@@ -1,162 +1,386 @@
-# qm-map-maplibre-gl
-
-基于 MapLibre GL 和 React 的地图组件库，提供丰富的地图交互组件。
-
-## 安装
-
-```bash
-npm install qm-map-maplibre-gl
-# 或
-yarn add qm-map-maplibre-gl
-```
-
-## 依赖
-
-- React >= 19.0.0
-- React DOM >= 19.0.0
-- MapLibre GL >= 5.0.0
-
-## 快速开始
-
-```tsx
-import { MapWidget, LayerList, Legend } from 'qm-map-maplibre-gl';
-import 'qm-map-maplibre-gl/dist/qm-map.css'
-import type { LngLatLike } from 'maplibre-gl';
-
-function App() {
-  const mapOptions = {
-    id: 'myMap',
-    center: [115.415, 33.254] as LngLatLike,
-    zoom: 9.5,
-    maxZoom: 18,
-  };
-
-  return (
-    <MapWidget mapOptions={mapOptions} mapLayerSettting={layerSetting}>
-      <LayerList position={{ top: 10, left: 10 }} />
-      <Legend position={{ bottom: 10, left: 10 }} />
-    </MapWidget>
-  );
-}
-```
-
-## 组件列表
-
-### MapWidget
-地图容器组件，所有其他组件必须包裹在其中。
-
-```tsx
-interface TMapProps {
-  mapOptions: TMapOptions;
-  mapLayerSettting: TMapLayerSettting;
-  children?: React.ReactNode;
-}
-```
-
-### LayerList
-图层列表组件，显示和控制地图图层可见性。
-
-```tsx
-<LayerList position={{ top: 10, left: 10 }} />
-```
-
-### Legend
-图例组件，显示地图图例信息。
-
-```tsx
-<Legend position={{ bottom: 10, left: 10 }} />
-```
-
-### Draw
-地图绘制组件，支持绘制点、线、面并计算面积。
-
-```tsx
-import DrawWidget, { type TDrawResult, type TDrawModeType } from 'qm-map-maplibre-gl';
-
-const onDraw = (res: TDrawResult) => {
-  console.log('绘制数据:', res.data);
-  console.log('总面积:', res.area);
-};
-
-// 基础用法
-<DrawWidget 
-  position={{ bottom: 10, right: 10 }} 
-  onDraw={onDraw} 
-/>
-
-// 限制绘制模式
-<DrawWidget 
-  modes={['draw_point', 'draw_polygon']}
-  position={{ bottom: 10, right: 10 }} 
-  onDraw={onDraw} 
-/>
-```
-
-**Props:**
-
-| 属性 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| position | TWidgetPosition | 是 | 控件位置 |
-| onDraw | (result: TDrawResult) => void | 是 | 绘制完成回调 |
-| modes | TDrawModeType[] | 否 | 允许的绘制模式 |
-| initFeature | FeatureCollection | 否 | 初始绘制数据 |
-
-**绘制模式:**
-- `'draw_point'` - 绘制点
-- `'draw_line_string'` - 绘制线
-- `'draw_polygon'` - 绘制多边形
-- `'simple_select'` - 选择模式
-
-### Swipe
-地图分屏对比组件。
-
-```tsx
-<Swipe position={{ top: 190, right: 10 }} />
-```
-
-### Print
-地图打印组件。
-
-```tsx
-<Print position={{ top: 10, right: 10 }} />
-```
-
-## 类型导出
-
-```tsx
-import type { 
-  TWidgetPosition,
-  TDrawResult, 
-  TDrawModeType,
-  TMapOptions,
-  TMapLayerSettting 
-} from 'qm-map-maplibre-gl';
-```
-
-## 工具 Hooks
-
-### useMap
-获取地图实例上下文。
-
-```tsx
-import { useMap } from 'qm-map-maplibre-gl';
-
-function MyComponent() {
-  const { map } = useMap();
-  
-  // 使用 map 实例
-  const handleClick = () => {
-    map?.flyTo({ center: [116, 39], zoom: 10 });
-  };
-  
-  return <button onClick={handleClick}>飞行到</button>;
-}
-```
-
-## 样式
-
-组件库已内置样式，无需额外引入 CSS 文件。
-
-## License
-
-MIT
+# qm-map-maplibre-gl
+
+基于 MapLibre GL 和 React 的地图组件库，提供丰富的地图交互组件。
+
+## 安装
+
+```bash
+npm install qm-map-maplibre-gl
+# 或
+yarn add qm-map-maplibre-gl
+```
+
+## 依赖
+
+- React >= 19.0.0
+- React DOM >= 19.0.0
+- MapLibre GL >= 5.0.0
+
+## 快速开始
+
+```tsx
+import { MapWidget, LayerList, Legend } from 'qm-map-maplibre-gl';
+import 'qm-map-maplibre-gl/dist/qm-map.css'
+import type { LngLatLike } from 'maplibre-gl';
+
+function App() {
+  const mapOptions = {
+    id: 'myMap',
+    center: [115.415, 33.254] as LngLatLike,
+    zoom: 9.5,
+    maxZoom: 18,
+  };
+
+  return (
+    <MapWidget mapOptions={mapOptions} mapLayerSettting={layerSetting}>
+      <LayerList style={{ top: 10, left: 10 }} />
+      <Legend style={{ bottom: 10, left: 10 }} />
+    </MapWidget>
+  );
+}
+```
+
+## 通用控件属性 TWidgetProps
+
+所有控件组件统一接收以下通用属性，通过 `style` 定位、`close` 控制显隐：
+
+```ts
+type TWidgetProps = {
+  /** 是否关闭（隐藏）控件，默认 false */
+  close?: boolean;
+  /** 自定义类名 */
+  classname?: string;
+  /** 样式，用于 absolute 定位 */
+  style?: CSSProperties;
+  /** 交互回调 */
+  onCallback?: (value?: any) => void;
+};
+```
+
+面板类控件（LayerList、Legend、Swipe、Print）配合 [WidgetButton](#widgetbutton) 使用：按钮切换显隐状态，通过 `close` 传入控件。
+
+## 组件列表
+
+### MapWidget
+地图容器组件，所有其他组件必须包裹在其中。
+
+```tsx
+interface TMapProps {
+  mapOptions: TMapOptions;
+  mapLayerSettting: TMapLayerSettting;
+  children?: React.ReactNode;
+}
+```
+
+### WidgetButton
+轻量图标按钮组件，用于切换面板类控件的显隐：
+
+```tsx
+import { WidgetButton } from 'qm-map-maplibre-gl';
+
+<WidgetButton
+  title="图层控制"
+  style={{ top: 10, left: 10 }}
+  icon={WIDGETICONS.LayerList}
+  onToggle={() => setLayerOpen((prev) => !prev)}
+/>
+<LayerList close={layerOpen} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| icon | string | 是 | 按钮图标（图片地址，内置图标见 `lib/widget/constant.ts` 的 `WIDGETICONS`） |
+| title | string | 否 | 悬停提示 |
+| onToggle | (value: boolean) => void | 否 | 点击回调 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+
+### LayerList
+图层列表组件，显示和控制地图图层可见性（树形勾选）。
+
+```tsx
+<LayerList
+  style={{ top: 10, left: 10 }}
+  close={!layerOpen}
+  onCallback={(checkedKeys) => console.log('勾选的图层:', checkedKeys)}
+/>
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onCallback | (checkedKeys: string[]) => void | 否 | 勾选变化回调，返回勾选的图层 id |
+
+### Legend
+图例组件，显示地图图例信息（依据图层配置的 `legend` 字段渲染）。
+
+```tsx
+<Legend style={{ bottom: 10, left: 10 }} close={false} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+
+### Draw
+地图绘制组件，支持绘制点、线、面，绘制结果含初始要素。
+
+```tsx
+import DrawWidget from 'qm-map-maplibre-gl';
+
+const onDraw = (res: TDrawResult) => {
+  console.log('绘制数据:', res.data);
+};
+
+// 基础用法
+<Draw
+  style={{ bottom: 10, right: 10 }}
+  onDraw={onDraw}
+/>
+
+// 限制绘制模式
+<Draw
+  modes={['draw_point', 'draw_polygon']}
+  style={{ bottom: 10, right: 10 }}
+  onDraw={onDraw}
+/>
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onDraw | (result: TDrawResult) => void | 否 | 绘制/修改/删除完成回调 |
+| modes | TDrawModeType[] | 否 | 允许的绘制模式，默认全部 |
+| initFeature | FeatureCollection | 否 | 初始绘制数据 |
+
+**绘制模式:**
+- `'draw_point'` - 绘制点
+- `'draw_line_string'` - 绘制线
+- `'draw_polygon'` - 绘制多边形
+- `'simple_select'` - 选择模式（清除工具始终保留）
+
+### Clear
+清除控件，点击清除地图上所有选中对象。
+
+```tsx
+<Clear style={{ top: 230, right: 10 }} onCallback={() => console.log('已清除')} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onCallback | () => void | 否 | 清除完成回调 |
+
+### Swipe
+地图分屏对比组件，点击按钮弹出模态框，内含左右两张联动地图进行卷帘对比。
+
+```tsx
+const [swipeOpen, setSwipeOpen] = useState(false);
+
+<WidgetButton
+  title="卷帘对比"
+  style={{ top: 180, right: 10 }}
+  icon={WIDGETICONS.Swipe}
+  onToggle={() => setSwipeOpen((prev) => !prev)}
+/>
+<Swipe close={!swipeOpen} onCallback={(value) => setSwipeOpen(value)} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否关闭弹窗 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 弹窗样式定位 |
+| onCallback | (open: boolean) => void | 否 | 关闭弹窗回调 |
+
+### Print
+地图打印组件，面板式导出：支持页面尺寸（A2~A6、B2~B6、Letter）、布局方向（横向/纵向）、导出格式（PDF/PNG/SVG/JPEG）、DPI（72~400），导出内容含指北针。
+
+```tsx
+const [printOpen, setPrintOpen] = useState(false);
+
+<WidgetButton
+  title="地图打印"
+  style={{ top: 10, right: 10 }}
+  icon={WIDGETICONS.Print}
+  onToggle={() => setPrintOpen((prev) => !prev)}
+/>
+<Print close={printOpen} style={{ right: 50, top: 10 }} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏面板 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onCallback | () => void | 否 | 导出完成回调 |
+
+### FullScreen
+全屏控件，点击进入/退出整页全屏。
+
+```tsx
+<FullScreen style={{ top: 350, right: 10 }} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onCallback | () => void | 否 | 全屏切换回调 |
+
+### ZoomIn / ZoomOut
+地图缩放控件，点击缩放级别 ±1。
+
+```tsx
+<ZoomIn style={{ top: 390, right: 10 }} />
+<ZoomOut style={{ top: 430, right: 10 }} />
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onCallback | () => void | 否 | 缩放回调 |
+
+### MeasureLine
+测距控件，点击开始测量距离，双击结束。
+
+```tsx
+<MeasureLine
+  style={{ top: 270, right: 10 }}
+  onMeasure={(result: TMeasureResult) => console.log(result)}
+/>
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| onMeasure | (result: TMeasureResult) => void | 否 | 测量完成回调（双击结束时触发） |
+
+### MeasurePolygon
+测面控件，点击开始测量面积，双击结束。
+
+```tsx
+<MeasurePolygon
+  style={{ top: 310, right: 10 }}
+  unit="mu"
+  onMeasure={(result: TMeasureResult) => console.log(result)}
+/>
+```
+
+**Props:**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| close | boolean | 否 | 是否隐藏 |
+| classname | string | 否 | 自定义类名 |
+| style | CSSProperties | 否 | 样式定位 |
+| unit | 'mu' \| 'm2' | 否 | 面积单位，默认 'mu'（亩） |
+| onMeasure | (result: TMeasureResult) => void | 否 | 测量完成回调（双击结束时触发） |
+
+**测量结果 TMeasureResult:**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| type | 'line' \| 'polygon' | 测量类型 |
+| points | [number, number][] | 采集的坐标点（[lng, lat]，含双击结束点） |
+| value | number | 原始数值：line 为 km；polygon 为 m² |
+| formatted | string | 格式化文本（如 '1.23km'、'12.3456亩'） |
+
+## 测量类与工具函数
+
+测量类也可脱离 React 组件直接使用：
+
+```tsx
+import { PolylineMeasure, PolygonMeasure } from 'qm-map-maplibre-gl';
+
+// 测距
+const measure = new PolylineMeasure(map, (result) => console.log(result));
+measure.start();
+// 双击结束测量，measure.clearMeasure() 清理
+
+// 测面（unit: 'mu' 亩 | 'm2' 平方米）
+const polygonMeasure = new PolygonMeasure(map, 'mu', (result) => console.log(result));
+polygonMeasure.start();
+```
+
+工具函数：`haversineDistance`（两点距离 km）、`polylineLengthKm`（折线总长 km）、`polygonAreaM2`（多边形面积 m²）、`formatDistance`、`formatArea`。
+
+## 类型导出
+
+```tsx
+import type {
+  TMapProps,
+  TWidgetProps,
+  TWidgetMeasureProps,
+  TWidgetDrawProps,
+  TDrawResult,
+  TDrawModeType,
+  TDrawMode,
+  TMapOptions,
+  TMapLayerSettting,
+  TMeasureResult,
+  TMeasurePoint,
+  TMeasureUnit
+} from 'qm-map-maplibre-gl';
+```
+
+## 工具 Hooks
+
+### useMap
+获取地图实例上下文。
+
+```tsx
+import { useMap } from 'qm-map-maplibre-gl';
+
+function MyComponent() {
+  const { map } = useMap();
+  
+  // 使用 map 实例
+  const handleClick = () => {
+    map?.flyTo({ center: [116, 39], zoom: 10 });
+  };
+  
+  return <button onClick={handleClick}>飞行到</button>;
+}
+```
+
+## 样式
+
+组件库已内置样式，无需额外引入 CSS 文件。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export { default as BaseWidget } from './widget/BaseWidget';
 export { default as MapWidget } from './widget/MapWidget';
 export { default as LayerList } from './widget/LayerList';
 export { default as Legend } from './widget/Legend';
@@ -6,16 +5,25 @@ export { default as Print } from './widget/Print';
 export { default as Swipe } from './widget/Swipe';
 export { default as Draw } from './widget/Draw';
 export { default as Clear } from './widget/Clear';
-export type { TWidgetOptions, TWidgetPosition } from './widget/BaseWidget';
+export { default as FullScreen } from './widget/FullScreen';
+export { default as ZoomIn } from './widget/ZoomIn';
+export { default as ZoomOut } from './widget/ZoomOut';
+export { default as MeasureLine } from './widget/MeasureLine';
+export { default as MeasurePolygon } from './widget/MeasurePolygon';
 export type { TMapProps } from './widget/MapWidget';
-export type { TDrawResult, TDrawControlProps, TDrawModeType } from './widget/Draw';
+export type { TDrawResult, TDrawModeType, TWidgetProps, TWidgetMeasureProps, TWidgetDrawProps, TDrawMode } from './widget/constant';
 export { default as BaseLayer } from './maplibregl/layer/BaseLayer';
 export { default as LayerGroupWrapper } from './maplibregl/layer/LayerGroupWrapper';
 export { default as LayerWrapper } from './maplibregl/layer/LayerWrapper';
 export { default as MapWrapper } from './maplibregl/MapWrapper';
+export { default as BaseMeasure } from './maplibregl/measure/BaseMeasure';
+export { default as PolylineMeasure } from './maplibregl/measure/PolylineMeasure';
+export { default as PolygonMeasure } from './maplibregl/measure/PolygonMeasure';
+export { haversineDistance, polylineLengthKm, polygonAreaM2, formatDistance, formatArea, } from './maplibregl/measure/measureUtil';
 export { useMap } from './context/mapContext';
 export { MapContext } from './context/mapContext';
 export type { MapEvent, MapEventData } from './maplibregl/typings/TEvent';
 export type { TMapContext } from './context/mapContext';
+export type { TMeasureResult, TMeasurePoint, TMeasureUnit, } from './maplibregl/measure/BaseMeasure';
 export type { TMapLayerSettting, TLegendItemOptions, TLegendControlOptions, TLayerOptions, TLayerGroupOptions, TLayerSetingOptions, } from './maplibregl/typings/TLayerOptions';
 export type { TMapOptions } from './maplibregl/typings/TMapOptions';

package/dist/maplibregl/MapWrapper.d.ts

@@ -64,7 +64,7 @@ declare class MapWrapper extends Map {
      * 在地图上显示选中的 GeoJSON 要素
      * @param geo - GeoJSON 要素或要素集合
      */
-    selectFeature(geo: GeoJSON.Feature<GeoJSON.Geometry> | GeoJSON.FeatureCollection<GeoJSON.Geometry> | string, combine?: boolean): void;
+    selectFeature(geo: GeoJSON.Feature<GeoJSON.Geometry> | GeoJSON.FeatureCollection<GeoJSON.Geometry> | string): void;
     /**
      * 清除选中要素的高亮显示
      */

package/dist/maplibregl/measure/BaseMeasure.d.ts

@@ -0,0 +1,83 @@
+import { Marker, MapMouseEvent } from 'maplibre-gl';
+import { default as MapWrapper } from '../MapWrapper';
+/** 经纬度坐标点 [lng, lat] */
+export type TMeasurePoint = [number, number];
+/** 面积单位：'mu' 亩 | 'm2' 平方米 */
+export type TMeasureUnit = 'mu' | 'm2';
+/**
+ * 测量完成回调结果
+ */
+export interface TMeasureResult {
+    /** 测量类型 */
+    type: 'line' | 'polygon';
+    /** 采集的坐标点（含双击结束点） */
+    points: TMeasurePoint[];
+    /** 原始数值：line 为 km；polygon 为 m² */
+    value: number;
+    /** 格式化文本（与地图 tooltip 一致） */
+    formatted: string;
+}
+/**
+ * 测量基类
+ * 封装测量交互公共逻辑：事件注册、光标切换、tooltip 与关闭按钮、清理
+ */
+declare abstract class BaseMeasure {
+    protected map: MapWrapper;
+    protected uuid: string;
+    protected isMeasure: boolean;
+    protected points: TMeasurePoint[];
+    /** 所有 Marker（tooltip、每点标签、关闭按钮） */
+    protected markers: Marker[];
+    /** tooltip 的 DOM 元素 */
+    protected ele: HTMLDivElement;
+    protected tooltip: Marker;
+    protected onMeasure?: (result: TMeasureResult) => void;
+    /** 宿主页面缩放比例（适配 3D 沙箱场景） */
+    protected scale: number;
+    /** 测量前 doubleClickZoom 的启用状态，清理时恢复 */
+    private prevDoubleClickZoom;
+    constructor(map: MapWrapper, onMeasure?: (result: TMeasureResult) => void);
+    /**
+     * 生成唯一 ID
+     */
+    generateId(): string;
+    /**
+     * 开始测量：禁用双击缩放、切换十字光标、注册地图事件
+     */
+    start(): void;
+    /**
+     * 移除地图事件监听
+     */
+    clearDrawEventListener(): void;
+    /**
+     * 清理所有测量痕迹并恢复地图状态（幂等，可重复调用）
+     */
+    clearMeasure(): void;
+    /**
+     * 双击收尾：结束测量、移除 tooltip、添加关闭按钮、触发 onMeasure 回调
+     * @param coords - 结束点坐标
+     */
+    protected finishMeasure(coords: TMeasurePoint): void;
+    /**
+     * 像素坐标转经纬度（除以宿主页面缩放比例）
+     * @param e - 地图鼠标事件
+     * @returns [lng, lat]
+     */
+    protected getCoords(e: MapMouseEvent): TMeasurePoint;
+    /** 创建测量图层与数据源 */
+    protected abstract createLayers(): void;
+    /** 移除测量图层与数据源 */
+    protected abstract removeLayers(): void;
+    /** tooltip 实时文本 */
+    protected abstract getFormatText(coords: TMeasurePoint): string;
+    /** 测量结果原始数值（line: km；polygon: m²） */
+    protected abstract getResultValue(): number;
+    /** 测量结果格式化文本 */
+    protected abstract getResultText(): string;
+    /** 测量类型 */
+    protected abstract getMeasureType(): 'line' | 'polygon';
+    protected abstract mapClickHandle: (e: MapMouseEvent) => void;
+    protected abstract mapMouseMoveHandle: (e: MapMouseEvent) => void;
+    protected abstract mapDbclickHandle: (e: MapMouseEvent) => void;
+}
+export default BaseMeasure;