@xingm/vmap-cesium-toolbar 0.0.7-alpha.1 → 0.0.7-alpha.2

package/README.md

@@ -0,0 +1,276 @@
+# @xingm/vmap-cesium-toolbar
+
+一个功能强大的 Cesium 地图工具栏组件，提供搜索、测量、绘制、2D/3D切换、图层管理等功能。
+
+## 特性
+
+- 🗺️ **完整的地图工具栏** - 搜索、测量、绘制、图层切换等功能
+- 📏 **精确测量工具** - 支持距离、面积、高度测量
+- ✏️ **绘制功能** - 支持点、线、面绘制和编辑
+- 🔄 **2D/3D切换** - 无缝切换2D和3D视图模式
+- 🎨 **可定制样式** - 支持自定义按钮样式和布局
+- 📱 **响应式设计** - 适配不同屏幕尺寸
+- 🚀 **TypeScript支持** - 完整的类型定义
+- ⚡ **Vue 3兼容** - 原生支持Vue 3项目
+
+## 安装
+
+```bash
+npm install @xingm/vmap-cesium-toolbar cesium
+```
+
+## 快速开始
+
+### 基本使用
+
+```javascript
+import { CesiumMapToolbar, initCesium } from '@xingm/vmap-cesium-toolbar';
+import '@xingm/vmap-cesium-toolbar/style';
+
+// 初始化Cesium
+(async () => {
+  const { viewer } = await initCesium('cesiumContainer', {
+    terrainProvider: Cesium.createWorldTerrain(),
+  });
+
+  // 创建工具栏
+  const toolbar = new CesiumMapToolbar(viewer, document.getElementById('toolbar'));
+})();
+```
+
+### Vue 3 项目中使用
+
+```vue
+<template>
+  <div id="cesiumContainer"></div>
+  <div id="toolbar"></div>
+</template>
+
+<script setup>
+import { onMounted } from 'vue';
+import { CesiumMapToolbar, initCesium } from '@xingm/vmap-cesium-toolbar';
+import '@xingm/vmap-cesium-toolbar/style';
+
+let viewer;
+let toolbar;
+
+onMounted(async () => {
+  // 初始化Cesium
+  const result = await initCesium('cesiumContainer', {
+    terrainProvider: Cesium.createWorldTerrain(),
+  });
+  viewer = result.viewer;
+
+  // 创建工具栏
+  toolbar = new CesiumMapToolbar(viewer, document.getElementById('toolbar'));
+});
+</script>
+```
+
+## 主要组件
+
+### CesiumMapToolbar
+
+主要工具栏组件，提供完整的地图操作功能。
+
+```typescript
+const toolbar = new CesiumMapToolbar(
+  viewer,                    // Cesium Viewer实例
+  container,                 // 工具栏容器元素
+  config,                    // 配置选项（可选）
+  callbacks,                 // 回调函数（可选）
+  initialCenter              // 初始中心点（可选）
+);
+```
+
+### DrawHelper
+
+绘制工具类（包的默认导出），提供线/面/矩形/圆等交互绘制能力。
+
+```typescript
+import DrawHelper from '@xingm/vmap-cesium-toolbar';
+
+const drawHelper = new DrawHelper(viewer);
+drawHelper.startDrawingPolygon();
+```
+
+### initCesium
+
+Cesium 初始化函数，简化 Viewer 创建、底图/地形与初始视角配置。
+
+```typescript
+import { initCesium } from '@xingm/vmap-cesium-toolbar';
+
+const { viewer } = await initCesium('cesiumContainer', {
+  cesiumToken: 'your_cesium_ion_token',
+});
+
+// 使用天地图时可指定底图类型（默认 imagery）
+const { viewer: tdtViewer } = await initCesium('cesiumContainer', {
+  mapType: 'tiandi',
+  tdtMapTypeId: 'terrain',
+  token: 'your_tianditu_token',
+});
+```
+
+## 配置选项
+
+### 工具栏配置
+
+```typescript
+interface ToolbarConfig {
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  buttonSize?: number;           // 按钮大小 (默认40px)
+  buttonSpacing?: number;        // 按钮间距 (默认8px)
+  backgroundColor?: string;      // 背景色
+  borderColor?: string;          // 边框色
+  borderRadius?: number;         // 圆角半径
+  showSearch?: boolean;          // 显示搜索框
+  showMeasurement?: boolean;     // 显示测量工具
+  showDrawing?: boolean;         // 显示绘制工具
+  showLayerControl?: boolean;    // 显示图层控制
+  show2D3DToggle?: boolean;      // 显示2D/3D切换
+}
+```
+
+### 回调函数
+
+```typescript
+interface ToolbarCallbacks {
+  search?: (query: string) => void;
+  measurement?: (type: string, result: any) => void;
+  drawing?: (type: string, entity: Entity) => void;
+  zoom?: (level: number) => void;
+}
+```
+
+## 功能说明
+
+### 搜索功能
+
+支持路网搜索和坐标定位：
+
+```javascript
+// 搜索回调
+const callbacks = {
+  search: (query) => {
+    console.log('搜索:', query);
+    // 实现搜索逻辑
+  }
+};
+```
+
+### 测量工具
+
+支持多种测量类型：
+
+- **距离测量** - 测量两点间距离
+- **面积测量** - 测量多边形面积
+- **高度测量** - 测量点的高度信息
+
+```javascript
+// 测量回调
+const callbacks = {
+  measurement: (type, result) => {
+    console.log('测量结果:', type, result);
+  }
+};
+```
+
+### 绘制功能
+
+支持多种绘制类型：
+
+- **点绘制** - 在地图上标记点
+- **线绘制** - 绘制线条
+- **面绘制** - 绘制多边形区域
+
+```javascript
+// 绘制回调
+const callbacks = {
+  drawing: (type, entity) => {
+    console.log('绘制完成:', type, entity);
+  }
+};
+```
+
+## 样式定制
+
+组件提供了完整的CSS变量支持，可以轻松定制样式：
+
+```css
+:root {
+  --toolbar-bg-color: #ffffff;
+  --toolbar-border-color: #e0e0e0;
+  --toolbar-button-size: 40px;
+  --toolbar-button-spacing: 8px;
+  --toolbar-border-radius: 4px;
+}
+```
+
+## 示例项目
+
+### 基本使用示例
+
+```bash
+# 克隆项目
+git clone https://github.com/your-username/vmap-cesium-toolbar.git
+cd vmap-cesium-toolbar
+
+# 查看基本示例
+cd examples/basic-usage
+# 在浏览器中打开 index.html
+```
+
+### Vue 3 示例
+
+```bash
+cd examples/vue3-usage
+npm install
+npm run dev
+```
+
+## API 文档
+
+详细的API文档请参考：
+
+- [CesiumMapToolbar API](./doc/CesiumMapToolbar_API.md)
+- [CesiumMapHelper API](./doc/CesiumMapHelper_API.md)
+- [CesiumMapLoader API](./doc/CesiumMapLoader_API.md)
+- [CesiumOverlayService API](./doc/CesiumOverlayService_API.md)
+
+## 依赖要求
+
+- **Cesium**: ^1.100.0
+- **Vue**: ^3.0.0 (可选，用于Vue项目)
+
+## 浏览器支持
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
+### v0.0.1-beta.2
+
+- 新增高度测量功能
+- 优化标签显示逻辑
+- 修复3D模式下标签位置问题
+- 改进绘制工具的用户体验
+
+### v0.0.1-beta.1
+
+- 初始版本发布
+- 基础工具栏功能
+- 搜索、测量、绘制功能
+- Vue 3 支持

