cesium-xs-sdk 1.0.0

package/src/modules/GraphicModule.js

@@ -0,0 +1,1037 @@
+import { Config } from '../core/Config.js';
+import { PlotGeometryUtil } from '../utils/PlotGeometryUtil.js';
+import { PlotGraphicType, isLinePlotType } from './PlotGraphicType.js';
+
+/**
+ * 点图元包装器
+ */
+class PointWrapper {
+  constructor(graphicModule, entity) {
+    this._entity = entity;
+    this._graphicModule = graphicModule;
+  }
+
+  setPosition(coords) {
+    this._entity.position = Cesium.Cartesian3.fromDegrees(...coords);
+    return this;
+  }
+
+  setColor(color) {
+    this._entity.point.color = color;
+    return this;
+  }
+
+  setPixelSize(size) {
+    this._entity.point.pixelSize = size;
+    return this;
+  }
+
+  setVisible(visible) {
+    this._entity.show = visible;
+    return this;
+  }
+
+  setHeightReference(ref) {
+    this._entity.point.heightReference = ref;
+    return this;
+  }
+
+  setDisableDepthTestDistance(distance) {
+    this._entity.point.disableDepthTestDistance = distance;
+    return this;
+  }
+
+
+  setOutlineColor(color) {
+    this._entity.point.outlineColor = color;
+    return this;
+  }
+
+  setOutlineWidth(width) {
+    this._entity.point.outlineWidth = width;
+    return this;
+  }
+
+  setName(name) {
+    this._entity.id = name;
+    return this;
+  }
+
+  // 名称标签相关
+  setNameVisible(visible) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.show = visible;
+    return this;
+  }
+
+  setText(text, options = {}) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.text = text;
+
+    // 应用配置选项
+    this._entity.label.disableDepthTestDistance = options.disableDepthTestDistance ?? Number.POSITIVE_INFINITY;
+    this._entity.label.verticalOrigin = options.verticalOrigin ?? Cesium.VerticalOrigin.BOTTOM;
+    this._entity.label.eyeOffset = options.eyeOffset ?? new Cesium.Cartesian3(0, 0, -10);
+    this._entity.label.heightReference = options.heightReference ?? Cesium.HeightReference.RELATIVE_TO_GROUND;
+
+    return this;
+  }
+
+  setFont(font) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.font = font;
+    return this;
+  }
+
+  setTextColor(color) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.fillColor = color;
+    return this;
+  }
+
+  setTextOutlineColor(color) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.outlineColor = color;
+    return this;
+  }
+
+  setTextOutlineWidth(width) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.outlineWidth = width;
+    return this;
+  }
+
+  setAlignType(alignType) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    // alignType: 0=CENTER, 1=LEFT, 2=RIGHT, 3=TOP, 4=BOTTOM
+    const horizontalOrigins = [Cesium.HorizontalOrigin.CENTER, Cesium.HorizontalOrigin.LEFT, Cesium.HorizontalOrigin.RIGHT];
+    const verticalOrigins = [Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.TOP, Cesium.VerticalOrigin.BOTTOM];
+    this._entity.label.horizontalOrigin = horizontalOrigins[alignType] || Cesium.HorizontalOrigin.CENTER;
+    this._entity.label.verticalOrigin = verticalOrigins[alignType] || Cesium.VerticalOrigin.CENTER;
+    return this;
+  }
+
+  setTextPixelOffset(offset) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.pixelOffset = offset;
+    return this;
+  }
+
+  setTextScale(scale) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.scale = scale;
+    return this;
+  }
+
+  remove() {
+    this._graphicModule.removeGraphic(this._entity.id);
+    return this;
+  }
+}
+
+/**
+ * 线图元包装器
+ */
+class LineWrapper {
+  constructor(graphicModule, entity) {
+    this._entity = entity;
+    this._graphicModule = graphicModule;
+  }
+
+  setPositions(coords) {
+    this._entity.polyline.positions = Cesium.Cartesian3.fromDegreesArrayHeights(
+      coords.flatMap(coord => [coord[0], coord[1], coord[2] || 0])
+    );
+    return this;
+  }
+
+  setColor(color) {
+    this._entity.polyline.material = color;
+    return this;
+  }
+
+  setWidth(width) {
+    this._entity.polyline.width = width;
+    return this;
+  }
+
+  setMaterial(material) {
+    this._entity.polyline.material = material;
+    return this;
+  }
+
+  setVisible(visible) {
+    this._entity.show = visible;
+    return this;
+  }
+
+  setClampToGround(clamp) {
+    this._entity.polyline.clampToGround = clamp;
+    return this;
+  }
+
+  setName(name) {
+    this._entity.id = name;
+    return this;
+  }
+
+  /**
+   * 在图元上附加标签，标签位置随几何变化自动更新
+   * @param {string} text 标签文字
+   * @param {object} options 标签样式 { font, color, outlineColor, outlineWidth, pixelOffset, horizontalOrigin, verticalOrigin }
+   * @returns {LineWrapper}
+   */
+  setLabel(text, options = {}) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.text = text;
+    this._entity.label.font = options.font || '14px Microsoft YaHei';
+    this._entity.label.fillColor = options.color || Cesium.Color.WHITE;
+    this._entity.label.outlineColor = options.outlineColor || Cesium.Color.BLACK;
+    this._entity.label.outlineWidth = options.outlineWidth ?? 1;
+    this._entity.label.show = true;
+    this._entity.label.pixelOffset = options.pixelOffset || new Cesium.Cartesian2(0, -10);
+    this._entity.label.horizontalOrigin = options.horizontalOrigin ?? Cesium.HorizontalOrigin.CENTER;
+    this._entity.label.verticalOrigin = options.verticalOrigin ?? Cesium.VerticalOrigin.BOTTOM;
+
+    // 使用 CallbackProperty 动态计算标签锚点，随编辑/平移自动更新
+    const self = this;
+    this._entity.position = new Cesium.CallbackProperty(function () {
+      const anchor = self._computeLabelAnchor();
+      return Cesium.Cartesian3.fromDegrees(anchor[0], anchor[1], anchor[2] || 0);
+    }, false);
+
+    return this;
+  }
+
+  /**
+   * 计算标签锚点 [lon, lat, height]
+   * 标绘图元使用控制点重心，普通线图元使用顶点平均
+   * @private
+   */
+  _computeLabelAnchor() {
+    if (this._entity._isPlotGraphic && this._entity._controlPoints?.length) {
+      const cps = this._entity._controlPoints;
+      let x = 0, y = 0, z = 0;
+      cps.forEach(cp => {
+        x += cp[0];
+        y += cp[1];
+        z += cp[2] || 0;
+      });
+      return [x / cps.length, y / cps.length, z / cps.length];
+    }
+
+    const positions = this._entity.polyline?.positions?.getValue(Cesium.JulianDate.now());
+    if (positions && positions.length > 0) {
+      let lon = 0, lat = 0, height = 0;
+      positions.forEach(p => {
+        const c = Cesium.Cartographic.fromCartesian(p);
+        lon += Cesium.Math.toDegrees(c.longitude);
+        lat += Cesium.Math.toDegrees(c.latitude);
+        height += c.height || 0;
+      });
+      const count = positions.length;
+      return [lon / count, lat / count, height / count];
+    }
+
+    return [0, 0, 0];
+  }
+
+  /**
+   * 设置为参数化标绘图元
+   * @param {string} plotType PlotGraphicType
+   * @param {Array} controlPoints 控制点 [lon, lat, height][]
+   * @param {object} options 标绘参数
+   * @returns {LineWrapper}
+   */
+  setPlotType(plotType, controlPoints, options = {}) {
+    this._entity._isPlotGraphic = true;
+    this._entity._plotType = plotType;
+    this._entity._controlPoints = JSON.parse(JSON.stringify(controlPoints));
+
+    const factoryName = `create${this._capitalizePlotType(plotType)}`;
+    if (!PlotGeometryUtil[factoryName]) {
+      console.warn(`未知标绘类型: ${plotType}`);
+      return this;
+    }
+
+    const positions = PlotGeometryUtil[factoryName](controlPoints, options);
+    this.setPositions(positions);
+    return this;
+  }
+
+  /**
+   * 更新标绘图元控制点并重算几何
+   * @param {Array} controlPoints 控制点 [lon, lat, height][]
+   * @param {object} options 标绘参数
+   * @returns {LineWrapper}
+   */
+  setControlPoints(controlPoints, options = {}) {
+    if (!this._entity._isPlotGraphic) {
+      console.warn('非标绘图元，请使用 setPositions');
+      return this;
+    }
+    return this.setPlotType(this._entity._plotType, controlPoints, options);
+  }
+
+  /**
+   * 将标绘类型名转为工厂方法名
+   * @private
+   */
+  _capitalizePlotType(plotType) {
+    return plotType
+      .replace(/-([a-z])/g, (g) => g[1].toUpperCase())
+      .replace(/^./, s => s.toUpperCase());
+  }
+
+  remove() {
+    this._graphicModule.removeGraphic(this._entity.id);
+    return this;
+  }
+}
+
+/**
+ * 面图元包装器
+ */
+class PolygonWrapper {
+  constructor(graphicModule, entity) {
+    this._entity = entity;
+    this._graphicModule = graphicModule;
+  }
+
+  setPositions(coords) {
+    this._entity.polygon.hierarchy = new Cesium.PolygonHierarchy(
+      Cesium.Cartesian3.fromDegreesArrayHeights(
+        coords.flatMap(coord => [coord[0], coord[1], coord[2] || 0])
+      )
+    );
+    return this;
+  }
+
+  setColor(color) {
+    this._entity.polygon.material = color;
+    return this;
+  }
+
+  setOutlineColor(color) {
+    this._entity.polygon.outlineColor = color;
+    return this;
+  }
+
+  setOutlineWidth(width) {
+    this._entity.polygon.outlineWidth = width;
+    return this;
+  }
+
+  setVisible(visible) {
+    this._entity.show = visible;
+    return this;
+  }
+
+  setClampToGround(clamp) {
+    this._entity.polygon.clampToGround = clamp;
+    return this;
+  }
+
+  setHeightReference(ref) {
+    this._entity.polygon.heightReference = ref;
+    return this;
+  }
+
+  setName(name) {
+    this._entity.id = name;
+    return this;
+  }
+
+  /**
+   * 在图元上附加标签，标签位置随几何变化自动更新
+   * @param {string} text 标签文字
+   * @param {object} options 标签样式 { font, color, outlineColor, outlineWidth, pixelOffset, horizontalOrigin, verticalOrigin }
+   * @returns {PolygonWrapper}
+   */
+  setLabel(text, options = {}) {
+    if (!this._entity.label) {
+      this._entity.label = new Cesium.LabelGraphics();
+    }
+    this._entity.label.text = text;
+    this._entity.label.font = options.font || '14px Microsoft YaHei';
+    this._entity.label.fillColor = options.color || Cesium.Color.WHITE;
+    this._entity.label.outlineColor = options.outlineColor || Cesium.Color.BLACK;
+    this._entity.label.outlineWidth = options.outlineWidth ?? 1;
+    this._entity.label.show = true;
+    this._entity.label.pixelOffset = options.pixelOffset || new Cesium.Cartesian2(0, -10);
+    this._entity.label.horizontalOrigin = options.horizontalOrigin ?? Cesium.HorizontalOrigin.CENTER;
+    this._entity.label.verticalOrigin = options.verticalOrigin ?? Cesium.VerticalOrigin.BOTTOM;
+
+    // 使用 CallbackProperty 动态计算标签锚点，随编辑/平移自动更新
+    const self = this;
+    this._entity.position = new Cesium.CallbackProperty(function () {
+      const anchor = self._computeLabelAnchor();
+      return Cesium.Cartesian3.fromDegrees(anchor[0], anchor[1], anchor[2] || 0);
+    }, false);
+
+    return this;
+  }
+
+  /**
+   * 计算标签锚点 [lon, lat, height]
+   * 扇形固定在圆心，其他标绘使用控制点重心，普通面图元使用顶点重心
+   * @private
+   */
+  _computeLabelAnchor() {
+    if (this._entity._isPlotGraphic && this._entity._controlPoints?.length) {
+      const cps = this._entity._controlPoints;
+      if (this._entity._plotType === PlotGraphicType.SECTOR ||
+          this._entity._plotType === PlotGraphicType.ELLIPSE) {
+        return cps[0];
+      }
+      let x = 0, y = 0, z = 0;
+      cps.forEach(cp => {
+        x += cp[0];
+        y += cp[1];
+        z += cp[2] || 0;
+      });
+      return [x / cps.length, y / cps.length, z / cps.length];
+    }
+
+    const hierarchy = this._entity.polygon?.hierarchy?.getValue(Cesium.JulianDate.now());
+    if (hierarchy && hierarchy.positions && hierarchy.positions.length > 0) {
+      let lon = 0, lat = 0, height = 0;
+      hierarchy.positions.forEach(p => {
+        const c = Cesium.Cartographic.fromCartesian(p);
+        lon += Cesium.Math.toDegrees(c.longitude);
+        lat += Cesium.Math.toDegrees(c.latitude);
+        height += c.height || 0;
+      });
+      const count = hierarchy.positions.length;
+      return [lon / count, lat / count, height / count];
+    }
+
+    return [0, 0, 0];
+  }
+
+  /**
+   * 设置为参数化标绘图元
+   * @param {string} plotType PlotGraphicType
+   * @param {Array} controlPoints 控制点 [lon, lat, height][]
+   * @param {object} options 标绘参数
+   * @returns {PolygonWrapper}
+   */
+  setPlotType(plotType, controlPoints, options = {}) {
+    this._entity._isPlotGraphic = true;
+    this._entity._plotType = plotType;
+    this._entity._controlPoints = JSON.parse(JSON.stringify(controlPoints));
+
+    const factoryName = `create${this._capitalizePlotType(plotType)}`;
+    if (!PlotGeometryUtil[factoryName]) {
+      console.warn(`未知标绘类型: ${plotType}`);
+      return this;
+    }
+
+    const positions = PlotGeometryUtil[factoryName](controlPoints, options);
+    this.setPositions(positions);
+    return this;
+  }
+
+  /**
+   * 更新标绘图元控制点并重算几何
+   * @param {Array} controlPoints 控制点 [lon, lat, height][]
+   * @param {object} options 标绘参数
+   * @returns {PolygonWrapper}
+   */
+  setControlPoints(controlPoints, options = {}) {
+    if (!this._entity._isPlotGraphic) {
+      console.warn('非标绘图元，请使用 setPositions');
+      return this;
+    }
+    return this.setPlotType(this._entity._plotType, controlPoints, options);
+  }
+
+  /**
+   * 将标绘类型名转为工厂方法名
+   * @private
+   */
+  _capitalizePlotType(plotType) {
+    return plotType
+      .replace(/-([a-z])/g, (g) => g[1].toUpperCase())
+      .replace(/^./, s => s.toUpperCase());
+  }
+
+  remove() {
+    this._graphicModule.removeGraphic(this._entity.id);
+    return this;
+  }
+}
+
+/**
+ * 模型图元包装器
+ */
+class ModelWrapper {
+  constructor(graphicModule, entity) {
+    this._entity = entity;
+    this._graphicModule = graphicModule;
+  }
+
+  setPosition(coords) {
+    this._entity.position = Cesium.Cartesian3.fromDegrees(...coords);
+    return this;
+  }
+
+  setUrl(url) {
+    this._entity.model.uri = url;
+    return this;
+  }
+
+  setScale(scale) {
+    this._entity.model.scale = scale;
+    return this;
+  }
+
+  setMinimumPixelSize(size) {
+    this._entity.model.minimumPixelSize = size;
+    return this;
+  }
+
+  setVisible(visible) {
+    this._entity.show = visible;
+    return this;
+  }
+
+  setColor(color) {
+    this._entity.model.color = color;
+    return this;
+  }
+
+  setName(name) {
+    this._entity.id = name;
+    return this;
+  }
+
+  remove() {
+    this._graphicModule.removeGraphic(this._entity.id);
+    return this;
+  }
+}
+
+/**
+ * 文本图元包装器
+ */
+class TextWrapper {
+  constructor(graphicModule, entity) {
+    this._entity = entity;
+    this._graphicModule = graphicModule;
+  }
+
+  setPosition(coords) {
+    this._entity.position = Cesium.Cartesian3.fromDegrees(...coords);
+    return this;
+  }
+
+  setText(text) {
+    this._entity.label.text = text;
+
+    return this;
+  }
+
+  setFont(font) {
+    this._entity.label.font = font;
+    return this;
+  }
+
+  setColor(color) {
+    this._entity.label.fillColor = color;
+    return this;
+  }
+
+  setOutlineColor(color) {
+    this._entity.label.outlineColor = color;
+    return this;
+  }
+
+  setOutlineWidth(width) {
+    this._entity.label.outlineWidth = width;
+    return this;
+  }
+
+  setVisible(visible) {
+    this._entity.show = visible;
+    return this;
+  }
+
+  setPixelOffset(offset) {
+    this._entity.label.pixelOffset = offset;
+    return this;
+  }
+
+  setScale(scale) {
+    this._entity.label.scale = scale;
+    return this;
+  }
+
+  setAlignType(alignType) {
+    const horizontalOrigins = [Cesium.HorizontalOrigin.CENTER, Cesium.HorizontalOrigin.LEFT, Cesium.HorizontalOrigin.RIGHT];
+    const verticalOrigins = [Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.CENTER, Cesium.VerticalOrigin.TOP, Cesium.VerticalOrigin.BOTTOM];
+    this._entity.label.horizontalOrigin = horizontalOrigins[alignType] || Cesium.HorizontalOrigin.CENTER;
+    this._entity.label.verticalOrigin = verticalOrigins[alignType] || Cesium.VerticalOrigin.CENTER;
+    return this;
+  }
+
+  setName(name) {
+    this._entity.id = name;
+    return this;
+  }
+
+  remove() {
+    this._graphicModule.removeGraphic(this._entity.id);
+    return this;
+  }
+}
+
+/**
+ * 图元模块（对应平台 IGraphicModule）
+ * 职责：点/线/面/模型的参数化创建、编辑、销毁
+ */
+export class GraphicModule {
+  constructor(viewer) {
+    this.viewer = viewer;
+    this.config = Config.getInstance().getConfig();
+    this.graphicMap = new Map(); // 图元缓存（ID -> 实体实例）
+    this.wrapperMap = new Map(); // 包装器缓存（ID -> Wrapper 实例）
+  }
+
+  /**
+   * 创建点图元
+   * @param {string} graphicId 图元唯一ID
+   * @returns {PointWrapper} 点图元包装器
+   */
+  createPoint(graphicId) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const defaultStyle = this.config.graphic?.point || { pixelSize: 8, color: Cesium.Color.RED };
+
+    const entityOptions = {
+      id: graphicId,
+      position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+      point: {
+        ...defaultStyle,
+        outlineColor: Cesium.Color.WHITE,
+        outlineWidth: 1
+      }
+    };
+
+    const entity = this.viewer.entities.add(entityOptions);
+    this.graphicMap.set(graphicId, entity);
+
+    const wrapper = new PointWrapper(this, entity);
+    this.wrapperMap.set(graphicId, wrapper);
+    console.log(`点图元 ${graphicId} 创建成功`);
+
+    return wrapper;
+  }
+
+  /**
+   * 创建点图元（旧方法别名，建议迁移到 createPoint）
+   * @deprecated
+   */
+  CreatePoint(graphicId) {
+    return this.createPoint(graphicId);
+  }
+
+  /**
+   * 创建线图元
+   * @param {string} graphicId 图元唯一ID
+   * @returns {LineWrapper} 线图元包装器
+   */
+  createLine(graphicId) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const defaultStyle = this.config.graphic?.line || { width: 2, material: Cesium.Color.BLUE };
+
+    const entityOptions = {
+      id: graphicId,
+      polyline: {
+        positions: Cesium.Cartesian3.fromDegreesArrayHeights([]),
+        clampToGround: true,
+        ...defaultStyle
+      }
+    };
+
+    const entity = this.viewer.entities.add(entityOptions);
+    this.graphicMap.set(graphicId, entity);
+
+    const wrapper = new LineWrapper(this, entity);
+    this.wrapperMap.set(graphicId, wrapper);
+    console.log(`线图元 ${graphicId} 创建成功`);
+
+    return wrapper;
+  }
+
+  /**
+   * 创建线图元（旧方法别名，建议迁移到 createLine）
+   * @deprecated
+   */
+  CreateLine(graphicId) {
+    return this.createLine(graphicId);
+  }
+
+  /**
+   * 创建面图元
+   * @param {string} graphicId 图元唯一ID
+   * @returns {PolygonWrapper} 面图元包装器
+   */
+  createPolygon(graphicId) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const defaultStyle = this.config.graphic?.polygon || { color: Cesium.Color.GREEN.withAlpha(0.5) };
+
+    const entityOptions = {
+      id: graphicId,
+      polygon: {
+        hierarchy: new Cesium.PolygonHierarchy([]),
+        clampToGround: true,
+        outlineColor: Cesium.Color.WHITE,
+        outlineWidth: 1,
+        ...defaultStyle
+      }
+    };
+
+    const entity = this.viewer.entities.add(entityOptions);
+    this.graphicMap.set(graphicId, entity);
+
+    const wrapper = new PolygonWrapper(this, entity);
+    this.wrapperMap.set(graphicId, wrapper);
+    console.log(`面图元 ${graphicId} 创建成功`);
+
+    return wrapper;
+  }
+
+  /**
+   * 创建面图元（旧方法别名，建议迁移到 createPolygon）
+   * @deprecated
+   */
+  CreatePolygon(graphicId) {
+    return this.createPolygon(graphicId);
+  }
+
+  /**
+   * 创建模型图元
+   * @param {string} graphicId 图元唯一ID
+   * @returns {ModelWrapper} 模型图元包装器
+   */
+  createModel(graphicId) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const entityOptions = {
+      id: graphicId,
+      position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+      model: {
+        uri: "",
+        scale: 1.0,
+        minimumPixelSize: 128
+      }
+    };
+
+    const entity = this.viewer.entities.add(entityOptions);
+    this.graphicMap.set(graphicId, entity);
+
+    const wrapper = new ModelWrapper(this, entity);
+    this.wrapperMap.set(graphicId, wrapper);
+    console.log(`模型图元 ${graphicId} 创建成功`);
+
+    return wrapper;
+  }
+
+  /**
+   * 创建模型图元（旧方法别名，建议迁移到 createModel）
+   * @deprecated
+   */
+  CreateModel(graphicId) {
+    return this.createModel(graphicId);
+  }
+
+  /**
+   * 创建文本图元
+   * @param {string} graphicId 图元唯一ID
+   * @returns {TextWrapper} 文本图元包装器
+   */
+  createText(graphicId) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const entityOptions = {
+      id: graphicId,
+      position: Cesium.Cartesian3.fromDegrees(0, 0, 0),
+      label: {
+        text: "",
+        font: "16px Microsoft YaHei",
+        fillColor: Cesium.Color.WHITE,
+        outlineColor: Cesium.Color.BLACK,
+        outlineWidth: 2,
+        style: Cesium.LabelStyle.FILL_AND_OUTLINE,
+        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+        horizontalOrigin: Cesium.HorizontalOrigin.CENTER
+      }
+    };
+
+    const entity = this.viewer.entities.add(entityOptions);
+    this.graphicMap.set(graphicId, entity);
+
+    const wrapper = new TextWrapper(this, entity);
+    this.wrapperMap.set(graphicId, wrapper);
+    console.log(`文本图元 ${graphicId} 创建成功`);
+
+    return wrapper;
+  }
+
+  /**
+   * 创建文本图元（旧方法别名，建议迁移到 createText）
+   * @deprecated
+   */
+  CreateText(graphicId) {
+    return this.createText(graphicId);
+  }
+
+  /**
+   * 创建参数化标绘图元
+   * @param {string} graphicId 图元唯一ID
+   * @param {string} plotType PlotGraphicType
+   * @param {Array} controlPoints 控制点 [lon, lat, height][]
+   * @returns {PolygonWrapper|LineWrapper} 图元包装器
+   */
+  createPlotGraphic(graphicId, plotType, controlPoints = []) {
+    if (this.wrapperMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 已存在`);
+      return this.wrapperMap.get(graphicId);
+    }
+
+    const isLine = isLinePlotType(plotType);
+    const wrapper = isLine
+      ? this.createLine(graphicId)
+      : this.createPolygon(graphicId);
+
+    if (controlPoints.length > 0) {
+      const options = this._getPlotOptions(plotType);
+      wrapper.setPlotType(plotType, controlPoints, options);
+    } else {
+      wrapper._entity._isPlotGraphic = true;
+      wrapper._entity._plotType = plotType;
+      wrapper._entity._controlPoints = [];
+    }
+
+    console.log(`标绘图元 ${graphicId}（${plotType}）创建成功`);
+    return wrapper;
+  }
+
+  /**
+   * 创建直箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点
+   * @returns {PolygonWrapper}
+   */
+  createFineArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.FINE_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建突击方向箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点
+   * @returns {PolygonWrapper}
+   */
+  createAssaultDirection(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.ASSAULT_DIRECTION, controlPoints);
+  }
+
+  /**
+   * 创建细直箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点
+   * @returns {LineWrapper}
+   */
+  createStraightArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.STRAIGHT_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建三角形
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点
+   * @returns {PolygonWrapper}
+   */
+  createTriangle(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.TRIANGLE, controlPoints);
+  }
+
+  /**
+   * 创建扇形
+   * @param {string} graphicId 图元ID
+   * @param {Array} center 圆心 [lon, lat, height]
+   * @param {number} radius 半径（米）
+   * @param {number} startAngle 起始角度（度，0=正东，逆时针增大）
+   * @param {number} endAngle 结束角度（度）
+   * @returns {PolygonWrapper}
+   */
+  createSector(graphicId, center, radius, startAngle, endAngle) {
+    // 转换为三点控制点，与内部编辑逻辑保持一致
+    const startAngleRad = (startAngle || 0) * Math.PI / 180;
+    const endAngleRad = (endAngle === undefined ? 90 : endAngle) * Math.PI / 180;
+    const pnt2 = PlotGeometryUtil._getPointAtBearingAndDistance(center, radius, startAngleRad);
+    const pnt3 = PlotGeometryUtil._getPointAtBearingAndDistance(center, radius, endAngleRad);
+    const controlPoints = [center, pnt2, pnt3];
+
+    return this.createPlotGraphic(graphicId, PlotGraphicType.SECTOR, controlPoints);
+  }
+
+  /**
+   * 创建椭圆
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，3 点 [center, majorEnd, minorEnd]
+   * @returns {PolygonWrapper}
+   */
+  createEllipse(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.ELLIPSE, controlPoints);
+  }
+
+  /**
+   * 创建攻击箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥3 点
+   * @returns {PolygonWrapper}
+   */
+  createAttackArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.ATTACK_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建燕尾攻击箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥3 点
+   * @returns {PolygonWrapper}
+   */
+  createSwallowtailAttackArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.SWALLOWTAIL_ATTACK_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建集结箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥2 点
+   * @returns {PolygonWrapper}
+   */
+  createSquadCombat(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.SQUAD_COMBAT, controlPoints);
+  }
+
+  /**
+   * 创建燕尾集结箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥2 点
+   * @returns {PolygonWrapper}
+   */
+  createSwallowtailSquadCombat(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.SWALLOWTAIL_SQUAD_COMBAT, controlPoints);
+  }
+
+  /**
+   * 创建双箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，3~5 点
+   * @returns {PolygonWrapper}
+   */
+  createDoubleArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.DOUBLE_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建曲线箭头
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥2 点
+   * @returns {LineWrapper}
+   */
+  createCurvedArrow(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.CURVED_ARROW, controlPoints);
+  }
+
+  /**
+   * 创建曲线
+   * @param {string} graphicId 图元ID
+   * @param {Array} controlPoints 控制点，≥2 点
+   * @returns {LineWrapper}
+   */
+  createCurve(graphicId, controlPoints = []) {
+    return this.createPlotGraphic(graphicId, PlotGraphicType.CURVE, controlPoints);
+  }
+
+  /**
+   * 获取标绘类型默认参数
+   * 当前返回空对象，算法参数使用 PlotGeometryUtil 内部默认值
+   * 后续可扩展为从 Config 读取各标绘类型的算法参数
+   * @private
+   */
+  _getPlotOptions(plotType) {
+    const plotConfig = this.config.graphic?.plot;
+    if (!plotConfig) return {};
+    // 当前仅支持按线/面读取通用样式，算法参数暂不提供配置
+    return {};
+  }
+
+  /**
+   * 删除图元
+   * @param {string} graphicId 图元ID
+   * @returns {boolean} 是否删除成功
+   */
+  removeGraphic(graphicId) {
+    if (!this.graphicMap.has(graphicId)) {
+      console.warn(`图元 ${graphicId} 不存在`);
+      return false;
+    }
+
+    const entity = this.graphicMap.get(graphicId);
+    this.viewer.entities.remove(entity);
+    this.graphicMap.delete(graphicId);
+    this.wrapperMap.delete(graphicId);
+    return true;
+  }
+
+  /**
+   * 获取图元
+   * @param {string} graphicId 图元ID
+   * @returns {Cesium.Entity|undefined} 图元实体
+   */
+  getGraphic(graphicId) {
+    return this.graphicMap.get(graphicId);
+  }
+}