@ray-js/robot-map-sdk 0.0.4 → 0.0.5-beta.2

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import { Rectangle } from 'pixi.js';
 import { SPECIAL_ROOM_IDS } from '@ray-js/robot-protocol';
 import { SpecialRoomId } from '@ray-js/robot-protocol';
 import { Sprite } from 'pixi.js';
+import { StructuredMapDataSource } from '@ray-js/robot-protocol';
 import { TextStyleFontWeight } from 'pixi.js';
 import { Texture } from 'pixi.js';
 
@@ -310,6 +311,11 @@ export declare type AppConfig = {
         opacity: number
         /** 缩放系数 */
         scale: number
+        // 地毯材质配置，针对地毯需要不同类型的填充材质的情况，比如羊毛地毯，长毛地毯等等
+        // 优先级比src要高，非必要情况，非必要不要传递，使用src的配置即可
+        material?: { type: number; src: string; opacity: number; scale: number }[]
+        // 地毯是否支持编辑，默认为false，非必要不要开启，会影响地毯绘制性能
+        enableEdit?: boolean
     }
 
     /** 机器人配置 */
@@ -544,6 +550,49 @@ export declare type AppOptions = {
     runtime: DeepPartialRuntimeConfig
 }
 
+declare abstract class BaseControlButton<T extends BaseControlButtonOptions = BaseControlButtonOptions> extends FixedSizeContainer {
+    protected background: Graphics;
+    protected icon: EnhancedSprite;
+    protected options: T;
+    constructor(options: T);
+    /**
+     * 抽象方法：子类需要实现具体的事件监听逻辑
+     */
+    protected abstract setupEvents(): void;
+    /**
+     * 设置点击热区
+     */
+    private setupHitArea;
+    /**
+     * 渲染按钮
+     */
+    private render;
+    /**
+     * 渲染背景
+     */
+    protected renderBackground(): void;
+    /**
+     * 渲染图标
+     */
+    protected renderIcon(): Promise<void>;
+    /**
+     * 销毁组件
+     */
+    destroy(): void;
+}
+
+declare type BaseControlButtonOptions = {
+    iconAlias: string;
+    backgroundColor: ColorSource;
+    config?: {
+        iconWrapperWidth: number;
+        iconWrapperHeight: number;
+        iconWrapperBorderRadius: number;
+        iconWidth: number;
+        iconHeight: number;
+    };
+};
+
 /**
  * 基础自定义元素参数（所有类型共享）
  */
@@ -567,6 +616,54 @@ export declare type BaseCustomElementParam = {
     sizeFixed?: boolean
 }
 