package/dist/hooks/toolBarConfig.d.ts

@@ -0,0 +1,78 @@
+import { SearchResult } from '../libs/CesiumMapModel';
+import { Viewer } from '../../node_modules/cesium';
+import { Ref } from 'vue';
+export declare const useToolBarConfig: (viewer: Viewer | undefined, message: Ref<string>, tdtAuth?: {
+    token?: string;
+    sk?: string;
+}) => {
+    toolbarConfig: {
+        position: string;
+        buttonSize: number;
+        buttonSpacing: number;
+        borderRadius: number;
+        borderWidth: number;
+        zIndex: number;
+        backgroundColor: string;
+        buttons: ({
+            size: number;
+            id: string;
+            icon: string;
+            title: string;
+            titleKey: string;
+            color: string;
+            borderColor: string;
+            backgroundColor: string;
+            activeIcon?: undefined;
+            callback?: undefined;
+        } | {
+            size: number;
+            id: string;
+            icon: string;
+            title: string;
+            titleKey: string;
+            color: string;
+            backgroundColor: string;
+            borderColor?: undefined;
+            activeIcon?: undefined;
+            callback?: undefined;
+        } | {
+            size: number;
+            id: string;
+            icon: boolean;
+            activeIcon: boolean;
+            title: string;
+            titleKey: string;
+            color: string;
+            backgroundColor: string;
+            borderColor?: undefined;
+            callback?: undefined;
+        } | {
+            size: number;
+            id: string;
+            icon: string;
+            title: string;
+            titleKey: string;
+            color: string;
+            borderColor: string;
+            backgroundColor: string;
+            callback: (isChecked: boolean, toolbar?: any) => void;
+            activeIcon?: undefined;
+        })[];
+    };
+    toolbarCallback: {
+        search: {
+            onSearch: (query: string) => Promise<SearchResult[]>;
+            onSelect: (result: SearchResult) => void;
+        };
+        measurement: {
+            onMeasurementStart: (positions?: any) => void;
+            onDistanceComplete: (positions: any, distance: any) => void;
+            onAreaComplete: (positions: any, area: any) => void;
+            onClear: () => void;
+        };
+        zoom: {
+            onZoomIn: (beforeLevel: any, afterLevel: any, currentLevel: any) => void;
+            onZoomOut: (beforeLevel: any, afterLevel: any, currentLevel: any) => void;
+        };
+    };
+};

