@vesium/plot 1.0.1-beta.48 → 1.0.1-beta.49

package/dist/index.d.ts

@@ -2,12 +2,10 @@ import { Cartesian3 } from 'cesium';
 import { ComputedRef } from 'vue';
 import { CSSProperties } from 'vue';
 import { Entity } from 'cesium';
-import { EntityCollection } from 'cesium';
 import { Event as Event_2 } from 'cesium';
 import { JulianDate } from 'cesium';
 import { MaybeRef } from 'vue';
 import { Nullable } from 'vesium';
-import { PrimitiveCollection } from 'cesium';
 import { Property } from 'cesium';
 import { ScreenSpaceEventHandler } from 'cesium';
 import { ShallowRef } from 'vue';
@@ -127,21 +125,23 @@ export declare enum PlotAction {
     ACTIVE = 2
 }
 
-export declare type PlotCollectionChanged = (scope: PlotFeatureCollection, added: PlotFeature[], removed: PlotFeature[]) => void;
-
-export declare interface PlotCollectionConstructorOptions {
-    id?: string;
-}
-
 export declare type PlotDefinitionChangedCallback = (scope: PlotFeature, key: keyof PlotFeature, newValue: PlotFeature[typeof key], oldValue: PlotFeature[typeof key]) => void;
 