+/** 区域和地毯配置的基础类型 */
+export declare type BaseZoneConfig = {
+    /** 最小尺寸 (米) */
+    minSize: number
+    /** 图标容器填充颜色 */
+    iconWrapperFillColor: ColorSource
+    /** 描边颜色 */
+    strokeColor: ColorSource
+    /** 描边宽度 */
+    strokeWidth: number
+    /** 填充颜色 */
+    fillColor: ColorSource
+    /** 轮廓偏移 */
+    outlineOffset: number
+    /** 轮廓描边颜色 */
+    outlineStrokeColor: ColorSource
+    /** 轮廓描边宽度 */
+    outlineStrokeWidth: number
+    /** 轮廓填充颜色 */
+    outlineFillColor: ColorSource
+    /** 轮廓是否虚线 */
+    outlineDashed: boolean
+    /** 轮廓虚线数组 */
+    outlineDashArray: [number, number]
+    /** 是否显示旋转图标 */
+    showRotateButton: boolean
+    /** 文本颜色 */
+    textColor: ColorSource
+    /** 文本位置 */
+    textPosition: 'top' | 'right' | 'bottom' | 'left'
+    /** 文本偏移 */
+    textOffset: number
+    /** 编辑模式样式 */
+    editing: {
+        /** 是否虚线 */
+        isDashed: boolean
+        /** 虚线数组 */
+        dashArray: [number, number]
+    }
+    /** 普通模式样式 */
+    normal: {
+        /** 是否虚线 */
+        isDashed: boolean
+        /** 虚线数组 */
+        dashArray: [number, number]
+    }
+}
+
 /** 边界框 */
 export declare type Bounds = {
     /** 最小X坐标 */
@@ -619,6 +716,18 @@ declare class Carpet extends Container {
     destroy(): void;
 }
 
+/** 地毯配置 */
+export declare type CarpetConfig = BaseZoneConfig & {
+    /** 是否开启自由旋转模式 */
+    enableFreeRotate: boolean
+}
+
+declare type CarpetOptions = {
+    carpetData: CustomCarpetParam;
+    textureMap: Map<number, Texture>;
+    events?: CustomCarpetEvents;
+};
+
 declare class ChargingStation extends Container {
     chargingStation: ChargingStationIcon;
     ring: Ring;
@@ -669,6 +778,10 @@ export declare type ControlsConfig = {
     scaleIconSrc: string
     /** 移动图标资源路径 */
     moveIconSrc: string
+    /** 横向缩放图标资源路径 */
+    horizontalScaleIconSrc: string
+    /** 纵向缩放图标资源路径 */
+    verticalScaleIconSrc: string
     /** 移动按钮偏移 */
     moveButtonOffset: number
     /** 文本字体大小 */
@@ -683,6 +796,8 @@ export declare type ControlsConfig = {
     forbiddenMopZone: ZoneConfig
     /** 清扫区域配置 */
     cleanZone: ZoneConfig
+    /** 地毯配置 */
+    carpet: CarpetConfig
     /** 虚拟墙配置 */
     virtualWall: VirtualWallConfig
     /** 定点清扫配置 */
@@ -904,6 +1019,282 @@ declare class ControlsManager {
     destroy(): void;
 }
 
+declare class CustomCarpet extends Container {
+    private carpetData;
+    private carpetConfig;
+    private controlsConfig;
+    private carpetEvents;
+    private controlFill;
+    private editControlLayer;
+    private clickHandler;
+    private maskContainer;
+    private maskGraphics;
+    private texture;
+    private textureMap;
+    private tilingSprite;
+    private initialZonePoints;
+    private unsubscribeFns;
+    constructor(options: CarpetOptions);
+    /**
+     * 处理地毯数据（点集合）
+     */
+    private processCarpetData;
+    /**
+     * 获取控制元素配置
+     */
+    private getControlsConfig;
+    /**
+     * 获取当前编辑状态（是否在 editingCarpetIds 中）
+     */
+    private isEditingEnabled;
+    /**
+     * 获取当前选中状态（是否在 selectedCarpetIds 中）
+     */
+    private isSelected;
+    /**
+     * 是否应该显示编辑框（在 editingCarpetIds 或 selectedCarpetIds 中）
+     */
+    private shouldShowEditControl;
+    /**
+     * 初始化组件
+     */
+    private initializeComponents;
+    /**
+     * 创建遮罩容器（用于地毯纹理）
+     */
+    private createMaskContainer;
+    /**
+     * 创建控制填充组件
+     */
+    private createControlFill;
+    /**
+     * 创建编辑控制层（通过 EditControlManager）
+     */
+    private createEditControlLayer;
+    /**
+     * 设置点击处理器（用于非编辑状态下的点击）
+     */
+    private setupClickHandler;
+    /**
+     * 设置 enableRoomSelection 监听器
+     */
+    private setupEnableRoomSelectionListener;
+    /**
+     * 检查是否启用了房间选择模式
+     */
+    private isRoomSelectionEnabled;
+    /**
+     * 更新点击处理器状态
+     */
+    private updateClickHandlerState;
+    /**
+     * 计算地毯边界
+     */
+    private calculateBounds;
+    /**
+     * 计算自定义形状的外接矩形点集
+     */
+    private calculateBoundingRectanglePoints;
+    /**
+     * 更新遮罩形状
+     */
+    private updateMaskShape;
+    /**
+     * 异步加载地毯纹理
+     */
+    private loadTexture;
+    /**
+     * 创建平铺纹理精灵
+     */
+    private createTilingSprite;
+    /**
+     * 更新平铺纹理位置和大小
+     */
+    private updateTilingSprite;
+    /**
+     * 处理拖拽开始
+     */
+    private handleDragStart;
+    /**
+     * 处理拖拽移动
+     */
+    private handleDragMove;
+    /**
+     * 处理拖拽结束
+     */
+    private handleDragEnd;
+    /**
+     * 处理移动开始
+     */
+    private handleMoveStart;
+    /**
+     * 处理移动过程
+     */
+    private handleMove;
+    /**
+     * 处理移动结束
+     */
+    private handleMoveEnd;
+    /**
+     * 应用平移变换（拖拽和移动的公共方法）
+     */
+    private applyTranslation;
+    /**
+     * 处理旋转开始
+     */
+    private handleRotationStart;
+    /**
+     * 处理旋转移动
+     */
+    private handleRotationMove;
+    /**
+     * 处理旋转结束
+     */
+    private handleRotationEnd;
+    /**
+     * 处理缩放开始
+     */
+    private handleScaleStart;
+    /**
+     * 处理缩放移动
+     */
+    private handleScaleMove;
+    /**
+     * 处理水平缩放移动
+     */
+    private handleScaleMoveHorizontal;
+    /**
+     * 处理垂直缩放移动
+     */
+    private handleScaleMoveVertical;
+    /**
+     * 处理缩放结束
+     */
+    private handleScaleEnd;
+    /**
+     * 处理删除操作
+     */
+    private handleDelete;
+    /**
+     * 处理点击事件
+     */
+    private handleClick;
+    /**
+     * 处理点集更新
+     */
+    private handlePointsUpdate;
+    /**
+     * 绘制地毯
+     */
+    private drawCarpet;
+    /**
+     * 更新编辑状态（公共方法）
+     */
+    updateEditState(): void;
+    /**
+     * 更新地毯数据
+     */
+    updateCarpetData(newData: CustomCarpetParam): void;
+    /**
+     * 获取当前地毯数据
+     */
+    getCarpetData(): CustomCarpetParam;
+    /**
+     * 刷新显示（用于单位变化等场景）
+     */
+    refreshDisplay(): void;
+    /**
+     * 销毁组件
+     */
+    destroy(): void;
+}
+
+declare type CustomCarpetEvents = {
+    onRemove?: (id: string) => void;
+    onUpdate?: (zone: CustomCarpetParam) => void;
+    onClick?: (zone: CustomCarpetParam) => void;
+};
+
+declare class CustomCarpetManager {
+    private customCarpetMap;
+    private unsubscribeFns;
+    private textureMap;
+    private texturesLoaded;
+    private texturesLoadingPromise;
+    constructor();
+    /**
+     * 加载材质纹理
+     * 如果已经加载过，直接返回已完成的 Promise
+     * 如果正在加载，返回正在进行的 Promise
+     * 如果未加载，开始加载并返回 Promise
+     */
+    loadTextures(): Promise<void>;
+    /**
+     * 内部方法：实际加载纹理
+     */
+    private _loadTextures;
+    /**
+     * 根据地图原点更新所有自定义地毯位置
+     */
+    updatePositionByOrigin(x: number, y: number): void;
+    /**
+     * 绘制自定义地毯
+     */
+    drawCustomCarpets(carpets: CustomCarpetParam[]): Promise<void>;
+    /**
+     * 获取所有自定义地毯数据
+     */
+    getCustomCarpets(): CustomCarpetParam[];
+    /**
+     * 根据 ID 获取自定义地毯
+     */
+    getCustomCarpetById(id: string): CustomCarpet | undefined;
+    /**
+     * 清除所有自定义地毯
+     */
+    clearAllCustomCarpets(): void;
+    /**
+     * 添加新自定义地毯到 LAYER_CUSTOM_CARPET
+     */
+    private addNewCustomCarpet;
+    /**
+     * 移除自定义地毯
+     */
+    private removeCustomCarpet;
+    /**
+     * 更新自定义地毯编辑状态
+     */
+    private updateCarpetsEditState;
+    /**
+     * 比较两个地毯数据是否相等
+     */
+    private isCarpetDataEqual;
+    /**
+     * 刷新显示（单位变化时调用）
+     */
+    refreshDisplay(): void;
+    /**
+     * 销毁管理器
+     */
+    destroy(): void;
+}
+
+/** 自定义地毯参数 */
+export declare type CustomCarpetParam = {
+    /** 地毯ID */
+    id: string
+    /** 地毯材质 */
+    type: number
+    /** 点集合（用于矩形和圆形） */
+    points?: Point[]
+
+    /** 形状 */
+    shape: 'rectangle' | 'round' | 'custom',
+
+    /** 自定义数据 */
+    customData?: Record<string, any>
+}
+
 /**
  * 自定义元素参数
  */
@@ -1072,6 +1463,351 @@ export declare type DividerConfig = {
     defaultDirection: Direction
 }
 
+declare type EditControlConfig = {
+    outlineStrokeColor: ColorSource;
+    outlineStrokeWidth: number;
+    outlineDashed: boolean;
+    outlineDashArray: [number, number];
+    outlineFillColor?: ColorSource;
+    outlineOffset: number;
+    iconWrapperFillColor: ColorSource;
+    showRotateButton: boolean;
+    showScaleButton?: boolean;
+    showRadialScaleButton?: boolean;
+    showDeleteButton?: boolean;
+    showMoveButton?: boolean;
+    textColor: ColorSource;
+    textPosition: 'top' | 'right' | 'bottom' | 'left';
+    textOffset: number;
+    moveButtonOffset: number;
+    textFontSize: number;
+    textFontFamily: string;
+    textFontWeight: TextStyleFontWeight;
+};
+
+declare type EditControlEvents = {
+    onRemove?: () => void;
+    onRotateStart?: (rotationCenter: Point) => void;
+    onRotateMove?: (newPoints?: Point[]) => void;
+    onRotateEnd?: () => void;
+    onClickRotate?: (newPoints?: Point[]) => void;
+    onScaleStart?: () => void;
+    onScaleMove?: (newPoints?: Point[]) => void;
+    onScaleMoveHorizontal?: (newPoints?: Point[]) => void;
+    onScaleMoveVertical?: (newPoints?: Point[]) => void;
+    onScaleEnd?: () => void;
+    onMoveStart?: () => void;
+    onMoveMove?: (event: FederatedPointerEvent) => void;
+    onMoveEnd?: () => void;
+    onClick?: () => void;
+    onPointsUpdate?: (newPoints: Point[]) => void;
+};
+
+/**
+ * 编辑控制层组件
+ * 统一管理编辑状态下的控制按钮、轮廓边框、移动延长线和尺寸文本
+ */
+declare class EditControlLayer extends Container {
+    private config;
+    private events;
+    private zonePoints;
+    private outlinePoints;
+    private minSize;
+    private initialZonePoints;
+    private scaleCache;
+    private rotationCache;
+    private outlineBorder;
+    private moveLine;
+    private sizeText;
+    private controlButtons;
+    private deleteButton;
+    private rotateButton;
+    private scaleButton;
+    private moveButton;
+    private horizontalScaleButton;
+    private verticalScaleButton;
+    private horizontalScaleInitialPosition;
+    private verticalScaleInitialPosition;
+    private clickHandler;
+    private throttledUpdateOutline;
+    constructor(options: EditControlLayerOptions);
+    /**
+     * 初始化组件
+     */
+    private initializeComponents;
+    /**
+     * 创建轮廓边框
+     */
+    private createOutlineBorder;
+    /**
+     * 创建移动按钮延长线
+     */
+    private createMoveLine;
+    /**
+     * 创建尺寸文本
+     */
+    private createSizeText;
+    private createDeleteButton;
+    private createRotateButton;
+    private onClickRotateButton;
+    private createScaleButton;
+    private createHorizontalScaleButton;
+    private createVerticalScaleButton;
+    private createMoveButton;
+    /**
+     * 创建并添加按钮到容器
+     */
+    private createAndAddButton;
+    /**
+     * 创建控制按钮
+     */
+    private createControlButtons;
+    /**
+     * 计算轮廓边框的点
+     */
+    private calculateOutlinePoints;
+    /**
+     * 计算移动按钮的位置（在 MOVE 点的延长线上）
+     * 使用角平分线算法计算按钮位置，使其位于 MOVE、SCALE、REMOVE 三个点形成的角的角平分线上
+     */
+    private calculateMoveButtonPosition;
+    /**
+     * 计算移动按钮延长线的点
+     * 返回从 MOVE 点到移动按钮位置的线段
+     */
+    private calculateMoveLinePoints;
+    /**
+     * 计算区域尺寸文本（宽x高格式）
+     */
+    private calculateSizeText;
+    /**
+     * 计算边的中点
+     */
+    private getEdgeCenter;
+    /**
+     * 计算垂直于边的偏移方向
+     * @param start 边的起点
+     * @param end 边的终点
+     * @param offset 偏移距离
+     * @param reverseNormal 是否反转法向量方向（用于 bottom case）
+     */
+    private calculatePerpendicularOffset;
+    /**
+     * 计算尺寸文本位置（基于textPosition）
+     */
+    private calculateSizeTextPosition;
+    /**
+     * 计算尺寸文本旋转角度（与对应边平行）
+     */
+    private calculateSizeTextRotation;
+    /**
+     * 计算水平缩放按钮旋转角度（与右侧边平行）
+     */
+    private calculateHorizontalScaleButtonRotation;
+    /**
+     * 计算垂直缩放按钮旋转角度（与底边平行）
+     */
+    private calculateVerticalScaleButtonRotation;
+    /**
+     * 更新点集（公共方法）
+     */
+    updatePoints(points: Point[]): void;
+    /**
+     * 更新轮廓边框
+     */
+    updateOutlineBorder(): void;
+    /**
+     * 更新移动按钮延长线
+     */
+    updateMoveLine(): void;
+    /**
+     * 更新尺寸文本
+     */
+    updateSizeText(): void;
+    /**
+     * 更新尺寸文本位置
+     */
+    updateSizeTextPosition(): void;
+    /**
+     * 更新控制按钮位置
+     */
+    updateControlButtonsPosition(): void;
+    /**
+     * 设置点击处理器
+     */
+    private setupClickHandler;
+    /**
+     * 注册缩放事件监听
+     */
+    private registerScaleListener;
+    /**
+     * 处理缩放变化时的outline更新
+     */
+    private updateOutlineForScale;
+    /**
+     * 初始化缩放计算缓存
+     */
+    private initializeScaleCache;
+    /**
+     * 处理内部缩放移动
+     * @param deltaX X 方向的偏移量
+     * @param deltaY Y 方向的偏移量
+     * @returns 计算后的新点集，如果无法缩放则返回 null
+     */
+    private handleInternalScaleMove;
+    /**
+     * 重置缩放状态
+     */
+    private resetScaleState;
+    /**
+     * 处理内部水平缩放移动
+     * @param deltaX X 方向的偏移量
+     * @param deltaY Y 方向的偏移量
+     * @returns 计算后的新点集，如果无法缩放则返回 null
+     */
+    private handleInternalHorizontalScaleMove;
+    /**
+     * 处理内部垂直缩放移动
+     * @param deltaX X 方向的偏移量
+     * @param deltaY Y 方向的偏移量
+     * @returns 计算后的新点集，如果无法缩放则返回 null
+     */
+    private handleInternalVerticalScaleMove;
+    /**
+     * 根据缩放比例计算新的点集
+     */
+    private calculatePointsFromScale;
+    /**
+     * 初始化旋转计算缓存
+     */
+    private initializeRotationCache;
+    /**
+     * 处理内部旋转移动
+     * 优化：基于初始点集和累计角度计算，避免累积误差
+     * @returns 计算后的新点集，如果无法旋转则返回 null
+     */
+    private handleInternalRotationMove;
+    /**
+     * 重置旋转状态
+     */
+    private resetRotationState;
+    /**
+     * 计算旋转中心（用于点击旋转）
+     */
+    private calculateRotationCenter;
+    /**
+     * 更新编辑状态
+     * @param options 控制各个元素显示/隐藏的选项
+     */
+    updateEditState({ showRotateButton, showScaleButton, showRadialScaleButton, showDeleteButton, showMoveButton, showBorder, showSizeText, borderStyle, }: {
+        showRotateButton?: boolean;
+        showScaleButton?: boolean;
+        showRadialScaleButton?: boolean;
+        showDeleteButton?: boolean;
+        showMoveButton?: boolean;
+        showBorder?: boolean;
+        showSizeText?: boolean;
+        borderStyle?: {
+            isDashed: boolean;
+            dashArray?: [number, number];
+        };
+    }): void;
+    /**
+     * 获取操作状态
+     */
+    getOperationState(): OperationState;
+    /**
+     * 停止所有操作
+     */
+    stopAllOperations(): void;
+    /**
+     * 获取控制按钮容器（供外部添加额外按钮）
+     */
+    getControlButtonsContainer(): Container;
+    /**
+     * 获取移动按钮（供外部调用）
+     */
+    getMoveButton(): MoveControlButton | null;
+    /**
+     * 计算指定边的中点位置
+     * @param startIndex 起始点索引
+     * @param endIndex 结束点索引
+     */
+    calculateEdgeMidpoint(startIndex: number, endIndex: number): Point;
+    /**
+     * 销毁组件
+     */
+    destroy(): void;
+}
+
+declare type EditControlLayerOptions = {
+    config: EditControlConfig;
+    zonePoints: Point[];
+    events?: EditControlEvents;
+    minSize?: number;
+};
+
+/**
+ * 编辑控制管理器
+ * 统一管理所有编辑控制层，将它们放在最顶层以确保始终可见
+ */
+declare class EditControlManager {
+    private editControlLayers;
+    constructor();
+    /**
+     * 注册编辑控制层
+     * @param id 组件唯一标识（如 Zone ID、Carpet ID）
+     * @param options 编辑控制层配置
+     * @returns 创建的 EditControlLayer 实例
+     */
+    registerEditControl(id: string | number, options: EditControlLayerOptions): EditControlLayer;
+    /**
+     * 注销编辑控制层
+     * @param id 组件唯一标识
+     */
+    unregisterEditControl(id: string | number): void;
+    /**
+     * 获取编辑控制层
+     * @param id 组件唯一标识
+     * @returns EditControlLayer 实例，如果不存在则返回 undefined
+     */
+    getEditControl(id: string | number): EditControlLayer | undefined;
+    /**
+     * 更新编辑控制层状态
+     * @param id 组件唯一标识
+     * @param options 控制各个元素显示/隐藏的选项
+     */
+    updateEditState(id: string | number, options: {
+        showRotateButton?: boolean;
+        showScaleButton?: boolean;
+        showRadialScaleButton?: boolean;
+        showDeleteButton?: boolean;
+        showMoveButton?: boolean;
+        showBorder?: boolean;
+        showSizeText?: boolean;
+        borderStyle?: {
+            isDashed: boolean;
+            dashArray?: [number, number];
+        };
+    }): void;
+    /**
+     * 清空所有编辑控制层
+     */
+    clearAll(): void;
+    /**
+     * 获取所有编辑控制层
+     * @returns 所有编辑控制层的数组
+     */
+    getAllEditControls(): EditControlLayer[];
+    updatePositionByOrigin(x: number, y: number): void;
+    /**
+     * 检查是否存在编辑控制层
+     * @param id 组件唯一标识
+     * @returns 是否存在
+     */
+    hasEditControl(id: string | number): boolean;
+}
+
 /**
  * 固定大小动画精灵基类
  * 基于 EnhancedSprite 扩展，支持帧动画播放
@@ -1276,6 +2012,31 @@ declare class EnhancedSprite extends Sprite {
     }): void;
 }
 
+/**
+ * 固定大小元素基类
+ * 用于创建在地图缩放时保持固定视觉大小的元素
+ */
+declare class FixedSizeContainer extends Container {
+    private throttledUpdateScale;
+    constructor();
+    /**
+     * 注册缩放事件监听
+     */
+    private registerScaleListener;
+    /**
+     * 更新元素缩放，以保持固定大小
+     */
+    protected updateScale(scale: number): void;
+    /**
+     * 组件销毁时清理资源
+     */
+    destroy(options?: {
+        children?: boolean;
+        texture?: boolean;
+        baseTexture?: boolean;
+    }): void;
+}
+
 declare class Free extends Graphics {
     constructor();
     /**
@@ -1317,7 +2078,10 @@ declare class Heatmap extends Container {
         y: number;
         signal: number;
         hasPoint: boolean;
-    }>>, useGradient?: boolean, heatmapAlpha?: number): void;
+    }>>, useGradient?: boolean, heatmapAlpha?: number, offset?: {
+        x: number;
+        y: number;
+    }): void;
     /**
      * 裁剪热力图 仅显示房间区域
      * 根据roomFill图层的子元素 组合Graphics生成大Graphics裁剪
@@ -1336,6 +2100,16 @@ declare class Heatmap extends Container {
      * @returns 渐变热力图mesh
      */
     private gradientDrawing;
+    /**
+     * 更新位置
+     * @param x
+     * @param y
+     */
+    updatePositionByOrigin(x: number, y: number): void;
+    /**
+     * 销毁热力图
+     */
+    destroy(): void;
 }
 
 declare class HeatmapManager {
@@ -1369,12 +2143,22 @@ declare class HeatmapManager {
      * @param pointsTopLeftOrigin 热力图路径点
      * @returns 信号网格
      */
-    calculateInterpolatedSignal(pointsTopLeftOrigin: HeatmapPoint[]): {
+    calculateInterpolatedSignal(pointsTopLeftOrigin: HeatmapPoint[], mapData: MapDataSource): {
         x: number;
         y: number;
         signal: number;
         hasPoint: boolean;
     }[][];
+    /**
+     * 更新热力图位置
+     * @param x
+     * @param y
+     */
+    updatePositionByOrigin(x: number, y: number): void;
+    /**
+     * 销毁热力图
+     */
+    destroy(): void;
 }
 
 /** 热力图点 */
@@ -1515,6 +2299,10 @@ declare class Interaction extends Container {
      */
     private updateInteractionMode;
     setupInteraction(): void;
+    /**
+     * 处理全局取消或失去焦点事件
+     */
+    private handleGlobalCancel;
     resetPan(targetPosition: {
         x: number;
         y: number;
@@ -1563,6 +2351,10 @@ declare class Interaction extends Container {
      * 退出手势劫持模式
      */
     private exitGestureHijacked;
+    /**
+     * 强制结束当前正在进行的手势交互
+     */
+    forceEndGesture(): void;
     /**
      * 暂停手势劫持（双指模式）
      */
@@ -1598,11 +2390,13 @@ declare type Managers = {
     detectedObjectManager: DetectedObjectManager;
     customElementsManager: CustomElementsManager;
     roomsManager: RoomManager;
+    customCarpetManager: CustomCarpetManager;
+    editControlManager: EditControlManager;
 };
 
-export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getSpots", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData"];
+export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getSpots", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture"];
 
-export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateSpot", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickSpot", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap"];
+export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateSpot", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickSpot", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd"];
 
 /**
  * 地图 API 接口定义
@@ -1619,6 +2413,12 @@ export declare interface MapApi {
      * 将地图的缩放和平移状态重置到初始位置，使地图完整显示在视口中。
      */
     resetPanZoom(): void;
+    /**
+     * 强制结束当前正在进行的手势交互
+     *
+     * 当小程序侧检测到 touchend 或其他需要强制结束手势的情况时调用。
+     */
+    forceEndGesture(): void;
     /**
      * 获取当前地图上所有禁扫区域数据
      *
@@ -1637,6 +2437,12 @@ export declare interface MapApi {
      * @returns 区域数据数组
      */
     getCleanZones(): ZoneParam[];
+    /**
+     * 获取当前地图上所有自定义地毯数据
+     *
+     * @returns 地毯数据数组
+     */
+    getCustomCarpets(): CustomCarpetParam[];
     /**
      * 获取当前地图上所有虚拟墙数据
      *
@@ -1899,7 +2705,7 @@ declare class MapApplication extends Application implements MapApi {
      * @returns Promise<void>
      *
      */
-    drawMap(mapData: MapDataSource): Promise<void>;
+    drawMap(mapData: StructuredMapDataSource): Promise<void>;
     /**
      * 绘制栅格地图数据
      *
@@ -1935,6 +2741,12 @@ declare class MapApplication extends Application implements MapApi {
      *
      */
     drawRoomProperty(roomInfos: RoomProperty[]): Promise<void>;
+    /**
+     * 绘制自定义地毯
+     * @param carpets 自定义地毯数组
+     * @returns void
+     */
+    drawCustomCarpets(carpets: CustomCarpetParam[]): Promise<void>;
     /**
      * 绘制热力图
      * @param param - 绘制参数
@@ -1981,6 +2793,11 @@ declare class MapApplication extends Application implements MapApi {
      * @param objects - 检测物体参数数组
      */
     drawDetectedObjects(objects: DetectedObjectParam[]): Promise<void>;
+    /**
+     * 绘制自定义地毯
+     * @param customCarpet - 自定义地毯参数数组
+     */
+    drawCustomCarpet(customCarpet: CustomCarpetParam[]): void;
     /**
      * 绘制自定义元素
      * @param elements - 自定义元素参数数组
@@ -2027,6 +2844,11 @@ declare class MapApplication extends Application implements MapApi {
      * @returns 分割线有效端点
      */
     getEffectiveDividerPoints(): Point[] | null;
+    /**
+     * 获取当前地图上所有自定义地毯数据
+     * @returns 地毯数据数组
+     */
+    getCustomCarpets(): CustomCarpetParam[];
     /**
      * 获取分割线端点
      * @returns 分割线端点
@@ -2039,6 +2861,12 @@ declare class MapApplication extends Application implements MapApi {
      * 将地图的缩放和平移状态重置到初始位置，使地图完整显示在视口中。
      */
     resetPanZoom(): void;
+    /**
+     * 强制结束当前正在进行的手势交互
+     *
+     * 当小程序侧检测到 touchend 或其他需要强制结束手势的情况时调用。
+     */
+    forceEndGesture(): void;
     /**
      * 将地图适配到视图中，居中并缩放
      * @param mapBounds 地图边界信息
@@ -2580,6 +3408,55 @@ export declare interface MapCallbacks {
      *
      */
     onClickMap?: (point: Point) => void;
+    /**
+     * 点击地毯回调
+     *
+     * 当用户点击地毯区域时触发（需要启用 carpet.enableEdit）。
+     *
+     * @param carpet - 被点击的地毯信息，包含索引和数据
+     *
+     */
+    onClickCarpet?: (carpet: {
+        id: string;
+    }) => void;
+    /**
+     * 删除地图地毯回调
+     *
+     * 当用户删除地图中的地毯时触发。
+     *
+     * @param carpet - 被删除的地毯信息
+     *
+     */
+    onDeleteCarpet?: (carpet: {
+        id: string;
+    }) => void;
+    /**
+     * 删除自定义地毯回调
+     *
+     * 当用户删除自定义地毯时触发。
+     *
+     * @param carpet - 被删除的自定义地毯信息
+     *
+     */
+    onDeleteCustomCarpet?: (carpet: {
+        id: string;
+    }) => void;
+    /**
+     * 更新自定义地毯回调
+     *
+     * 当用户编辑自定义地毯（移动、旋转、缩放）后触发。
+     *
+     * @param carpet - 更新后的自定义地毯数据
+     *
+     */
+    onUpdateCustomCarpet?: (carpet: CustomCarpetParam) => void;
+    onGestureStart?: () => void;
+    /**
+     * 手势交互结束回调
+     *
+     * 当用户结束手势交互时触发。
+     */
+    onGestureEnd?: () => void;
 }
 
 /**
@@ -2655,7 +3532,7 @@ declare class MapManager {
     /**
      * 处理结构化地图数据（房间形状、障碍物等）
      */
-    drawMap(mapData: MapDataSource): Promise<boolean>;
+    drawMap(mapData: StructuredMapDataSource): Promise<boolean>;
     /**
      * 处理栅格地图数据
      * @param mapPointsStr 栅格数据字符串
@@ -2676,6 +3553,13 @@ declare class MapManager {
      * @returns 是否需要触发fitMapToView
      */
     private shouldFitMapToView;
+    /**
+     * 将栅格数据转换为结构化数据格式
+     * @param carpetPixels 地毯像素数据
+     * @param mapWidth 地图宽度
+     * @returns 结构化地毯数据数组
+     */
+    private convertRasterToStructuredData;
     /**
      * 更新地毯显示
      * 类似于RoomFloorType的模式，根据当前状态决定是否重建地毯
@@ -2806,6 +3690,66 @@ export declare type MapType = 'structured' | 'raster'
 /** 测量单位 */
 export declare type MeasurementUnit = 'meter' | 'feet' | 'centimeter'
 
+declare class MoveControlButton extends BaseControlButton<MoveControlButtonOptions> {
+    private isMoving;
+    private dragStartPosition;
+    constructor(options: MoveControlButtonOptions);
+    /**
+     * 设置移动事件监听
+     */
+    private setupMoveEventListeners;
+    /**
+     * 清理移动事件监听
+     */
+    private cleanupMoveEventListeners;
+    /**
+     * 设置手势事件监听
+     */
+    protected setupEvents(): void;
+    /**
+     * 处理指针按下事件（开始移动）
+     */
+    private handlePointerDown;
+    /**
+     * 开始移动
+     */
+    private startMoving;
+    /**
+     * 处理移动过程中的指针移动
+     */
+    private handleMovePointerMove;
+    /**
+     * 处理移动结束
+     */
+    private handleMovePointerUp;
+    /**
+     * 处理移动取消（多点触控干扰）
+     */
+    private handleMoveCancel;
+    /**
+     * 获取是否正在移动
+     */
+    isCurrentlyMoving(): boolean;
+    /**
+     * 获取拖拽开始位置
+     */
+    getDragStartPosition(): Point | null;
+    /**
+     * 强制停止移动（用于清理）
+     */
+    stopMoving(): void;
+    /**
+     * 销毁组件
+     */
+    destroy(): void;
+}
+
+declare type MoveControlButtonOptions = BaseControlButtonOptions & {
+    onMoveStart?: () => void;
+    onMoveMove?: (event: FederatedPointerEvent) => void;
+    onMoveEnd?: () => void;
+};
+
 declare class Obstacle extends Graphics {
     constructor();
     /**
@@ -2833,6 +3777,14 @@ declare class Obstacle extends Graphics {
  */
 export declare const offsetPointsToAvoidOverlap: (points: Point[], existingPointsArray: Point[][], maxAttempts?: number) => Point[];
 
+declare type OperationState = {
+    isDragging: boolean;
+    isScaling: boolean;
+    isRotating: boolean;
+    isMoving: boolean;
+    hasAnyOperation: boolean;
+};
+
 /**
  * 解析后的点阵地图数据
  */
@@ -3506,6 +4458,8 @@ export declare type RuntimeConfig = {
     editingSpotIds: string[]
     /** 正在编辑的途径点ID列表 */
     editingWayPointIds: string[]
+    /** 正在编辑的地毯ID列表 */
+    editingCarpetIds: string[]
     /** 地图旋转角度（度） */
     mapRotation: number
     /** 房间属性折叠的房间ID列表 */
@@ -3542,6 +4496,8 @@ export declare type RuntimeConfig = {
     showRobotSleepAnimation: boolean
     /** 是否显示机器人脉冲圈 */
     showRobotPulseCircle: boolean
+    /** 选中的地毯ID列表 */
+    selectedCarpetIds: string[]
 }
 
 /**
@@ -3825,52 +4781,7 @@ export declare type WayPointParam = {
 }
 
 /** 区域配置 */
-export declare type ZoneConfig = {
-    /** 最小尺寸 (米) */
-    minSize: number
-    /** 图标容器填充颜色 */
-    iconWrapperFillColor: ColorSource
-    /** 描边颜色 */
-    strokeColor: ColorSource
-    /** 描边宽度 */
-    strokeWidth: number
-    /** 填充颜色 */
-    fillColor: ColorSource
-    /** 轮廓偏移 */
-    outlineOffset: number
-    /** 轮廓描边颜色 */
-    outlineStrokeColor: ColorSource
-    /** 轮廓描边宽度 */
-    outlineStrokeWidth: number
-    /** 轮廓填充颜色 */
-    outlineFillColor: ColorSource
-    /** 轮廓是否虚线 */
-    outlineDashed: boolean
-    /** 轮廓虚线数组 */
-    outlineDashArray: [number, number]
-    /** 是否显示旋转图标 */
-    showRotateButton: boolean
-    /** 文本颜色 */
-    textColor: ColorSource
-    /** 文本位置 */
-    textPosition: 'top' | 'right' | 'bottom' | 'left'
-    /** 文本偏移 */
-    textOffset: number
-    /** 编辑模式样式 */
-    editing: {
-        /** 是否虚线 */
-        isDashed: boolean
-        /** 虚线数组 */
-        dashArray: [number, number]
-    }
-    /** 普通模式样式 */
-    normal: {
-        /** 是否虚线 */
-        isDashed: boolean
-        /** 虚线数组 */
-        dashArray: [number, number]
-    }
-}
+export declare type ZoneConfig = BaseZoneConfig
 
 /** 区域参数 */
 export declare type ZoneParam = {