package/dist/hooks/useDrawHelper.d.ts

@@ -0,0 +1,24 @@
+import { Ref } from 'vue';
+import { default as DrawHelper } from '../libs/CesiumMapDraw';
+import * as Cesium from "cesium";
+/**
+ * 绘制相关的辅助逻辑
+ * - 提供线、矩形、圆形、多边形的绘制示例方法
+ */
+export declare function useDrawHelper(viewer: Ref<Cesium.Viewer | undefined>, message: Ref<string>): {
+    drawHelper: import('vue').ShallowRef<DrawHelper | null, DrawHelper | null>;
+    isDrawing: Ref<boolean, boolean>;
+    currentDrawMode: Ref<string | null, string | null>;
+    initDrawHelper: () => void;
+    endDrawing: () => void;
+    addDrawLine: () => void;
+    addDrawArea: () => void;
+    addDrawAreaNoLabel: () => void;
+    addDrawCircle: () => void;
+    addDrawCircleNoLabel: () => void;
+    addDrawPolygon: () => void;
+    addDrawPolygonNoLabel: () => void;
+    addDrawPolygon_PointIntercept: () => void;
+    addDrawPolygon_FinishFallback: () => void;
+    destroyDrawHelper: () => void;
+};

package/dist/hooks/useDynamicRing.d.ts

@@ -0,0 +1,44 @@
+import { Viewer } from '../../node_modules/cesium';
+import * as Cesium from "cesium";
+export type CleanupFn = () => void;
+export type RingDirection = "outward" | "inward";
+export type AddDynamicRingOptions = {
+    position: Cesium.Cartesian3;
+    color?: Cesium.Color;
+    width?: number;
+    height?: number;
+    scale?: number;
+    direction?: RingDirection;
+    imageSize?: number;
+    disableDepthTestDistance?: number;
+};
+export type DynamicRingInstance = {
+    billboard: Cesium.Billboard;
+    color: Cesium.Color;
+    direction: RingDirection;
+};
+export declare function getRingCanvas(size?: number): HTMLCanvasElement;
+export declare function addDynamicRing(collection: Cesium.BillboardCollection, options: AddDynamicRingOptions): DynamicRingInstance;
+export type StartDynamicRingOptions = {
+    lon: number;
+    lat: number;
+    /** 任选其一：radiusMeters / diameterMeters / widthMeters+heightMeters */
+    radiusMeters?: number;
+    diameterMeters?: number;
+    widthMeters?: number;
+    heightMeters?: number;
+    color?: Cesium.Color;
+    /** 发散方向：outward(由小到大) / inward(由大到小) */
+    direction?: RingDirection;
+    heightOffset?: number;
+    imageSize?: number;
+    disableDepthTestDistance?: number;
+    period?: number;
+    baseScale?: number;
+    scaleRange?: number;
+    baseAlpha?: number;
+};
+/**
+ * 一站式：创建光圈 + 贴地采样 + preRender 动画，并返回 cleanup
+ */
+export declare function startDynamicRing(viewer: Viewer, options: StartDynamicRingOptions): CleanupFn;

package/dist/hooks/useHeatmapHelper.d.ts

