@ray-js/robot-map-sdk 0.0.17-beta.3 → 0.0.17-beta.5

package/dist/constant/methods.js

@@ -1 +1 @@
-const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getThresholdPointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};
+const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getRamps","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getThresholdPointsByViewportCenter","getRampPointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onRemoveRamp","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateRamp","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickRamp","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};

package/dist/index.d.ts

@@ -776,19 +776,24 @@ export declare type ComponentPropsApp = {
     app: MapApplicationInstance
 }
 
-/** 控制层内可排序元素 */
+/**
+ * 控制层内可排序元素。
+ *
+ * 门槛（threshold）不在其中：它是不透明地面元素，画在地面标记层
+ * （路径 / 机器人 / 房间名之下），层内顺序固定，不参与控制层排序
+ * （见 ADR 0006）。
+ */
 export declare type ControlRenderItem =
 | 'forbiddenSweepZone'
 | 'forbiddenMopZone'
 | 'cleanZone'
 | 'virtualWall'
-| 'threshold'
 | 'spot'
 | 'roomAnchor'
 | 'wayPoint'
 | 'divider'
 // Allow any string for custom zone types while keeping IDE autocomplete
-// for the seven built-in items via the `(string & {})` trick.
+// for the eight built-in items via the `(string & {})` trick.
 | (string & {})
 
 /**
@@ -839,6 +844,8 @@ export declare type ControlsConfig = {
     virtualWall: VirtualWallConfig
     /** 门槛配置 */
     threshold: ThresholdConfig
+    /** 坡道配置 */
+    ramp: RampConfig
     /** 定点清扫配置 */
     spot: SpotConfig
     /**
@@ -1130,9 +1137,9 @@ export declare type LoggerPayload = {
     ts: number
 }
 
-export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getThresholdPointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
+export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getRamps", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getThresholdPointsByViewportCenter", "getRampPointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
 
-export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onRoomsDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onRemoveThreshold", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateThreshold", "onUpdateSpot", "onUpdateRoomAnchor", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickThreshold", "onClickSpot", "onClickRoomAnchor", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd", "onClickRobot", "onClickChargingStation", "onRemoveFurniture", "onUpdateFurniture", "onClickFurniture", "onRemoveCustomZone", "onUpdateCustomZone", "onClickCustomZone"];
+export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onRoomsDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onRemoveThreshold", "onRemoveRamp", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateThreshold", "onUpdateRamp", "onUpdateSpot", "onUpdateRoomAnchor", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickThreshold", "onClickRamp", "onClickSpot", "onClickRoomAnchor", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd", "onClickRobot", "onClickChargingStation", "onRemoveFurniture", "onUpdateFurniture", "onClickFurniture", "onRemoveCustomZone", "onUpdateCustomZone", "onClickCustomZone"];
 
 /**
  * 地图 API 接口定义
@@ -1277,6 +1284,12 @@ export declare interface MapApi {
      * @returns 门槛数据数组（长度已修正，`height` 已补默认值并钳制）
      */
     getThresholds(): ThresholdParam[];
+    /**
+     * 获取当前地图上所有坡道数据
+     *
+     * @returns 坡道数据数组（角点为归一化后的结果）
+     */
+    getRamps(): RampParam[];
     /**
      * 获取当前地图上所有定点清扫数据
      *
@@ -1463,6 +1476,28 @@ export declare interface MapApi {
         offsetX?: number;
         offsetY?: number;
     }): Point[];
+    /**
+     * 基于视口中心生成坡道的四个角点坐标
+     *
+     * 缺省尺寸 0.8m × 0.4m（宽 × 高，高方向即坡向）—— 「新建坡道」的初始尺寸，不是配置项；
+     * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
+     * `controls.ramp` 的 `minWidth`/`maxWidth` 与 `minHeight`/`maxHeight`
+     * （米）区间内。
+     *
+     * @param options - 配置选项
+     * @param options.width - 坡道宽度，单位米，默认 0.8
+     * @param options.height - 坡道高度，单位米，默认 0.4（正好等于 minHeight）
+     * @param options.offsetX - X方向像素偏移，支持负数，默认为 0
+     * @param options.offsetY - Y方向像素偏移，支持负数，默认为 0
+     * @returns 四个角点坐标，顺时针顺序：[左上, 右上, 右下, 左下]（0→1 为宽
+     *   方向，0→3 为高方向），可直接作为 `RampParam.points`；坡向为屏幕上方
+     */
+    getRampPointsByViewportCenter(options?: {
+        width?: number;
+        height?: number;
+        offsetX?: number;
+        offsetY?: number;
+    }): Point[];
     /**
      * 基于任意中心点生成矩形的四个顶点坐标
      *
@@ -1746,6 +1781,15 @@ export declare interface MapCallbacks {
      * @param.en id - ID of the deleted threshold
      */
     onRemoveThreshold?: (id: string) => void;
