@xingm/vmap-cesium-toolbar 0.0.2-alpha.15 → 0.0.2-alpha.17

package/README.md

@@ -28,12 +28,14 @@ import { CesiumMapToolbar, initCesium } from '@xingm/vmap-cesium-toolbar';
 import '@xingm/vmap-cesium-toolbar/style';
 
 // 初始化Cesium
-const viewer = initCesium('cesiumContainer', {
-  terrainProvider: Cesium.createWorldTerrain()
-});
+(async () => {
+  const { viewer } = await initCesium('cesiumContainer', {
+    terrainProvider: Cesium.createWorldTerrain(),
+  });
 
-// 创建工具栏
-const toolbar = new CesiumMapToolbar(viewer, document.getElementById('toolbar'));
+  // 创建工具栏
+  const toolbar = new CesiumMapToolbar(viewer, document.getElementById('toolbar'));
+})();
 ```
 
 ### Vue 3 项目中使用
@@ -52,11 +54,12 @@ import '@xingm/vmap-cesium-toolbar/style';
 let viewer;
 let toolbar;
 
-onMounted(() => {
+onMounted(async () => {
   // 初始化Cesium
-  viewer = initCesium('cesiumContainer', {
-    terrainProvider: Cesium.createWorldTerrain()
+  const result = await initCesium('cesiumContainer', {
+    terrainProvider: Cesium.createWorldTerrain(),
   });
+  viewer = result.viewer;
 
   // 创建工具栏
   toolbar = new CesiumMapToolbar(viewer, document.getElementById('toolbar'));
@@ -80,30 +83,26 @@ const toolbar = new CesiumMapToolbar(
 );
 ```
 
-### CesiumMapHelper
+### DrawHelper
 
-地图辅助工具类，提供绘制和测量功能。
+绘制工具类（包的默认导出），提供线/面/矩形/圆等交互绘制能力。
 
 ```typescript
-import { CesiumMapHelper } from '@xingm/vmap-cesium-toolbar';
+import DrawHelper from '@xingm/vmap-cesium-toolbar';
 
-const helper = new CesiumMapHelper(viewer);
-helper.startDrawing('line');  // 开始绘制线条
-helper.startMeasurement('distance'); // 开始距离测量
+const drawHelper = new DrawHelper(viewer);
+drawHelper.startDrawingPolygon();
 ```
 
-### CesiumMapLoader
+### initCesium
 
-Cesium初始化工具，简化Cesium的配置和初始化。
+Cesium 初始化函数，简化 Viewer 创建、底图/地形与初始视角配置。
 
 ```typescript
-import { CesiumMapLoader } from '@xingm/vmap-cesium-toolbar';
+import { initCesium } from '@xingm/vmap-cesium-toolbar';
 
-const viewer = CesiumMapLoader.init('container', {
-  terrainProvider: Cesium.createWorldTerrain(),
-  imageryProvider: new Cesium.OpenStreetMapImageryProvider({
-    url: 'https://a.tile.openstreetmap.org/'
-  })
+const { viewer } = await initCesium('cesiumContainer', {
+  cesiumToken: 'your_cesium_ion_token',
 });
 ```
 
@@ -231,6 +230,7 @@ npm run dev
 - [CesiumMapToolbar API](./doc/CesiumMapToolbar_API.md)
 - [CesiumMapHelper API](./doc/CesiumMapHelper_API.md)
 - [CesiumMapLoader API](./doc/CesiumMapLoader_API.md)
+- [CesiumOverlayService API](./doc/CesiumOverlayService_API.md)
 
 ## 依赖要求
 

package/dist/hooks/toolBarConfig.d.ts

