@terra.gl/core 0.0.1-alpha.51 → 0.0.1-alpha.53

package/dist/index.d.ts

@@ -274,19 +274,10 @@ export declare type AttributesType = {
 
 export declare const author: any;
 
-/**
- * @category DrawTool
- */
 declare type BaseDrawToolOptions = MapToolOptions & {
-    /**
-     * Mode name, e.g. 'line' / 'polygon' / 'point'
-     * 模式名称，例如 'line' / 'polygon' / 'point'
-     */
+    /** 模式名称，例如 'line' / 'polygon' / 'point' */
     mode: string;
-    /**
-     * Whether to automatically disable tool after one drawing finishes
-     * 是否在一次绘制结束后自动禁用工具
-     */
+    /** 是否在一次绘制结束后自动禁用工具 */
     once?: boolean;
 };
 
@@ -1160,15 +1151,12 @@ declare interface DomEventMap extends BaseEventMap<Map_2> {
 }
 
 /**
- * Single draw mode definition:
  * 单个绘制模式定义：
- *
- * @property actions - Involved event sequence (currently mainly click / mousemove / dblclick) 参与的事件序列（目前主要是 click / mousemove / dblclick）
- * @property create - Create geometry object on first click 第一次点击时创建几何对象
- * @property update - Update geometry on every new vertex or move 每次新增顶点或移动时更新几何
- * @property generate - Generate final result on finish (can be Feature or original geometry) 结束时生成最终结果（可以是 Feature，也可以是原几何）
- * @property clickLimit - Minimum click count (can finish when reached, usually with dblclick) 最少点击次数（达到就可以结束，通常配合 dblclick）
- * @category DrawTool
+ * - actions: 参与的事件序列（目前主要是 click / mousemove / dblclick）
+ * - create: 第一次点击时创建几何对象
+ * - update: 每次新增顶点或移动时更新几何
+ * - generate: 结束时生成最终结果（可以是 Feature，也可以是原几何）
+ * - clickLimit: 最少点击次数（达到就可以结束，通常配合 dblclick）
  */
 declare type DrawModeDefinition = {
     actions: Array<"click" | "mousemove" | "dblclick">;
@@ -1179,86 +1167,51 @@ declare type DrawModeDefinition = {
 };
 
 /**
- * DrawTool: Universal Drawing Tool
  * DrawTool：通用绘图工具
  *
- * @description
- * Responsible for:
- * - Handling Map DOM events (click/mousemove/dblclick)
- * - Maintaining vertex sequence _clickCoords
- * - Calling mode definitions create/update/generate
- * - Triggering events: drawstart / drawvertex / drawend / drawing, etc.
- *
  * 负责：
  * - 处理 Map 的 DOM 事件（click/mousemove/dblclick）
  * - 维护顶点序列 _clickCoords
  * - 调用模式定义的 create/update/generate
- * - 向外触发：drawstart / drawend / drawing 等事件
- * @category DrawTool
+ * - 向外触发：drawstart / drawvertex / drawend / drawing 等事件
  */
 export declare class DrawTool extends MapTool {
-    /**
-     * Configuration options
-     * 配置
-     */
+    /** 配置 */
     options: DrawToolOptions;
-    /**
-     * Current mode definition
-     * 当前模式定义
-     */
+    /** 当前模式定义 */
     private _modeDef?;
-    /**
-     * Current drawing vertex sequence
-     * 当前绘制中的顶点序列
-     */
+    /** 当前绘制中的顶点序列 */
     private _clickCoords;
-    /**
-     * Whether drawing is in progress
-     * 是否正在绘制中
-     */
+    /** 是否正在绘制中 */
     private _isDrawing;
-    /**
-     * Current drawing geometry object (returned by mode.create/create)
-     * 当前绘制中的几何对象（由 mode.create/create 返回）
-     */
+    /** 当前绘制中的几何对象（由 mode.create/create 返回） */
     private _geometry;
-    /**
-     * Internal unified draft layer
-     * 内部统一草图图层
-     */
+    /** 内部统一草图图层 */
     private _draftLayer?;
     /**
-     * Register a drawing mode
      * 注册一个绘制模式
      */
     static registerMode(name: string, def: DrawModeDefinition): void;
     /**
-     * Get registered mode definition
      * 获取已注册的模式
      */
     static getModeDefinition(name: string): DrawModeDefinition | undefined;
     constructor(options: DrawToolOptions);
     /**
-     * Get current mode name (unified to lowercase)
      * 获取当前模式名称（统一转为小写）
      */
     getMode(): string;
     /**
-     * Set drawing mode: will clear current drawing state
      * 设置绘制模式：会清空当前绘制状态
      */
     setMode(mode: string): this;
     /**
-     * Set drawing style (only affects subsequent new drawings)
      * 设置绘制样式（仅影响后续新开始的绘制）
-     *
-     * @param style - Style options 样式选项
-     * @param style.geometryStyle - Main geometry style (point/line/polygon) 主几何样式（点/线/面）
-     * @param style.vertexStyle - Vertex style, pass null to disable anchor display 顶点样式，传 null 可关闭锚点显示
+     * - geometryStyle：主几何样式（点/线/面）
+     * - vertexStyle：顶点样式，传 null 可关闭锚点显示
      */
     setStyle(style: DrawToolStyleOptions): this;
     /**
-     * Subclass implementation: Return event mapping to bind to Map
      * 子类实现：返回需要绑定到 Map 的事件映射
      */
     protected getEvents(): {
@@ -1267,67 +1220,44 @@ export declare class DrawTool extends MapTool {
         dblclick: (evt: DomEventMap) => void;
     };
     /**
-     * Sync mode definition when enabled
      * 启用时同步一下模式定义
      */
     protected onEnable(): void;
     /**
-     * Finish current drawing and clean up draft layer when disabled
      * 禁用时结束当前绘制，并清理草图图层
      */
     protected onDisable(): void;
     /**
-     * Ensure current mode has corresponding definition
      * 确保当前 mode 有对应的定义
      */
     private _ensureMode;
     /**
-     * Handle click event:
      * 处理 click 事件：
-     *
-     * @description
-     * - First click: Start drawing, call mode.create, trigger drawstart
-     * - Subsequent click: Append vertex, call mode.update, trigger drawvertex
-     * - If clickLimit reached: Finish drawing
-     *
      * - 第一次 click：开始绘制，调用 mode.create，触发 drawstart
      * - 后续 click：追加顶点，调用 mode.update，触发 drawvertex
      * - 若达到 clickLimit，则结束绘制
      */
     private _handleClick;
     /**
-     * Handle mousemove event:
      * 处理 mousemove 事件：
-     *
-     * @description
-     * - Only update geometry when drawing
-     * - Do not modify _clickCoords, use temporary coords for update
-     *
      * - 仅在绘制中才更新几何
      * - 不修改 _clickCoords，只用临时 coords 传给 update
      */
     private _handleMouseMove;
     /**
-     * Handle dblclick:
      * 处理 dblclick：
-     *
-     * @description
-     * - If drawing, finish directly
      * - 如果正在绘制，则直接结束
      */
     private _handleDblClick;
     /**
-     * Normally finish a drawing: Call mode.generate and trigger drawend
      * 正常结束一次绘制：调用 mode.generate 并触发 drawend
      */
     private _finishDrawing;
     /**
-     * Silently finish (no drawend trigger), used for mode switching / tool disabling
      * 静默结束（不触发 drawend），用于切换模式 / 禁用工具
      */
     private _finishDrawingSilently;
     /**
-     * Internal: Get or create unified draft layer
      * 内部：获取或创建统一草图图层
      */
     _getOrCreateDraftLayer(): OverlayLayer<Feature>;
@@ -1340,23 +1270,13 @@ export declare class DrawTool extends MapTool {
 export declare type DrawToolOptions = BaseDrawToolOptions & DrawToolStyleOptions;
 
 /**
- * Style configuration type
  * 样式配置类型
- * @category DrawTool
  */
 export declare type DrawToolStyleOptions = {
-    /**
-     * Main geometry style (point / line / polygon)
-     * 主几何样式（点 / 线 / 面）
-     */
+    /** 主几何样式（点 / 线 / 面） */
     geometryStyle?: StyleInput;
     /**
-     * Vertex (anchor) style
      * 顶点（锚点）样式
-     *
-     * @description
-     * - Pass null to not draw anchors
-     * - Pass undefined to keep current setting
      * - 传 null 表示不绘制锚点
      * - 不传该字段则保持当前设置
      */
@@ -4268,100 +4188,78 @@ export declare type MapOptionsType = {
 };
 
 /**
- * Map Tool Base Class.
  * 地图工具基类
  *
- * - Manage tool lifecycle (addTo / enable / disable / remove)
- * - Integrate with Map event system (Unified internal event registration/unregistration)
- * - Ensure only one active tool exists on the same map
- *
  * - 管理工具的生命周期（addTo / enable / disable / remove）
  * - 与 Map 的事件系统对接（内部统一注册/注销事件）
  * - 保证同一张地图同时只存在一个激活工具
- * @category Map
  */
 export declare abstract class MapTool extends MapTool_base {
-    /**
-     * Bound map instance
-     * 绑定的地图实例
-     */
+    /** 绑定的地图实例 */
     protected _map?: Map_2;
-    /**
-     * Whether enabled
-     * 是否启用中
-     */
+    /** 是否启用中 */
     protected _enabled: boolean;
-    /**
-     * Cache event handlers bound to Map for removal on off
-     * 缓存绑定到 Map 上的事件处理函数，便于 off 时移除
-     */
+    /** 缓存绑定到 Map 上的事件处理函数，便于 off 时移除 */
     private _boundHandlers;
     /**
-     * @param options Tool options 工具配置
+     * @param options 工具配置
      */
     constructor(options?: MapToolOptions);
     /**
-     * Add tool to map and automatically enable.
-     * Ensures only one active MapTool on the same Map.
      * 将工具添加到地图上，并自动启用。
      * 同一张 Map 上会保证只有一个激活的 MapTool。
      */
     addTo(map: Map_2): this;
     /**
-     * Get currently bound map instance.
      * 获取当前绑定的地图实例
      */
     getMap(): Map_2 | undefined;
     /**
-     * Enable tool: Bind events + Call onEnable hook.
      * 启用工具：绑定事件 + 调用 onEnable 钩子
      */
     enable(): this;
     /**
-     * Disable tool: Unbind events + Call onDisable hook.
      * 禁用工具：解绑事件 + 调用 onDisable 钩子
      */
     disable(): this;
     /**
-     * Remove tool from map.
-     * 从地图移除工具。
+     * 工具是否处于启用状态
+     */
+    isEnabled(): boolean;
+    /**
+     * 从地图上移除工具
      */
     remove(): this;
     /**
-     * Abstract method: Subclasses can implement initialization logic.
-     * 抽象方法：子类可实现初始化逻辑。
+     * 子类实现：返回需要绑定到 Map 上的事件映射
+     *
+     * key: 事件名（如 'click', 'mousemove'）
+     * value: 事件处理函数（参数为 Map 的事件数据）
+     *
+     * 注意：
+     * - 不要求提前 bind(this)，MapTool 内部会统一绑定 this
+     */
+    protected abstract getEvents(): Record<string, (e: any) => void>;
+    /**
+     * 生命周期钩子：工具刚 addTo(map) 时调用
      */
     protected onAdd?(): void;
     /**
-     * Abstract method: Subclasses can implement enabling logic.
-     * 抽象方法：子类可实现启用逻辑。
+     * 生命周期钩子：工具 enable() 时调用
      */
     protected onEnable?(): void;
     /**
-     * Abstract method: Subclasses can implement disabling logic.
-     * 抽象方法：子类可实现禁用逻辑。
+     * 生命周期钩子：工具 disable() 时调用
      */
     protected onDisable?(): void;
     /**
-     * Abstract method: Subclasses can implement removal logic.
-     * 抽象方法：子类可实现移除逻辑。
-     */
-    protected onRemove?(): void;
-    /**
-     * Bind events.
-     * 绑定事件。
+     * 内部：绑定 Map 事件
      */
     private _bindEvents;
     /**
-     * Unbind events.
-     * 解绑事件。
+     * 内部：解绑 Map 事件
      */
     private _unbindEvents;
-    /**
-     * Helper method: Register map event listener (Automatically managed, auto-removed on disable).
-     * 辅助方法：注册地图事件监听（自动管理，disable 时自动移除）。
-     */
-    protected addMapEvent(type: string, fn: (e: any) => void, context?: any): void;
 }
 
 declare const MapTool_base: {
@@ -4393,9 +4291,7 @@ declare const MapTool_base: {
 } & typeof EmptyBase;
 
 /**
- * MapTool configuration (Reserved for future extension)
  * MapTool 配置项（预留，将来可以扩展）
- * @category Map
  */
 declare type MapToolOptions = ClassOptions_2 & {};