+    /**
+     * @description.zh 点击坡道删除按钮的回调
+     * @description.en Callback when clicking the delete button of ramp
+     * @description.zh 当用户点击编辑态坡道的删除按钮时触发。SDK 不会移除该坡道，宿主更新自己的坡道列表后重绘。
+     * @description.en Triggered when the user clicks the delete button of an editing ramp. The SDK does not remove it; the host updates its own list and redraws.
+     * @param.zh id - 被删除的坡道ID
+     * @param.en id - ID of the deleted ramp
+     */
+    onRemoveRamp?: (id: string) => void;
     /**
      * @description.zh 更新禁扫区域的回调
      * @description.en Callback when updating forbidden sweep zone
@@ -1791,6 +1835,15 @@ export declare interface MapCallbacks {
      * @param.en threshold - Updated threshold data
      */
     onUpdateThreshold?: (threshold: ThresholdParam) => void;
+    /**
+     * @description.zh 更新坡道的回调
+     * @description.en Callback when updating ramp
+     * @description.zh 当用户完成一次坡道编辑操作（旋转 / 缩放 / 移动，或拖拽整体平移）后触发，携带最终几何。
+     * @description.en Triggered after the user finishes a ramp edit (rotate/scale/move, or body drag), carrying the final geometry.
+     * @param.zh ramp - 更新后的坡道数据
+     * @param.en ramp - Updated ramp data
+     */
+    onUpdateRamp?: (ramp: RampParam) => void;
     /**
      * @description.zh 更新定点清扫的回调
      * @description.en Callback when updating spot clean
@@ -1872,6 +1925,15 @@ export declare interface MapCallbacks {
      * @param.en threshold - Clicked threshold data
      */
     onClickThreshold?: (threshold: ThresholdParam) => void;
