@ray-js/robot-map-sdk 0.0.5-beta.4 → 0.0.6-beta.1

package/dist/index.d.ts

@@ -69,6 +69,8 @@ export declare type AppConfig = {
         smoothIterations: number
         /** 热力图透明度 */
         heatmapAlpha: number
+        /** 是否使用渐变 */
+        useGradient: boolean
         /** 颜色渐变配置 */
         colorGradients: [
         ColorSource,
@@ -475,6 +477,8 @@ export declare type AppConfig = {
 declare class AppContainer extends Container {
     private layers;
     private mapRotation;
+    private backgroundGraphics;
+    private lastBackgroundState;
     constructor();
     /**
      * 初始化所有预定义的层级
@@ -535,6 +539,17 @@ declare class AppContainer extends Container {
      * @returns 旋转角度（弧度）
      */
     getMapRotationRadians(): number;
+    /**
+     * 获取用于截图的完整边界
+     * 会合并所有可见图层的局部边界，确保截图能覆盖所有内容（包括超出初始地图范围的禁区等）
+     */
+    getSnapshotBounds(): Rectangle;
+    /**
+     * 更新截图背景（主渲染器显示版本）
+     * @param color 背景颜色
+     * @param visible 是否可见
+     */
+    updateBackground(color: ColorSource, visible: boolean): void;
 }
 
 /**
@@ -610,7 +625,7 @@ export declare type BaseCustomElementParam = {
     /** 是否可交互 */
     interactive?: boolean
     /** 自定义数据 */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
     customData?: Record<string, any>
     /** 尺寸是否固定 */
     sizeFixed?: boolean
@@ -1289,7 +1304,7 @@ export declare type CustomCarpetParam = {
     points?: Point[]
 
     /** 形状 */
-    shape: 'rectangle' | 'round' | 'custom',
+    shape: 'rectangle' | 'round' | 'custom'
 
     /** 自定义数据 */
     customData?: Record<string, any>
@@ -1428,7 +1443,7 @@ export declare type DetectedObjectParam = {
     /** 宽度 */
     width?: number
     /** 自定义数据 */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
     customData?: Record<string, any>
 }
 
@@ -2078,10 +2093,7 @@ declare class Heatmap extends Container {
         y: number;
         signal: number;
         hasPoint: boolean;
-    }>>, useGradient?: boolean, heatmapAlpha?: number, offset?: {
-        x: number;
-        y: number;
-    }): void;
+    }>>, heatmapAlpha?: number): void;
     /**
      * 裁剪热力图 仅显示房间区域
      * 根据roomFill图层的子元素 组合Graphics生成大Graphics裁剪
@@ -2125,25 +2137,33 @@ declare class HeatmapManager {
     maxDistance: number;
     smoothIterations: number;
     heatmapAlpha: number;
+    isHeatmapDrawn: boolean;
+    private loadTimer;
     constructor();
     /**
      * 绘制热力图
      * @param mapData 地图数据
      * @param heatmapPoints 热力图点
-     * @param useGradient 是否使用渐变绘制
      * @returns
      */
-    draw({ mapData, heatmapPoints, useGradient, }: {
-        mapData: MapDataSource;
-        heatmapPoints: HeatmapPoint[];
-        useGradient?: boolean;
-    }): void;
+    private pendingPoints;
+    /**
+     * 绘制热力图
+     * @param mapData 地图数据
+     * @param heatmapPoints 热力图点
+     * @returns
+     */
+    draw(heatmapPoints: HeatmapPoint[]): void;
+    /**
+     * 地图加载完成回调
+     */
+    onMapLoaded(): void;
     /**
      * 插值计算信号网格
      * @param pointsTopLeftOrigin 热力图路径点
      * @returns 信号网格
      */
-    calculateInterpolatedSignal(pointsTopLeftOrigin: HeatmapPoint[], mapData: MapDataSource): {
+    calculateInterpolatedSignal(pointsTopLeftOrigin: HeatmapPoint[]): {
         x: number;
         y: number;
         signal: number;
@@ -2407,6 +2427,8 @@ export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapD
  *
  */
 export declare interface MapApi {
+    /** 地图是否绘制完成 */
+    isMapDrawn: boolean;
     /**
      * 重置地图的平移和缩放状态
      *
@@ -2624,28 +2646,35 @@ export declare interface MapApi {
     /**
      * 地图截图
      *
-     * 将当前地图状态导出为图片，支持多种格式和质量设置。
+     * 将当前地图状态导出为图片。截图过程中会自动添加一个临时的背景层，
+     * 确保禁区等半透明元素在截图中能够正确显示颜色。
      *
-     * @returns Promise<string> Base64 格式的图片数据
+     * @param options - 截图配置选项
+     * @param options.backgroundColor - 指定截图时的背景颜色。若不指定，将默认使用 `global.config.backgroundColor`。支持颜色字符串、十六进制数值或 RGB 数组。
+     * @returns Promise<string> Base64 格式的图片数据 (Data URL)
      */
-    snapshot(): Promise<string>;
+    snapshot(options?: {
+        backgroundColor?: ColorSource;
+    }): Promise<string>;
     /**
-     * 使用其他地图数据进行截图
+     * 使用自定义地图数据生成截图
      *
-     * 基于提供的地图数据生成截图，主要用于多地图场景或预览功能。
-     * 不会影响当前地图的显示状态。
+     * 基于提供的地图、路径、区域等数据生成截图，通常用于多地图管理界面的缩略图预览。
+     * 此方法会创建一个临时的离屏渲染实例，不会影响当前正在运行的地图显示状态。
      *
-     * @param data - 地图数据对象
-     * @param data.map - 地图字符串数据
-     * @param data.path - 可选的路径数据
-     * @param data.roomProperties - 可选的房间属性数据
-     * @param data.customElements - 可选的自定义元素数据
-     * @param data.forbiddenSweepZones - 可选的禁扫区域数据
-     * @param data.forbiddenMopZones - 可选的禁拖区域数据
-     * @param data.virtualWalls - 可选的虚拟墙数据
-     * @param data.detectedObjects - 可选的检测物体数据
-     * @param runtime - 可选的运行时配置
-     * @returns Promise<string> Base64 格式的图片数据
+     * @param data - 包含地图、路径、区域等完整状态的数据对象
+     * @param data.map - 地图原始字符串数据 (支持结构化协议和栅格协议)
+     * @param data.path - 可选的路径协议字符串
+     * @param data.roomProperties - 可选的房间属性数据数组
+     * @param data.customElements - 可选的自定义元素数组
+     * @param data.forbiddenSweepZones - 可选的禁扫区域数组
+     * @param data.forbiddenMopZones - 可选的禁拖区域数组
+     * @param data.virtualWalls - 可选的虚拟墙数组
+     * @param data.detectedObjects - 可选的 AI 物体检测数据数组
+     * @param runtime - 可选的运行时配置 (如是否显示机器人、充电桩等状态)
+     * @param options - 截图配置选项
+     * @param options.backgroundColor - 指定生成截图时的背景颜色。若不指定，将默认使用 `global.config.backgroundColor`。
+     * @returns Promise<string> Base64 格式的图片数据 (Data URL)
      */
     snapshotByData(data: {
         map: string;
@@ -2656,7 +2685,9 @@ export declare interface MapApi {
         forbiddenMopZones?: ZoneParam[];
         virtualWalls?: VirtualWallParam[];
         detectedObjects?: DetectedObjectParam[];
-    }, runtime?: DeepPartialRuntimeConfig): Promise<string>;
+    }, runtime?: DeepPartialRuntimeConfig, options?: {
+        backgroundColor?: ColorSource;
+    }): Promise<string>;
 }
 
 /**
@@ -2681,6 +2712,8 @@ declare class MapApplication extends Application implements MapApi {
     /* Excluded from this release type: tickerState */
     private pendingAsyncRender;
     private isFirstMapDraw;
+    /** 地图是否绘制完成 */
+    isMapDrawn: boolean;
     /* Excluded from this release type: __constructor */
     /**
      * 初始化地图应用
@@ -2753,11 +2786,7 @@ declare class MapApplication extends Application implements MapApi {
      * @returns void
      *
      */
-    drawHeatmap({ mapData, heatmapPoints, useGradient, }: {
-        mapData: MapDataSource;
-        heatmapPoints: HeatmapPoint[];
-        useGradient?: boolean;
-    }): void;
+    drawHeatmap(heatmapPoints: HeatmapPoint[]): void;
     /**
      * 绘制禁扫区域
      * @param zones - 禁扫区域参数数组
@@ -3094,12 +3123,17 @@ declare class MapApplication extends Application implements MapApi {
     /**
      * 地图截图
      *
-     * 将当前地图状态导出为图片，支持多种格式和质量设置。
+     * 将当前地图状态导出为图片。截图过程中使用离屏渲染技术，
+     * 确保禁区等半透明元素在截图中能够正确显示颜色，同时避免主视图闪烁。
      *
-     * @returns Promise<string> Base64 格式的图片数据
+     * @param options - 截图配置选项
+     * @param options.backgroundColor - 指定截图时的背景颜色。若不指定，将默认使用 `global.config.backgroundColor`。支持颜色字符串、十六进制数值或 RGB 数组。
+     * @returns Promise<string> Base64 格式的图片数据 (Data URL)
      *
      */
-    snapshot(): Promise<string>;
+    snapshot(options?: {
+        backgroundColor?: ColorSource;
+    }): Promise<string>;
     /**
      * 使用其他地图数据进行截图
      *
@@ -3128,7 +3162,9 @@ declare class MapApplication extends Application implements MapApi {
         forbiddenMopZones?: ZoneParam[];
         virtualWalls?: VirtualWallParam[];
         detectedObjects?: DetectedObjectParam[];
-    }, runtime?: DeepPartialRuntimeConfig): Promise<string>;
+    }, runtime?: DeepPartialRuntimeConfig, options?: {
+        backgroundColor?: ColorSource;
+    }): Promise<string>;
     /* Excluded from this release type: renderOnce */
     /* Excluded from this release type: renderOnceNextFrame */
     /* Excluded from this release type: requestRender */
@@ -4424,7 +4460,7 @@ export declare type RoomProperty = {
     /** 拖地模式 */
     yMop: number
     /** 自定义数据 */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
     customData?: Record<string, any>
 }