@@ -0,0 +1,18 @@
+import { Ref } from 'vue';
+import { default as CesiumHeatmapLayer, HeatPoint, HeatmapOptions, HeatmapGradient, HeatmapAutoUpdateOptions } from '../libs/CesiumHeatmapLayer';
+import * as Cesium from "cesium";
+/**
+ * 热力图相关的辅助逻辑
+ */
+export declare function useHeatmapHelper(viewer: Ref<Cesium.Viewer | undefined>): {
+    heatmapLayer: import('vue').ShallowRef<CesiumHeatmapLayer | null, CesiumHeatmapLayer | null>;
+    visible: Ref<boolean, boolean>;
+    initHeatmap: (options?: HeatmapOptions) => void;
+    updateHeatmapData: (points: HeatPoint[]) => void;
+    setHeatmapVisible: (v: boolean) => void;
+    setHeatmapOpacity: (alpha: number) => void;
+    setHeatmapGradient: (gradient: HeatmapGradient) => void;
+    setHeatmapAutoUpdate: (options?: HeatmapAutoUpdateOptions) => void;
+    stopHeatmapAutoUpdate: () => void;
+    destroyHeatmap: () => void;
+};

package/dist/hooks/useMap.d.ts

@@ -0,0 +1,14 @@
+export declare const TD_Map_TOKEN: any;
+export declare const China_Map_Bound = "73.5577,18.1597,135.0882,53.5609";
+export declare const China_Map_Center: {
+    longitude: number;
+    latitude: number;
+    height: number;
+};
+export declare const China_Map_Extent: {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+};
+export declare const TD_Map_Search_URL: (keywords: string, mapConfig: any, token?: any, sk?: string) => string;

package/dist/hooks/useMapInit.d.ts

@@ -0,0 +1,14 @@
+export declare const TD_Map_TOKEN: any;
+export declare const China_Map_Bound = "73.5577,18.1597,135.0882,53.5609";
+export declare const China_Map_Center: {
+    longitude: number;
+    latitude: number;
+    height: number;
+};
+export declare const China_Map_Extent: {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+};
+export declare const TD_Map_Search_URL: (keywords: string, mapConfig: any, token?: any, sk?: string) => string;

package/dist/hooks/useOverlayHelper.d.ts

@@ -0,0 +1,48 @@
+import { Ref } from 'vue';
+import { Entity } from '../../node_modules/cesium';
+import { OverlayEntity } from '../libs/overlay/types';
+import { CesiumOverlayService } from '../libs/overlay';
+import * as Cesium from "cesium";
+type OverlayEditChangeHandler = (entity: Entity & OverlayEntity) => void;
+type OverlayHelperOptions = {
+    /**
+     * 覆盖物编辑模式下，拖拽结束且几何变化时触发。
+     * 可用于同步业务数据或触发保存。
+     */
+    onOverlayEditChange?: OverlayEditChangeHandler;
+};
+/**
+ * 覆盖物相关的辅助逻辑
+ * - 提供添加点位（Marker）与示例覆盖物的便捷方法
+ * - 管理点位模式的事件处理及清理
+ */
+export declare function useOverlayHelper(viewer: Ref<Cesium.Viewer | undefined>, message: Ref<string>): {
+    overlayService: import('vue').ShallowRef<CesiumOverlayService | null, CesiumOverlayService | null>;
+    initOverlayService: (options?: OverlayHelperOptions) => void;
+    addMarker: () => void;
+    addMarkerWithLabel: () => void;
+    addLabel: (options: any) => void;
+    addIcon: (coords?: {
+        longitude: number;
+        latitude: number;
+    }) => void;
+    addSvg: (coords?: {
+        longitude: number;
+        latitude: number;
+    }) => void;
+    addPolyline: () => void;
+    addLine: () => void;
+    addArea: () => void;
+    addCircle: () => void;
+    addCircle123: () => void;
+    addRing: (i?: number) => Cesium.Entity | undefined;
+    addPolygon: () => void;
+    addRectangle: () => void;
+    addInfoWindow: () => void;
+    closeInfoWindow: () => void;
+    testSetOverlayHighlight: () => void;
+    testToggleOverlayHighlight: () => void;
+    cancelMarkerMode: () => void;
+    destroyOverlayService: () => void;
+};
+export {};

package/dist/hooks/usePointClusterHelper.d.ts

@@ -0,0 +1,14 @@
+import { Ref } from 'vue';
+import { default as CesiumPointClusterLayer, ClusterPoint, PointClusterLayerOptions } from '../libs/CesiumPointClusterLayer';
+import * as Cesium from 'cesium';
+/**
+ * 点聚类图层相关的辅助逻辑（Vue3 composition API）
+ */
+export declare function usePointClusterHelper(viewer: Ref<Cesium.Viewer | undefined>): {
+    clusterLayer: import('vue').ShallowRef<CesiumPointClusterLayer | null, CesiumPointClusterLayer | null>;
+    visible: Ref<boolean, boolean>;
+    initCluster: (options?: PointClusterLayerOptions) => void;
+    updateClusterData: (points: ClusterPoint[]) => void;
+    setClusterVisible: (v: boolean) => void;
+    destroyCluster: () => void;
+};