+    /**
+     * @description.zh 点击坡道回调
+     * @description.en Callback when clicking ramp
+     * @description.zh 点击坡道时触发。常用于「点击进入编辑」（把该 id 加入 editingRampIds）。
+     * @description.en Triggered when the user taps a ramp. Commonly used to enter edit mode (add the id to editingRampIds).
+     * @param.zh ramp - 被点击的坡道数据
+     * @param.en ramp - Clicked ramp data
+     */
+    onClickRamp?: (ramp: RampParam) => void;
     /**
      * @description.zh 点击定点清扫回调
      * @description.en Callback when clicking spot clean
@@ -2225,6 +2287,114 @@ export declare type ProcessedRasterData = {
     totalPixels: number
 }
 
+/** 坡道配置 */
+export declare type RampConfig = {
+    /** 底色（不透明 —— 坡道是地面元素，画在路径 / 机器人之下，见 ADR 0006） */
+    fillColor: ColorSource
+    /** 描边颜色 */
+    strokeColor: ColorSource
+    /** 描边线宽（屏幕像素，不随地图缩放） */
+    strokeWidth: number
+    /**
+     * 箭头颜色。默认白色 40% 透明叠在底色上（与 UED 稿一致）——
+     * 这样改 `fillColor` 时箭头会自动跟随，不用两处对着调。
+     */
+    arrowColor: ColorSource
+    /**
+     * 箭头**最小**线宽（屏幕像素，不随地图缩放）。
+     *
+     * 实际线宽取 `实际行距 × arrowThicknessRatio` 与本值中的较大者：正常缩放
+     * 下由比例决定（线与缝的粗细比恒定，观感等于 UED 稿），坡道小到 / 地图
+     * 缩到线要细过本值时由本值兜底，保证箭头不会细成看不见。
+     */
+    arrowThickness: number
+    /**
+     * 箭头线宽相对**实际行距**的比例，UED 稿量得 `3 / 7 ≈ 0.43`。
+     *
+     * 线宽跟着行距走而不是锁在固定像素：行距随坡道尺寸变化，若线宽不跟着长，
+     * 放大地图就会看到又粗又疏的缝里夹着细发丝一样的箭头。按比例算才能任何
+     * 缩放下都是同一张贴纸。
+     */
+    arrowThicknessRatio: number
+    /**
+     * 相邻箭头的**最小**间隙（屏幕像素），沿坡向度量。
+     *
+     * 最小步距 = `arrowThickness + arrowGap`，它是密度上限：箭头永远不会比这
+     * 更挤。地图缩得很小时它会顶掉 {@link RampConfig.arrowDensity} 算出的砖
+     * 尺寸，让砖变大、行数变少，保证箭头不会糊成一片。
+     */
+    arrowGap: number
+    /**
+     * 纹样密度：**短边**上铺几个箭头。UED 稿是方形坡道上 6 个，故默认 6。
+     *
+     * 箭头是一块比例固定的「砖」，而不是拉满坡道宽度的单根折线：砖的尺寸
+     * 取 `短边 / arrowDensity`，再沿坡向铺若干**行**、沿宽方向铺若干**列**。
+     * 因此任何宽高比的坡道看到的都是同一块砖，只是数量不同。
+     *
+     * 若改成「整宽一个箭头 + 固定行数」，折角深浅由宽决定、线宽由高决定，
+     * 两个特征分别挂在两条边上：窄高坡道会退化成胖带子（折角只有线宽的
+     * 1/7），宽矮坡道会退化成细丝配大折角。见 plan record
+     * `docs/records/plans/2026-08-06-ramp-map-element-plan.md`。
+     *
+     * 调小更稀、调大更密；密度还受最小步距 `arrowThickness + arrowGap` 约束。
+     */
+    arrowDensity: number
+    /**
+     * 箭头两臂相对横轴的抬升角度（度），钳制在 `[1, 60]`。
+     *
+     * **不是固定的外凸像素**：外凸量由 `半个砖宽 × tan(角度)` 反推，所以任何
+     * 坡道尺寸、任何地图缩放下箭头形状恒定。若改成固定像素，宽砖上的箭头会
+     * 被摊平成直线。UED 稿量得约 8.7°，默认取 9。
+     */
+    arrowAngle: number
+    /** 箭头区域相对坡道边缘的内缩（屏幕像素），箭头不贴边 */
+    arrowInset: number
+    /** 最小宽度 (米)，绘制与缩放时宽边（顶点 0→1）被钳制到不小于该值 */
+    minWidth: number
+    /** 最大宽度 (米)，可选。缺省或 ≤ minWidth 时不限制。 */
+    maxWidth?: number
+    /** 最小高度 (米)，绘制与缩放时高边（顶点 0→3）被钳制到不小于该值 */
+    minHeight: number
+    /** 最大高度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
+    maxHeight?: number
+    /** 四角控制按钮图标容器填充颜色（编辑态显示） */
+    iconWrapperFillColor: ColorSource
+    /** 编辑态轮廓相对坡道边缘的偏移（屏幕像素） */
+    outlineOffset: number
+    /** 编辑态轮廓描边颜色 */
+    outlineStrokeColor: ColorSource
+    /** 编辑态轮廓描边宽度 */
+    outlineStrokeWidth: number
+    /** 编辑态轮廓是否虚线 */
+    outlineDashed: boolean
+    /** 编辑态轮廓虚线数组 */
+    outlineDashArray: [number, number]
+    /** 编辑态轮廓填充颜色 */
+    outlineFillColor: ColorSource
+    /** 尺寸标签（宽×高）文本颜色（编辑态显示） */
+    textColor: ColorSource
+    /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
+    textOffset: number
+}
+
+/** 坡道参数 */
+export declare type RampParam = {
+    /** 坡道ID */
+    id: string
+    /**
+     * 四角坐标（地图像素坐标系），顺时针 左上→右上→右下→左下，与家具 /
+     * 禁区等四边形元素同序：顶点 0→1 为宽（w）方向，0→3 为高（h）方向。
+     *
+     * 坡道的上坡方向由点序自带：垂直于 0→1 边、从 3→2 边指向 0→1 边
+     * （未旋转时即"朝上"）。旋转时点集整体旋转，坡向随之旋转 —— 没有独立的
+     * direction 字段。因此点序**不做**长边规范（那会翻转坡向），入口只纠正
+     * 绕向为顺时针、把宽与高分别钳制到 `minWidth`/`maxWidth` 与
+     * `minHeight`/`maxHeight`（米）区间并拉直成标准矩形。`getRamps()` 回吐的
+     * 点集是归一化后的结果，不一定与传入的原始点逐字相同。
+     */
+    points: Point[]
+}
+
 /**
  * 栅格房间的美化几何（仅 `runtime.enableBeautify` 开启时由 MapManager 计算，
  * 随 `ProcessedRasterData` 一并交给渲染层）。
@@ -2478,6 +2648,14 @@ export declare type RuntimeConfig = {
      * 加入本列表即可。
      */
     editingThresholdIds: string[]
+    /**
+     * 正在编辑的坡道ID列表。
+     *
+     * 列入的坡道显示编辑控件（虚线轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动
+     * 按钮）并可整体拖拽；未列入的坡道不显示编辑控件，但坡道本身仍可点击
+     * （上抛 `onClickRamp`，宿主可借此实现「点击进入编辑」）。
+     */
+    editingRampIds: string[]
     /** 正在编辑的定点清扫ID列表 */
     editingSpotIds: string[]
     /** 正在编辑的房间锚点ID列表（独立于 editingSpotIds，互不影响） */
@@ -2928,3 +3106,19 @@ export declare type ZoneParam = {
 export declare type ZoneTypeDefinition = ZoneConfig
 
 export { }
+
+/**
+ * Minimal `node:fs` surface for the few tests that read source files off disk
+ * (structural invariants like `throttle-cancel-invariant.test.ts`).
+ *
+ * `@types/node` is installed but unreachable: `tsconfig.json` pins `typeRoots`
+ * to `./src/core/@types`, deliberately keeping Node globals out of a browser
+ * SDK's type surface. Shimming the three functions actually used is contained;
+ * widening `typeRoots` would put `process`, `Buffer` and friends in scope for
+ * every `src/` file, where they must never be used.
+ */
+declare module 'node:fs' {
+  export function readFileSync(path: string, encoding: 'utf8'): string
+  export function readdirSync(path: string): string[]
+  export function statSync(path: string): { isDirectory(): boolean }
+}