+/**
+ * 标绘实例
+ */
 export declare class PlotFeature {
     constructor(options: PlotFeatureConstructorOptions);
     get id(): string;
     get scheme(): PlotScheme;
     get definitionChanged(): Event_2<PlotDefinitionChangedCallback>;
     get defining(): boolean;
-    private _disabled;
+    /**
+     * 获取禁用状态
+     *
+     * 当为 `true` 时，标绘实例将停止响应交互和更新；
+     * 为 `false` 时恢复正常功能。
+     */
     get disabled(): boolean;
     set disabled(value: string);
     get sampled(): SampledPlotProperty;
@@ -152,32 +152,52 @@ export declare class PlotFeature {
     get skeletons(): PlotSkeletonEntity[];
 }
 
-export declare class PlotFeatureCollection {
-    constructor(options?: PlotCollectionConstructorOptions);
-    get id(): string;
-    get collectionChanged(): Event_2<PlotCollectionChanged>;
-    get values(): PlotFeature[];
-    add(value: PlotFeature): boolean;
-    remove(value: PlotFeature): boolean;
-    get entities(): EntityCollection;
-    get primitives(): PrimitiveCollection;
-    get groundPrimitives(): PrimitiveCollection;
-    get skeletons(): EntityCollection;
-    isDestroyed(): boolean;
-    destroy(): void;
-}
-
+/**
+ * 标绘实例构造参数
+ */
 export declare interface PlotFeatureConstructorOptions {
+    /**
+     * 唯一标识符
+     *
+     * 未指定时将自动生成GUID
+     */
     id?: string;
+    /**
+     * 标绘方案配置
+     *
+     * 支持直接传入字符串方案名称、方案实例或构造参数
+     */
     scheme: string | PlotScheme | PlotSchemeConstructorOptions;
+    /**
+     * 采样属性配置
+     *
+     * 控制标绘对象的动态属性采样行为
+     */
     sampled?: SampledPlotProperty | SampledPlotPropertyConstructorOptions;
+    /**
+     * 禁用状态标志
+     *
+     * @default false
+     */
     disabled?: boolean;
 }
 
 export declare interface PlotRenderOptions<D = any> {
+    /**
+     * 当前标绘点位数据
+     */
     packable: SampledPlotPackable<D>;
+    /**
+     * 当前是否处于定义态
+     */
     defining: boolean;
+    /**
+     * 当前鼠标位置，若当前标绘不处于定义态时，`mouse`为`undefined`
+     */
     mouse?: Cartesian3;
+    /**
+     * 上一次的渲染结果
+     */
     previous: PlotRenderResult;
 }
 
@@ -189,45 +209,106 @@ export declare interface PlotRenderResult {
 
 export declare class PlotScheme {
     constructor(options: PlotSchemeConstructorOptions);
+    /**
+     * 标绘类型。应当是全局唯一的字符串，会作为键名缓存
+     */
     type: string;
     /**
-     * 是否立即执行完成标绘操作
-     *
-     * 每次控制点发生变变化时，执行该回调函数，如果返回`true`则标绘完成
+     * 判断是否立即完成标绘.
+     * 每次控制点发生变变化时，执行该回调函数，返回`true`则完成标绘
      */
     complete?: (packable: SampledPlotPackable) => boolean;
     /**
-     * 双击时，是否执行完成标绘操作
+     * 判断是否允许手动完成标绘。
+     * 每次控制点发生变变化时，执行该回调函数，返回`true`则后续左键双击即完成标绘
      */
-    forceComplete?: (packable: SampledPlotPackable) => boolean;
+    allowManualComplete?: (packable: SampledPlotPackable) => boolean;
     /**
+     * 处于定义态时鼠标的样式
      * @default 'crosshair'
      */
     definingCursor?: Nullable<CSSProperties['cursor']> | ((packable: SampledPlotPackable) => Nullable<CSSProperties['cursor']>);
+    /**
+     * 当前标绘的框架点数据
+     */
     skeletons: PlotSkeleton[];
+    /**
+     * 初始化时创建`Entity`的函数，创建后的`Entity`会作为配置项传入`render`中
+     */
     initEntites?: () => (Entity[] | undefined);
+    /**
+     * 初始化时创建`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+     */
     initPrimitives?: () => (any[] | undefined);
+    /**
+     * 初始化时创建贴地`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+     */
     initGroundPrimitives?: () => (any[] | undefined);
+    /**
+     * 当标绘数据变化时，会触发`render`回调，返回的数据会被添加到cesium中
+     */
     render?: (options: PlotRenderOptions) => PlotRenderResult | Promise<PlotRenderResult>;
     private static _record;
+    /**
+     * 标绘方案缓存。
+     * 每次标绘时都会将`PlotScheme.type`作为键名缓存，
+     * 后续可用过`PlotScheme.getCache(type)`获取完整的`PlotScheme`配置。
+     */
     static getCacheTypes(): string[];
+    /**
+     * 通过`PlotScheme.type`获取缓存中的`PlotScheme`配置。
+     */
     static getCache(type: string): PlotScheme | undefined;
+    /**
+     * 缓存标绘方案。
+     */
     static setCache(scheme: PlotScheme): void;
+    /**
+     * 解析传入的maybeScheme，maybeScheme可能是一个完整的PlotScheme，也可能是缓存中的`PlotScheme.type`，并返回 PlotScheme 实例。
+     * 若传入的是`PlotScheme.type`字符串，并且缓存中不存在该标绘方案，则抛出错误。
+     */
     static resolve(maybeScheme: string | PlotScheme | PlotSchemeConstructorOptions): PlotScheme;
 }
 
 export declare interface PlotSchemeConstructorOptions {
+    /**
+     * 标绘类型。应当是全局唯一的字符串，会作为键名缓存
+     */
     type: string;
+    /**
+     * 判断是否立即完成标绘.
+     * 每次控制点发生变变化时，执行该回调函数，返回`true`则完成标绘
+     */
     complete?: (packable: SampledPlotPackable) => boolean;
-    forceComplete?: (packable: SampledPlotPackable) => boolean;
     /**
+     * 判断是否允许手动完成标绘。
+     * 每次控制点发生变变化时，执行该回调函数，返回`true`则后续左键双击即完成标绘
+     */
+    allowManualComplete?: (packable: SampledPlotPackable) => boolean;
+    /**
+     * 处于定义态时鼠标的样式
      * @default 'crosshair'
      */
     definingCursor?: Nullable<CSSProperties['cursor']> | ((packable: SampledPlotPackable) => Nullable<CSSProperties['cursor']>);
+    /**
+     * 当前标绘的框架点数据
+     */
     skeletons?: (() => PlotSkeleton)[];
+    /**
+     * 初始化时创建`Entity`的函数，创建后的`Entity`会作为配置项传入`render`中
+     */
     initEntites?: () => (Entity[] | undefined);
+    /**
+     * 初始化时创建贴地`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+     */
     initPrimitives?: () => (any[] | undefined);
+    /**
+     * 初始化时创建贴地`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+     */
     initGroundPrimitives?: () => (any[] | undefined);
+    /**
+     * 当标绘数据变化时，会触发`render`回调，返回的数据会被添加到cesium中
+     */
     render?: (options: PlotRenderOptions) => PlotRenderResult | Promise<PlotRenderResult>;
 }
 
@@ -287,13 +368,24 @@ export declare type SampledPlotInterpolationAlgorithm<D = any> = (time: JulianDa
  * 标绘采集到的数据
  */
 export declare interface SampledPlotPackable<D = any> {
+    /**
+     * 当前标绘所属于的时间节点
+     */
     time?: JulianDate;
+    /**
+     * 采样点位数据
+     */
     positions?: Cartesian3[];
+    /**
+     * 附带的额外自定义数据
+     */
     derivative?: D;
 }
 
 /**
- * 标绘属性数据
+ * 标绘采样点数据。
+ * 标绘采样点数据是一个时间序列数据，包含时间、位置和附带的额外数据。
+ * 具体用法可参考 [Cesium.SampledProperty](https://cesium.com/learn/cesiumjs/ref-doc/SampledProperty.html)
  */
 export declare class SampledPlotProperty<D = any> {
     constructor(options?: SampledPlotPropertyConstructorOptions<D>);
@@ -318,8 +410,7 @@ export declare class SampledPlotProperty<D = any> {
      */
     getValue(time?: JulianDate, result?: SampledPlotPackable): SampledPlotPackable<D>;
     /**
-     * 设置样本数据
-     *
+     * 设置样本数据，如果传入的数据不含时间，则会存入时间最早的集合中
      * @param value 样本数据对象，包含时间、位置和导数信息
      */
     setSample(value: SampledPlotPackable<D>): void;
@@ -342,6 +433,9 @@ export declare class SampledPlotProperty<D = any> {
      * @param interval 要移除样本的时间间隔
      */
     removeSamples(interval: TimeInterval): void;
+    /**
+     * 判断两个property是否相等
+     */
     equals(other?: Property): boolean;
 }
 

package/dist/index.iife.js

@@ -5,30 +5,49 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 
   const _PlotScheme = class _PlotScheme {
     constructor(options) {
+      /**
+       * 标绘类型。应当是全局唯一的字符串，会作为键名缓存
+       */
       __publicField(this, "type");
       /**
-       * 是否立即执行完成标绘操作
-       *
-       * 每次控制点发生变变化时，执行该回调函数，如果返回`true`则标绘完成
+       * 判断是否立即完成标绘.
+       * 每次控制点发生变变化时，执行该回调函数，返回`true`则完成标绘
        */
       __publicField(this, "complete");
       /**
-       * 双击时，是否执行完成标绘操作
+       * 判断是否允许手动完成标绘。
+       * 每次控制点发生变变化时，执行该回调函数，返回`true`则后续左键双击即完成标绘
        */
-      __publicField(this, "forceComplete");
+      __publicField(this, "allowManualComplete");
       /**
+       * 处于定义态时鼠标的样式
        * @default 'crosshair'
        */
       __publicField(this, "definingCursor");
+      /**
+       * 当前标绘的框架点数据
+       */
       __publicField(this, "skeletons");
+      /**
+       * 初始化时创建`Entity`的函数，创建后的`Entity`会作为配置项传入`render`中
+       */
       __publicField(this, "initEntites");
+      /**
+       * 初始化时创建`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+       */
       __publicField(this, "initPrimitives");
+      /**
+       * 初始化时创建贴地`Primitive`的函数，创建后的`Primitive`会作为配置项传入`render`中
+       */
       __publicField(this, "initGroundPrimitives");
+      /**
+       * 当标绘数据变化时，会触发`render`回调，返回的数据会被添加到cesium中
+       */
       __publicField(this, "render");
       var _a;
       this.type = options.type;
       this.complete = options.complete;
-      this.forceComplete = options.forceComplete;
+      this.allowManualComplete = options.allowManualComplete;
       this.definingCursor = options.definingCursor ?? "crosshair";
       this.skeletons = ((_a = options.skeletons) == null ? void 0 : _a.map((item) => item())) ?? [];
       this.initEntites = options.initEntites;
@@ -36,16 +55,31 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.initGroundPrimitives = options.initGroundPrimitives;
       this.render = options.render;
     }
+    /**
+     * 标绘方案缓存。
+     * 每次标绘时都会将`PlotScheme.type`作为键名缓存，
+     * 后续可用过`PlotScheme.getCache(type)`获取完整的`PlotScheme`配置。
+     */
     static getCacheTypes() {
       return [...this._record.keys()];
     }
+    /**
+     * 通过`PlotScheme.type`获取缓存中的`PlotScheme`配置。
+     */
     static getCache(type) {
       return _PlotScheme._record.get(type);
     }
+    /**
+     * 缓存标绘方案。
+     */
     static setCache(scheme) {
       vesium.assertError(!scheme.type, "`scheme.type` is required");
       _PlotScheme._record.set(scheme.type, scheme);
     }
+    /**
+     * 解析传入的maybeScheme，maybeScheme可能是一个完整的PlotScheme，也可能是缓存中的`PlotScheme.type`，并返回 PlotScheme 实例。
+     * 若传入的是`PlotScheme.type`字符串，并且缓存中不存在该标绘方案，则抛出错误。
+     */
     static resolve(maybeScheme) {
       if (typeof maybeScheme === "string") {
         const _scheme = _PlotScheme.getCache(maybeScheme);
@@ -225,8 +259,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       return result;
     }
     /**
-     * 设置样本数据
-     *
+     * 设置样本数据，如果传入的数据不含时间，则会存入时间最早的集合中
      * @param value 样本数据对象，包含时间、位置和导数信息
      */
     setSample(value) {
@@ -292,6 +325,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         cesium.TimeInterval.contains(interval2, time) && this.removeSample(time);
       }
     }
+    /**
+     * 判断两个property是否相等
+     */
     equals(other) {
       return other === this;
     }
@@ -316,6 +352,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
        * @internal
        */
       __publicField(this, "_defining");
+      /**
+       * @internal
+       */
       __publicField(this, "_disabled");
       /**
        * @internal
@@ -372,6 +411,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         plot._defining = value;
       }
     }
+    /**
+     * 获取禁用状态
+     *
+     * 当为 `true` 时，标绘实例将停止响应交互和更新；
+     * 为 `false` 时恢复正常功能。
+     */
     get disabled() {
       return this._disabled;
     }
@@ -419,64 +464,6 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this._skeletons = value;
     }
   }
-  class PlotFeatureCollection {
-    constructor(options = {}) {
-      /**
-       * @internal
-       */
-      __publicField(this, "_id");
-      /**
-       * @internal
-       */
-      __publicField(this, "_isDestroyed");
-      const { id } = options;
-      this._id = id || cesium.createGuid();
-      this._isDestroyed = false;
-    }
-    get id() {
-      return this._id;
-    }
-    get collectionChanged() {
-      return this._collectionChanged;
-    }
-    get values() {
-      return Array.from(this._values);
-    }
-    add(value) {
-      if (this._isDestroyed) {
-        throw new Error(`PlotFeatureCollection is isDestroyed`);
-      }
-      return this._values.has(value) ? false : !!this._values.add(value);
-    }
-    remove(value) {
-      return this._values.delete(value);
-    }
-    get entities() {
-      return this._dataSource.entities;
-    }
-    get primitives() {
-      return this._primitives;
-    }
-    get groundPrimitives() {
-      return this._groundPrimitives;
-    }
-    get skeletons() {
-      return this._skeletonDataSource.entities;
-    }
-    isDestroyed() {
-      return this._isDestroyed;
-    }
-    destroy() {
-      if (!this._isDestroyed) {
-        this._viewer.dataSources.remove(this._dataSource);
-        this._viewer.dataSources.remove(this._skeletonDataSource);
-        this._viewer.scene.primitives.remove(this._primitives);
-        this._viewer.scene.groundPrimitives.remove(this._groundPrimitives);
-        this._viewer.dataSources.remove(this._skeletonDataSource);
-        this._isDestroyed = true;
-      }
-    }
-  }
   var PlotAction = /* @__PURE__ */ ((PlotAction2) => {
     PlotAction2[PlotAction2["IDLE"] = 0] = "IDLE";
     PlotAction2[PlotAction2["HOVER"] = 1] = "HOVER";
@@ -623,7 +610,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         if (!position) {
           return;
         }
-        const completed = (_a = scheme.forceComplete) == null ? void 0 : _a.call(scheme, packable.value);
+        const completed = (_a = scheme.allowManualComplete) == null ? void 0 : _a.call(scheme, packable.value);
         completed && PlotFeature.setDefining(current.value, false);
       }
     );
@@ -900,7 +887,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       if (previous) {
         if (previous.defining) {
           const packable2 = previous.sampled.getValue(getCurrentTime());
-          const completed = (_b = (_a = previous.scheme).forceComplete) == null ? void 0 : _b.call(_a, packable2);
+          const completed = (_b = (_a = previous.scheme).allowManualComplete) == null ? void 0 : _b.call(_a, packable2);
           if (completed) {
             PlotFeature.setDefining(previous, false);
             operateResolve == null ? void 0 : operateResolve(previous);
@@ -1246,7 +1233,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   }
   const schemeMeasureArea = new PlotScheme({
     type: "measureArea",
-    forceComplete: (packable) => packable.positions.length >= 3,
+    allowManualComplete: (packable) => packable.positions.length >= 3,
     skeletons: [
       control,
       interval
@@ -1358,7 +1345,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   });
   const schemePolygon = new PlotScheme({
     type: "polygon",
-    forceComplete: (packable) => packable.positions.length >= 3,
+    allowManualComplete: (packable) => packable.positions.length >= 3,
     skeletons: [
       control,
       interval,
@@ -1408,7 +1395,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   const schemePolyline = new PlotScheme(
     {
       type: "polyline",
-      forceComplete: (packable) => packable.positions.length >= 2,
+      allowManualComplete: (packable) => packable.positions.length >= 2,
       skeletons: [
         control,
         intervalNonclosed,
@@ -1468,7 +1455,6 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   });
   exports.PlotAction = PlotAction;
   exports.PlotFeature = PlotFeature;
-  exports.PlotFeatureCollection = PlotFeatureCollection;
   exports.PlotScheme = PlotScheme;
   exports.PlotSkeletonEntity = PlotSkeletonEntity;
   exports.SampledPlotProperty = SampledPlotProperty;