@terra.gl/core 0.0.1-alpha.11 → 0.0.1-alpha.12

package/dist/index.d.ts

@@ -748,7 +748,7 @@ export declare function concatenateTypedArrays<T extends TypedArray>(...typedArr
  * @param zoom - 缩放级别
  * @returns 包含 WGS84 坐标数组的 GeoJSON geometry 对象 { type: string, coordinates: any }
  */
-export declare function convertGeometryToWGS84(geometryData: any, tileX: number, tileY: number, zoom: number): GeoJSONGeometry;
+export declare function convertGeometryToWGS84(geometryData: any, tileX: number, tileY: number, zoom: number): GeoJSONGeometry_2;
 
 /**
  * 基础坐标类型
@@ -787,6 +787,136 @@ export declare interface CustomStyle extends BaseStyle {
     build: () => Object3D | Promise<Object3D>;
 }
 
+declare interface DomEventMap extends BaseEventMap<Map_2> {
+    /** 事件的地理坐标（可选） */
+    coordinate?: Coordinate;
+}
+
+/**
+ * 单个绘制模式定义：
+ * - actions: 参与的事件序列（目前主要是 click / mousemove / dblclick）
+ * - create: 第一次点击时创建几何对象
+ * - update: 每次新增顶点或移动时更新几何
+ * - generate: 结束时生成最终结果（可以是 Feature，也可以是原几何）
+ * - clickLimit: 最少点击次数（达到就可以结束，通常配合 dblclick）
+ */
+declare type DrawModeDefinition = {
+    actions: Array<"click" | "mousemove" | "dblclick">;
+    create: (start: Coordinate, evt: DomEventMap) => any;
+    update: (coords: Coordinate[], geometry: any, evt: DomEventMap) => void;
+    generate: (geometry: any, coords: Coordinate[]) => any;
+    clickLimit?: number;
+};
+
+/**
+ * DrawTool：通用绘图工具
+ *
+ * 负责：
+ * - 处理 Map 的 DOM 事件（click/mousemove/dblclick）
+ * - 维护顶点序列 _clickCoords
+ * - 调用模式定义的 create/update/generate
+ * - 向外触发：drawstart / drawvertex / drawend / drawing 等事件
+ */
+export declare class DrawTool extends MapTool {
+    /** 配置 */
+    options: DrawToolOptions;
+    /** 当前模式定义 */
+    private _modeDef?;
+    /** 当前绘制中的顶点序列 */
+    private _clickCoords;
+    /** 是否正在绘制中 */
+    private _isDrawing;
+    /** 当前绘制中的几何对象（由 mode.create/create 返回） */
+    private _geometry;
+    /** 内部统一草图图层 */
+    private _draftLayer?;
+    /**
+     * 注册一个绘制模式
+     */
+    static registerMode(name: string, def: DrawModeDefinition): void;
+    /**
+     * 获取已注册的模式
+     */
+    static getModeDefinition(name: string): DrawModeDefinition | undefined;
+    constructor(options: DrawToolOptions);
+    /**
+     * 获取当前模式名称（统一转为小写）
+     */
+    getMode(): string;
+    /**
+     * 设置绘制模式：会清空当前绘制状态
+     */
+    setMode(mode: string): this;
+    /**
+     * 子类实现：返回需要绑定到 Map 的事件映射
+     */
+    protected getEvents(): {
+        click: (evt: DomEventMap) => void;
+        mousemove: (evt: DomEventMap) => void;
+        dblclick: (evt: DomEventMap) => void;
+    };
+    /**
+     * 启用时同步一下模式定义
+     */
+    protected onEnable(): void;
+    /**
+     * 禁用时结束当前绘制，并清理草图图层
+     */
+    protected onDisable(): void;
+    /**
+     * 确保当前 mode 有对应的定义
+     */
+    private _ensureMode;
+    /**
+     * 处理 click 事件：
+     * - 第一次 click：开始绘制，调用 mode.create，触发 drawstart
+     * - 后续 click：追加顶点，调用 mode.update，触发 drawvertex
+     * - 若达到 clickLimit，则结束绘制
+     */
+    private _handleClick;
+    /**
+     * 处理 mousemove 事件：
+     * - 仅在绘制中才更新几何
+     * - 不修改 _clickCoords，只用临时 coords 传给 update
+     */
+    private _handleMouseMove;
+    /**
+     * 处理 dblclick：
+     * - 如果正在绘制，则直接结束
+     */
+    private _handleDblClick;
+    /**
+     * 正常结束一次绘制：调用 mode.generate 并触发 drawend
+     */
+    private _finishDrawing;
+    /**
+     * 静默结束（不触发 drawend），用于切换模式 / 禁用工具
+     */
+    private _finishDrawingSilently;
+    /**
+     * 内部：获取或创建统一草图图层
+     */
+    _getOrCreateDraftLayer(): OverlayLayer<Feature>;
+    /**
+     * 内部：销毁草图图层
+     */
+    private _destroyDraftLayer;
+}
+
+/**
+ * DrawTool 的配置项
+ */
+declare type DrawToolOptions = MapToolOptions & {
+    /** 模式名称，例如 'line' / 'polygon' / 'point' */
+    mode: string;
+    /** 是否在一次绘制结束后自动禁用工具 */
+    once?: boolean;
+    /** 主几何的样式（线 / 面） */
+    geometryStyle?: StyleInput;
+    /** 锚点样式 */
+    vertexStyle?: StyleInput | null;
+};
+
 /**
  * 边缘索引类型
  * @description 定义网格四边的顶点索引
@@ -802,6 +932,10 @@ export declare type EdgeIndices = {
     northIndices: Uint16Array | Uint32Array;
 };
 
+declare class EmptyBase {
+    constructor(..._args: any[]);
+}
+
 /**
  * 创建一个空基类（仅用于混入起点）
  */