@@ -15,6 +15,7 @@ export declare const useToolBarConfig: (viewer: Viewer | undefined, message: Ref
             id: string;
             icon: string;
             title: string;
+            titleKey: string;
             color: string;
             borderColor: string;
             backgroundColor: string;
@@ -25,6 +26,7 @@ export declare const useToolBarConfig: (viewer: Viewer | undefined, message: Ref
             id: string;
             icon: string;
             title: string;
+            titleKey: string;
             color: string;
             backgroundColor: string;
             borderColor?: undefined;
@@ -36,6 +38,7 @@ export declare const useToolBarConfig: (viewer: Viewer | undefined, message: Ref
             icon: boolean;
             activeIcon: boolean;
             title: string;
+            titleKey: string;
             color: string;
             backgroundColor: string;
             borderColor?: undefined;
@@ -45,6 +48,7 @@ export declare const useToolBarConfig: (viewer: Viewer | undefined, message: Ref
             id: string;
             icon: string;
             title: string;
+            titleKey: string;
             color: string;
             borderColor: string;
             backgroundColor: string;

package/dist/hooks/useOverlayHelper.d.ts

@@ -232,6 +232,7 @@ export declare function useOverlayHelper(viewer: Ref<Cesium.Viewer | undefined>,
     addLine: () => void;
     addArea: () => void;
     addCircle: () => void;
+    addCircle123: () => void;
     addRing: (i?: number) => Cesium.Entity | undefined;
     addPolygon: () => void;
     addRectangle: () => void;

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

@@ -0,0 +1,135 @@
+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;
+        };
+    };
+    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;
+    };
+};
+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 };

package/dist/i18n/zh-CN.d.ts

@@ -0,0 +1,135 @@
+declare const zhCN: {
+    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;
+        };
+    };
+    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;
+    };
+};
+export default zhCN;

package/dist/index.d.ts

@@ -3,6 +3,20 @@
 import type * as Cesium from 'cesium';
 import type { Viewer, Cartesian3, Entity, Color } from 'cesium';
 
