cesium-xs-sdk 1.0.0

package/src/index.d.ts

@@ -0,0 +1,358 @@
+// 基础类型别名
+type LonLat = [number, number, number?];
+type LonLatArray = LonLat[];
+
+// 用 any 占位 Cesium 类型，避免对 cesium 包类型的强依赖
+// 这样既能提供完整的 SDK 方法自动补全，又不会在 JS/HTML 项目中出现类型解析错误
+type CesiumColor = any;
+type CesiumCartesian2 = any;
+type CesiumCartesian3 = any;
+type CesiumCartographic = any;
+type CesiumHeightReference = any;
+type CesiumViewer = any;
+type CesiumEntity = any;
+type CesiumMaterial = any;
+
+// ==================== 枚举 ====================
+
+/**
+ * 图层类型
+ */
+export type LayerType = 'xyz' | 'wmts' | 'wms' | 'tms' | 'single_image' | 'terrain' | '3dtiles';
+
+/**
+ * 标绘图元类型
+ */
+export type PlotGraphicType =
+  | 'triangle'
+  | 'sector'
+  | 'ellipse'
+  | 'fineArrow'
+  | 'assaultDirection'
+  | 'attackArrow'
+  | 'swallowtailAttackArrow'
+  | 'squadCombat'
+  | 'swallowtailSquadCombat'
+  | 'doubleArrow'
+  | 'straightArrow'
+  | 'curvedArrow'
+  | 'curve';
+
+/**
+ * 绘制工具类型
+ */
+export type DrawType =
+  | 'point'
+  | 'line'
+  | 'polygon'
+  | 'fineArrow'
+  | 'straightArrow'
+  | 'assaultDirection'
+  | 'triangle'
+  | 'sector'
+  | 'ellipse'
+  | 'attackArrow'
+  | 'swallowtailAttackArrow'
+  | 'squadCombat'
+  | 'swallowtailSquadCombat'
+  | 'doubleArrow'
+  | 'curvedArrow'
+  | 'curve';
+
+/**
+ * 编辑模式
+ */
+export type EditMode = 'vertex' | 'move';
+
+/**
+ * 选择类型
+ */
+export type SelectType = 'point' | 'box';
+
+/**
+ * 删除模式
+ */
+export type DeleteMode = 'single' | 'multiple';
+
+/**
+ * 工具名称
+ */
+export type ToolName = 'draw' | 'edit' | 'select' | 'delete';
+
+// ==================== 包装器 ====================
+
+/**
+ * 点图元包装器
+ */
+export class PointWrapper {
+  setPosition(coords: LonLat): this;
+  setColor(color: CesiumColor): this;
+  setPixelSize(size: number): this;
+  setVisible(visible: boolean): this;
+  setHeightReference(ref: CesiumHeightReference): this;
+  setDisableDepthTestDistance(distance: number): this;
+  setOutlineColor(color: CesiumColor): this;
+  setOutlineWidth(width: number): this;
+  setName(name: string): this;
+  setNameVisible(visible: boolean): this;
+  setText(text: string, options?: Record<string, any>): this;
+  setFont(font: string): this;
+  setTextColor(color: CesiumColor): this;
+  setTextOutlineColor(color: CesiumColor): this;
+  setTextOutlineWidth(width: number): this;
+  setAlignType(alignType: number): this;
+  setTextPixelOffset(offset: CesiumCartesian2): this;
+  setTextScale(scale: number): this;
+  remove(): this;
+}
+
+/**
+ * 线图元包装器
+ */
+export class LineWrapper {
+  setPositions(coords: LonLatArray): this;
+  setColor(color: CesiumColor): this;
+  setWidth(width: number): this;
+  setMaterial(material: CesiumMaterial | CesiumColor): this;
+  setVisible(visible: boolean): this;
+  setClampToGround(clamp: boolean): this;
+  setName(name: string): this;
+  setLabel(text: string, options?: Record<string, any>): this;
+  remove(): this;
+}
+
+/**
+ * 面图元包装器
+ */
+export class PolygonWrapper {
+  setPositions(coords: LonLatArray): this;
+  setColor(color: CesiumColor): this;
+  setOutlineColor(color: CesiumColor): this;
+  setOutlineWidth(width: number): this;
+  setVisible(visible: boolean): this;
+  setClampToGround(clamp: boolean): this;
+  setHeightReference(ref: CesiumHeightReference): this;
+  setName(name: string): this;
+  setLabel(text: string, options?: Record<string, any>): this;
+  remove(): this;
+}
+
+/**
+ * 模型图元包装器
+ */
+export class ModelWrapper {
+  setPosition(coords: LonLat): this;
+  setUri(uri: string): this;
+  setScale(scale: number): this;
+  setMinimumPixelSize(size: number): this;
+  setVisible(visible: boolean): this;
+  setHeightReference(ref: CesiumHeightReference): this;
+  setName(name: string): this;
+  remove(): this;
+}
+
+/**
+ * 文本图元包装器
+ */
+export class TextWrapper {
+  setPosition(coords: LonLat): this;
+  setText(text: string): this;
+  setFont(font: string): this;
+  setColor(color: CesiumColor): this;
+  setOutlineColor(color: CesiumColor): this;
+  setOutlineWidth(width: number): this;
+  setPixelOffset(offset: CesiumCartesian2): this;
+  setVisible(visible: boolean): this;
+  setHeightReference(ref: CesiumHeightReference): this;
+  setName(name: string): this;
+  remove(): this;
+}
+
+/**
+ * 图层包装器
+ */
+export interface LayerWrapper {
+  setVisible(visible: boolean): this;
+  setAlpha?(alpha: number): this;
+  setBrightness?(brightness: number): this;
+  setContrast?(contrast: number): this;
+  setHue?(hue: number): this;
+  setSaturation?(saturation: number): this;
+  setGamma?(gamma: number): this;
+  getExtent?(): number[];
+  locateTo?(): void;
+  remove(): this;
+  [key: string]: any;
+}
+
+// ==================== 模块 ====================
+
+/**
+ * 场景模块
+ */
+export class SceneModule {
+  lonLatToWorld(lon: number, lat: number, height?: number): CesiumCartesian3;
+  worldToLonLat(cartesian: CesiumCartesian3): LonLat;
+  screenToWorld(x: number, y: number): CesiumCartesian3 | null;
+  worldToScreen(cartesian: CesiumCartesian3): CesiumCartesian2;
+  screenToLonLat(x: number, y: number): LonLat | null;
+  lonLatToScreen(lon: number, lat: number, height?: number): CesiumCartesian2;
+  lonLatToCartographic(lon: number, lat: number, height?: number): CesiumCartographic;
+  cartographicToLonLat(cartographic: CesiumCartographic): LonLat;
+  createLayer(url: string, options?: Record<string, any>): Promise<LayerWrapper>;
+  removeLayer(layerId: string): boolean;
+  getLayer(layerId: string): LayerWrapper | undefined;
+  flyToLonLat(params?: { lon?: number; lat?: number; height?: number; duration?: number }): void;
+  setView(params?: { lon?: number; lat?: number; height?: number; heading?: number; pitch?: number; roll?: number }): void;
+}
+
+/**
+ * 图元模块
+ */
+export class GraphicModule {
+  createPoint(graphicId: string): PointWrapper;
+  createLine(graphicId: string): LineWrapper;
+  createPolygon(graphicId: string): PolygonWrapper;
+  createModel(graphicId: string): ModelWrapper;
+  createText(graphicId: string): TextWrapper;
+  createPlotGraphic(graphicId: string, plotType: PlotGraphicType, controlPoints?: LonLatArray): LineWrapper | PolygonWrapper;
+  createFineArrow(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createAssaultDirection(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createStraightArrow(graphicId: string, controlPoints?: LonLatArray): LineWrapper;
+  createTriangle(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createSector(graphicId: string, center: LonLat, radius: number, startAngle: number, endAngle: number): PolygonWrapper;
+  createEllipse(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createAttackArrow(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createSwallowtailAttackArrow(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createSquadCombat(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createSwallowtailSquadCombat(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createDoubleArrow(graphicId: string, controlPoints?: LonLatArray): PolygonWrapper;
+  createCurvedArrow(graphicId: string, controlPoints?: LonLatArray): LineWrapper;
+  createCurve(graphicId: string, controlPoints?: LonLatArray): LineWrapper;
+  removeGraphic(graphicId: string): boolean;
+  getGraphic(graphicId: string): CesiumEntity | undefined;
+}
+
+/**
+ * 事件模块
+ */
+export class EventModule {
+  registerObserver(eventType: string, callback: (...args: any[]) => void): string;
+  unregisterObserver(eventType: string, observerId: string): void;
+  unregisterAllObservers(): void;
+  getZoomLevel(): number;
+}
+
+/**
+ * 编辑器模块
+ */
+export class EditorModule {
+  activateDrawTool(type?: DrawType): this;
+  activateSelectTool(type?: SelectType): this;
+  activateEditTool(mode?: EditMode): this;
+  activateDeleteTool(mode?: DeleteMode): this;
+  deactivateTool(): this;
+  getDrawTool(): any;
+  getSelectTool(): any;
+  getEditTool(): any;
+  onDrawComplete(callback: (data: any) => void): this;
+  onDrawProgress(callback: (data: any) => void): this;
+  onDrawCancel(callback: () => void): this;
+  onEditComplete(callback: (data: any) => void): this;
+  onEditSelect(callback: (data: any) => void): this;
+  onSelect(callback: (data: any) => void): this;
+  onSelectionChange(callback: (data: any) => void): this;
+  onSelectionComplete(callback: (data: any) => void): this;
+  onBeforeDelete(callback: (data: any) => void): this;
+  onDelete(callback: (data: any) => void): this;
+  onDeleteMultiple(callback: (data: any) => void): this;
+}
+
+/**
+ * 模块管理器
+ */
+export class ModuleManager {
+  /** Cesium Viewer 实例 */
+  readonly cesiumViewer: CesiumViewer;
+  /** Cesium Viewer 快捷别名 */
+  readonly viewer: CesiumViewer;
+  /** 获取任意模块（保留向后兼容） */
+  getModule(moduleName: string): any;
+  /** 场景模块 */
+  readonly sceneModule: SceneModule;
+  /** 图元模块 */
+  readonly graphicModule: GraphicModule;
+  /** 事件模块 */
+  readonly eventModule: EventModule;
+  /** 编辑器模块 */
+  readonly editorModule: EditorModule;
+  /** 销毁 SDK */
+  destroy(): void;
+  /** 重置单例 */
+  static reset(): void;
+}
+
+/**
+ * 全局配置类
+ */
+export class Config {
+  static getInstance(): Config;
+  setConfig(options: Record<string, any>): void;
+  getConfig(): Record<string, any>;
+}
+
+/**
+ * 坐标工具类
+ */
+export class CoordinateUtil {
+  // 具体方法可按需补充
+}
+
+/**
+ * 地理计算工具类
+ */
+export class GeoCalcUtil {
+  // 具体方法可按需补充
+}
+
+// ==================== SDK 入口 ====================
+
+interface Xs3dSDK {
+  /**
+   * 初始化 SDK
+   * @param container 容器元素 ID 或 HTMLElement
+   * @param config 初始化配置
+   */
+  init(container: string | HTMLElement, config?: Record<string, any>): ModuleManager;
+  /**
+   * 获取模块（保留向后兼容）
+   * @deprecated 推荐通过 init 返回的实例访问模块
+   */
+  getModule(moduleName: string): any;
+  /** 销毁 SDK */
+  destroy(): void;
+
+  Config: typeof Config;
+  ModuleManager: typeof ModuleManager;
+  SceneModule: typeof SceneModule;
+  GraphicModule: typeof GraphicModule;
+  EventModule: typeof EventModule;
+  EditorModule: typeof EditorModule;
+  CoordinateUtil: typeof CoordinateUtil;
+  GeoCalcUtil: typeof GeoCalcUtil;
+
+  DrawType: Record<string, DrawType>;
+  EditMode: Record<string, EditMode>;
+  SelectType: Record<string, SelectType>;
+  DeleteMode: Record<string, DeleteMode>;
+  ToolName: Record<string, ToolName>;
+  LayerType: Record<string, LayerType>;
+  PlotGraphicType: Record<string, PlotGraphicType>;
+}
+
+declare const xs3d: Xs3dSDK;
+export default xs3d;
+
+// 命名导出（与 index.js 保持一致）
+export { Config, ModuleManager, SceneModule, GraphicModule, EventModule, EditorModule, CoordinateUtil, GeoCalcUtil };
+export { DrawType, EditMode, SelectType, DeleteMode, ToolName, LayerType, PlotGraphicType };

package/src/index.js

@@ -0,0 +1,59 @@
+// src/index.js
+import { Config } from './core/Config.js';
+import { ModuleManager } from './core/ModuleManager.js';
+import { SceneModule, LayerType } from './modules/SceneModule.js';
+import { GraphicModule } from './modules/GraphicModule.js';
+import { EventModule } from './modules/EventModule.js';
+import { EditorModule, DrawType, EditMode, SelectType, DeleteMode, ToolName } from './modules/EditorModule.js';
+import { PlotGraphicType } from './modules/PlotGraphicType.js';
+import { CoordinateUtil } from './utils/CoordinateUtil.js';
+import { GeoCalcUtil } from './utils/GeoCalcUtil.js';
+
+// 核心 SDK 实例（直接导出，无嵌套）
+const xs3d = {
+    // 初始化 SDK
+    init: (container, config = {}) => {
+        // 设置 Cesium Token（提前处理，避免内部模块重复设置）
+        if (config.cesiumToken) {
+            window.Cesium.Ion.defaultAccessToken = config.cesiumToken;
+        }
+        // 设置全局配置
+        Config.getInstance().setConfig(config);
+        // 初始化模块管理器
+        const moduleManager = ModuleManager.getInstance();
+        moduleManager.initViewer(container);
+        return moduleManager;
+    },
+    // 获取模块
+    getModule: (moduleName) => {
+        return ModuleManager.getInstance().getModule(moduleName);
+    },
+    // 销毁 SDK
+    destroy: () => {
+        ModuleManager.reset();
+        Config.getInstance().setConfig({});
+        if (window.Cesium?.Ion) {
+            window.Cesium.Ion.defaultAccessToken = '';
+        }
+    },
+    // 暴露核心类（方便高级使用）
+    Config,
+    ModuleManager,
+    SceneModule,
+    GraphicModule,
+    EventModule,
+    EditorModule,
+    CoordinateUtil,
+    GeoCalcUtil,
+    // 导出工具枚举
+    DrawType,
+    EditMode,
+    SelectType,
+    DeleteMode,
+    ToolName,
+    LayerType,
+    PlotGraphicType
+};
+
+// 仅默认导出（Rollup 会自动处理 UMD 全局变量）
+export default xs3d;