@@ -922,7 +1056,7 @@ declare abstract class Feature extends Feature_base implements ICollidable {
     /** Three.js几何对象 */
     _threeGeometry: Object3D | Line2;
     /** GeoJSON几何数据 */
-    _geometry: GeoJSONGeometry_2;
+    _geometry: GeoJSONGeometry;
     /** 所属图层 */
     _layer?: Layer;
     /** 当前样式 */
@@ -1224,19 +1358,19 @@ declare type FeatureOptions = {
     rotateAngle?: number;
 };
 
+/**
+ * GeoJSON几何类型联合类型
+ */
+declare type GeoJSONGeometry = Point_2 | MultiPoint | LineString_2 | MultiLineString_2 | Polygon_2 | MultiPolygon;
+
 /**
  * GeoJSON Geometry 的返回类型 (用于 GeoJSON 兼容输出)
  */
-declare interface GeoJSONGeometry {
+declare interface GeoJSONGeometry_2 {
     type: string;
     coordinates: any;
 }
 
-/**
- * GeoJSON几何类型联合类型
- */
-declare type GeoJSONGeometry_2 = Point_2 | MultiPoint | LineString_2 | MultiLineString_2 | Polygon_2 | MultiPolygon;
-
 /**
  * GeoJSON 兼容的 WGS84 坐标数组 [Lng, Lat]
  */
@@ -2787,6 +2921,114 @@ export declare type MapOptionsType = {
     FeatureEvents?: boolean;
 };
 
+/**
+ * 地图工具基类
+ *
+ * - 管理工具的生命周期（addTo / enable / disable / remove）
+ * - 与 Map 的事件系统对接（内部统一注册/注销事件）
+ * - 保证同一张地图同时只存在一个激活工具
+ */
+export declare abstract class MapTool extends MapTool_base {
+    /** 绑定的地图实例 */
+    protected _map?: Map_2;
+    /** 是否启用中 */
+    protected _enabled: boolean;
+    /** 缓存绑定到 Map 上的事件处理函数，便于 off 时移除 */
+    private _boundHandlers;
+    /**
+     * @param options 工具配置
+     */
+    constructor(options?: MapToolOptions);
+    /**
+     * 将工具添加到地图上，并自动启用。
+     * 同一张 Map 上会保证只有一个激活的 MapTool。
+     */
+    addTo(map: Map_2): this;
+    /**
+     * 获取当前绑定的地图实例
+     */
+    getMap(): Map_2 | undefined;
+    /**
+     * 启用工具：绑定事件 + 调用 onEnable 钩子
+     */
+    enable(): this;
+    /**
+     * 禁用工具：解绑事件 + 调用 onDisable 钩子
+     */
+    disable(): this;
+    /**
+     * 工具是否处于启用状态
+     */
+    isEnabled(): boolean;
+    /**
+     * 从地图上移除工具
+     */
+    remove(): this;
+    /**
+     * 子类实现：返回需要绑定到 Map 上的事件映射
+     *
+     * key: 事件名（如 'click', 'mousemove'）
+     * value: 事件处理函数（参数为 Map 的事件数据）
+     *
+     * 注意：
+     * - 不要求提前 bind(this)，MapTool 内部会统一绑定 this
+     */
+    protected abstract getEvents(): Record<string, (e: any) => void>;
+    /**
+     * 生命周期钩子：工具刚 addTo(map) 时调用
+     */
+    protected onAdd?(): void;
+    /**
+     * 生命周期钩子：工具 enable() 时调用
+     */
+    protected onEnable?(): void;
+    /**
+     * 生命周期钩子：工具 disable() 时调用
+     */
+    protected onDisable?(): void;
+    /**
+     * 内部：绑定 Map 事件
+     */
+    private _bindEvents;
+    /**
+     * 内部：解绑 Map 事件
+     */
+    private _unbindEvents;
+}
+
+declare const MapTool_base: {
+    new (...args: any[]): {
+        eventClass: EventClass;
+        on: (type: string, listener: (data?: any) => void) => EventClass;
+        trigger: (type: string, data?: any) => EventClass;
+        off: (type: string, listener: (...args: any[]) => void) => EventClass;
+    };
+} & {
+    new (...args: any[]): {
+        [x: string]: any;
+        options: any;
+        _isUpdatingOptions?: boolean;
+        _initHooksCalled?: boolean;
+        _initHooks?: Function[];
+        proxyOptions(): /*elided*/ any;
+        callInitHooks(): /*elided*/ any;
+        setOptions(options: ClassOptions): /*elided*/ any;
+        config(conf?: string | ClassOptions, value?: any): ClassOptions | /*elided*/ any;
+        onConfig(_conf: ClassOptions): void;
+        _visitInitHooks(proto: {
+            _initHooks: any;
+        }): void;
+    };
+    mergeOptions(options: ClassOptions): /*elided*/ any & typeof EmptyBase;
+    addInitHook(fn: Function | string, ...args: any[]): /*elided*/ any & typeof EmptyBase;
+    include(...sources: any[]): /*elided*/ any & typeof EmptyBase;
+} & typeof EmptyBase;
+
+/**
+ * MapTool 配置项（预留，将来可以扩展）
+ */
+declare type MapToolOptions = ClassOptions & {};
+
 /**
  * Martini网格瓦片生成器
  * @description 基于RTIN（Right-Triangulated Irregular Networks）方法的高度图瓦片生成器