+export type Locale = 'zh-CN' | 'en-US' | (string & {});
+
+export interface I18nLike {
+  getLocale(): Locale;
+  setLocale(locale: Locale, options?: { persist?: boolean }): void;
+  t(key: string, params?: Record<string, any>, localeOverride?: Locale): string;
+  onLocaleChange(cb: (locale: Locale) => void): () => void;
+  bindElement(el: HTMLElement, key: string, attr?: 'text' | 'title' | 'placeholder', params?: Record<string, any>): void;
+  updateTree(root: HTMLElement): void;
+  addMessages?(locale: Locale, dict: Record<string, any>, options?: { merge?: boolean }): void;
+  setFallbackLocale?(locale: Locale): void;
+  configure?(options: { persist?: boolean; useStoredLocale?: boolean; fallbackLocale?: Locale; locale?: Locale }): void;
+}
+
 // 工具栏配置接口（与 CesiumMapModel.ts 保持一致）
 export interface ToolbarConfig {
   position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
@@ -15,6 +29,8 @@ export interface ToolbarConfig {
   boxShadow?: string;
   zIndex?: number;
   buttons?: CustomButtonConfig[];
+  useI18n?: boolean;
+  i18n?: I18nLike;
 }
 
 // 按钮配置接口（内部默认按钮配置使用）
@@ -23,6 +39,7 @@ export interface ButtonConfig {
   id: string;
   icon: string;
   title: string;
+  titleKey?: string;
   size?: number;
   color?: string;
   borderColor?: string;
@@ -40,6 +57,7 @@ export interface CustomButtonConfig {
   id: string;
   icon: string | HTMLElement | false;
   title: string;
+  titleKey?: string;
   enabled?: boolean;
   visible?: boolean;
   size?: number;
@@ -92,12 +110,15 @@ export interface ZoomCallback {
 export interface MapType {
   id: string;
   name: string;
+  nameKey?: string;
   thumbnail: string;
   provider: (token: string) => Cesium.ImageryProvider[];
   terrainProvider?: (token: string) => Cesium.TerrainProvider | null;
   geoWTFS?: (token: string, viewer: Cesium.Viewer) => any | null;
 }
 
+export const i18n: I18nLike;
+
 // 视锥体选项接口
 export interface FrustumOptions {
   position?: Cartesian3;
@@ -198,9 +219,10 @@ export interface InitOptions {
   requestRenderMode?: boolean;
   token?: string;
   cesiumToken?: string;
-  orderIndependentTranslucency?: boolean // 无序半透明度,
-  fxaa?: boolean, // 启用FXAA后处理抗锯齿
-  msaaSamples?: number, // MSAA采样数（推荐4或8）,
+  maximumRenderTimeChange?: number; // 最大渲染时间变化
+  orderIndependentTranslucency?: boolean; // 无序半透明度,
+  fxaa?: boolean; // 启用FXAA后处理抗锯齿
+  msaaSamples?: number; // MSAA采样数（推荐4或8）
   success?: () => void;
   cancel?: () => void;
   mapCenter?: MapCenter;
@@ -216,9 +238,33 @@ export declare class CesiumMapToolbar {
       search?: SearchCallback;
       measurement?: MeasurementCallback;
       zoom?: ZoomCallback;
+      fullscreen?: (isFullscreen: boolean) => void;
+      resetLocation?: () => void;
     },
     initialCenter?: { longitude: number; latitude: number; height: number }
   );
+
+  /** 天地图 Token（可直接修改或配合 setTDToken） */
+  TD_Token: string;
+
+  /** 当前可用的底图类型列表 */
+  mapTypes: MapType[];
+
+  /** 获取内部搜索服务实例 */
+  getSearchService(): SearchService;
+
+  /** 获取内部禁飞区服务实例 */
+  getNotFlyZonesService(): NotFlyZonesService;
+
+  /** 获取内部测量服务实例 */
+  getMeasurementService(): any; // MeasurementService (内部未在 d.ts 中单独暴露)
+
+  /** 获取内部地图控制器实例 */
+  getCesiumMapCtrl(): CesiumMapController;
+
+  /** 获取内部图层服务实例 */
+  getMapLayersService(): MapLayersService;
+
   setMapTypes(mapTypes: MapType[]): void;
   setTDToken(TD_Token: string): void;
   setInitialCenter(center: { longitude: number; latitude: number; height: number }): void;
@@ -298,6 +344,9 @@ export interface OverlayEntity extends Entity {
   _innerRadius?: number;
   _outerRectangle?: Cesium.Rectangle;
 
+  /** primitive layer key: 用于分层批处理路由 */
+  _primitiveLayerKey?: string;
+
   /** primitive circle: 内部使用的纯色缓存（用于高亮恢复） */
   _primitiveRingBaseColor?: any;
   _primitiveFillBaseColor?: any;
@@ -451,6 +500,8 @@ export interface PolygonOptions {
   clickHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   hoverHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   onClick?: (entity: Entity) => void;
+  /** primitive 分层渲染 key（不同 key 会进入不同批次并按创建顺序确定上下层） */
+  layerKey?: string;
   id?: string;
 }
 
@@ -469,6 +520,8 @@ export interface RectangleOptions {
   clickHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   hoverHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   onClick?: (entity: Entity) => void;
+  /** primitive 分层渲染 key（不同 key 会进入不同批次并按创建顺序确定上下层） */
+  layerKey?: string;
   id?: string;
 }
 
@@ -489,6 +542,8 @@ export interface CircleOptions {
   clickHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   hoverHighlight?: boolean | { color?: any | string; fillAlpha?: number };
   onClick?: (entity: Entity) => void;
+  /** primitive 分层渲染 key（不同 key 会进入不同批次并按创建顺序确定上下层） */
+  layerKey?: string;
   id?: string;
 }
 
@@ -676,6 +731,10 @@ export interface CesiumMapControllerOptions {
   getToken?: () => string;
   zoomCallback?: ZoomCallback;
   onSceneModeChanged?: () => void;
+    /** 全屏切换回调 */
+  fullscreenCallback?: (isFullscreen: boolean) => void;
+  /** 复位位置回调 */
+  resetLocationCallback?: () => void;
 }
 
 export declare class CesiumMapController {
@@ -779,6 +838,14 @@ export interface DrawOptions {
    * 默认 true；设为 false 可禁用绘制完成后自动创建的面积标签。
    */
   showAreaLabel?: boolean;
+
+  /**
+   * 是否启用多边形自相交校验。
+   * - false/未设置：默认允许交叉（不做校验）
+   * - true：启用自相交校验（结合 selfIntersectionAllowTouch/AllowContinue 控制行为）
+   */
+  selfIntersectionEnabled?: boolean;
+  
   /**
    * 多边形自相交校验：是否允许“擦边/顶点落在旧边上”等仅接触（touch）情况。
    * - false/未设置：touch 也视为不合法