package/dist/i18n/en-US.d.ts

@@ -0,0 +1,148 @@
+declare const enUS: {
+    locale: string;
+    app: {
+        lang: {
+            zh: string;
+            en: string;
+        };
+        located: string;
+        init_success: string;
+        heatmap_empty: string;
+        heatmap_need_add: string;
+        heatmap_added: string;
+        heatmap_auto_on: string;
+        heatmap_auto_off: string;
+        heatmap_lod_coarse: string;
+        heatmap_lod_medium: string;
+        heatmap_lod_fine: string;
+        ring_test_added: string;
+        custom_alert: string;
+        custom_stats: string;
+        custom_visibility: string;
+        custom_alert_title: string;
+        custom_stats_title: string;
+        custom_visibility_title: string;
+    };
+    ui: {
+        draw: {
+            line: string;
+            area: string;
+            area_no_label: string;
+            circle: string;
+            circle_no_label: string;
+            polygon: string;
+            polygon_point_intercept: string;
+            polygon_finish_fallback: string;
+            polygon_no_label: string;
+        };
+        add: {
+            marker: string;
+            line: string;
+            area: string;
+            circle: string;
+            circle123: string;
+            polygon: string;
+            polyline: string;
+            icon: string;
+            svg: string;
+            marker_with_label: string;
+            label: string;
+            rectangle: string;
+            info_window: string;
+            ring: string;
+            ring_test: string;
+            heatmap: string;
+        };
+        test: {
+            set_highlight: string;
+            toggle_highlight: string;
+        };
+        heatmap: {
+            auto_on: string;
+            auto_off: string;
+            lod_coarse: string;
+            lod_medium: string;
+            lod_fine: string;
+        };
+        overlay_edit: {
+            enable: string;
+            disable: string;
+            stop: string;
+        };
+    };
+    layers: {
+        map_type: {
+            place_name: string;
+        };
+    };
+    draw: {
+        start: {
+            line: string;
+            rectangle: string;
+            rectangle_no_label: string;
+            circle: string;
+            circle_no_label: string;
+            polygon: string;
+            polygon_no_label: string;
+            polygon_point_intercept: string;
+            polygon_finish_fallback: string;
+        };
+        done: {
+            line: string;
+            rectangle: string;
+            rectangle_no_label: string;
+            circle: string;
+            circle_no_label: string;
+            polygon: string;
+            polygon_no_label: string;
+            polygon_point_intercept_ok: string;
+            polygon_point_intercept_end: string;
+            polygon_finish_fallback_ok: string;
+            polygon_finish_fallback_blocked: string;
+        };
+    };
+    overlay: {
+        marker_mode: string;
+        marker_added: string;
+        marker_position: string;
+        sample_marker_label: string;
+        sample_marker_added: string;
+        icon_added: string;
+        icon_clicked: string;
+        svg_added: string;
+        svg_clicked: string;
+        polyline_added: string;
+        polyline_clicked: string;
+        line_added: string;
+        line_clicked: string;
+        area_added: string;
+        area_a_clicked: string;
+        area_b_clicked: string;
+        circle_added: string;
+        circle_a_clicked: string;
+        circle_b_clicked: string;
+        circle_c_clicked: string;
+        circle_d_clicked: string;
+        circle_e_clicked: string;
+        circle_alarm_clicked: string;
+        circle_detect_clicked: string;
+        rectangle_added: string;
+        rectangle_a_clicked: string;
+        rectangle_b_clicked: string;
+        rectangle_c_clicked: string;
+        rectangle_d_clicked: string;
+        rectangle_e_clicked: string;
+        highlight_need_rect_b: string;
+        highlight_need_rect_e: string;
+        info_window_added: string;
+        info_clicked: string;
+        info_window_title: string;
+        info_window_desc: string;
+        ring_added: string;
+        ring_clicked: string;
+        edit_mode_on: string;
+        edit_mode_off: string;
+        edit_stopped: string;
+    };
+};
+export default enUS;

package/dist/i18n/index.d.ts

@@ -0,0 +1,3 @@
+import { I18nLike } from '../libs/i18n';
+export declare const i18n: I18nLike;
+export type { I18nLike };