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

package/dist/index.d.ts

@@ -10,6 +10,32 @@ import { TextStyleFontWeight } from 'pixi.js';
  * 定义了视觉样式、素材资源、交互行为等一次性配置项
  */
 export declare type AppConfig = {
+    /**
+     * 弹性缩放的档位断点（全图共用）
+     *
+     * 屏幕固定尺寸的元素（房间属性气泡、检测物体图标等）默认在地图缩放时保持
+     * 恒定像素大小。弹性缩放在此之上叠一层分档倍数：地图缩到第一个断点以下时
+     * 元素略微变小，放大到最后一个断点以上时略微变大，中间保持原状。
+     *
+     * **断点全图共用，倍数各元素自己给**（见 `room.elasticFactors`、
+     * `detectedObject.elasticFactors`）。共用断点保证所有元素在同一刻切档，
+     * 否则捏合时气泡和图标会错开变化。
+     */
+    elasticScale: {
+        /**
+         * 档位断点，升序排列。`n` 个断点划出 `n + 1` 档。
+         *
+         * 边界归属**刻意不对称**：`s <= 断点[0]` 归最低档，`s >= 断点[末]` 归最高档，
+         * 恰好压在中间某个断点上归上一档。若把 `interaction.zoomRange.max` 设成正好
+         * 等于最末断点，捏到顶时会稳定落在最高档。
+         *
+         * 断点应落在 `interaction.zoomRange` 区间内，否则该档永不触发。
+         *
+         * @defaultValue [1, 5]
+         */
+        breakpoints: number[]
+    }
+
     /** 全局配置 */
     global: {
         /** 容器距离顶部位置 */
@@ -131,6 +157,13 @@ export declare type AppConfig = {
             inactive: string[]
             /** 普通状态颜色（非选择模式下使用） */
             normal?: string[]
+            /**
+             * 禁用状态（`runtime.disabledRoomIds` 列入的房间）填充色调色板，按四色
+             * 索引取用。填单个值即所有禁用房间共用一色；未配置或配置为空数组时回退
+             * 到该房间的 `inactive` 色。禁用态优先于选中态，且不受
+             * `enableRoomSelection` 影响。
+             */
+            disabled?: string[]
             /**
              * 美化外壳（Shell）填充色的显式覆盖调色板，按四色索引取用（可选）。
              * 未配置时外壳色由房间基础色向白色按 `map.beautify.shellLightenRatio`
@@ -259,6 +292,14 @@ export declare type AppConfig = {
                  * - 设置为 'auto' 时，文字颜色将自动跟随房间的 active 颜色
                  */
                 color: ColorSource | 'auto'
+                /**
+                 * 圆形序号背景色
+                 * - 设置为 'auto' 时，背景色跟随房间属性图标的主题色
+                 *   （`room.colors.propertyTheme` / `propertyThemeInactive` /
+                 *   `propertyThemeNormal` 三态）
+                 * - 设置为固定颜色后与图标颜色解绑，三态一并失效
+                 */
+                backgroundColor: ColorSource | 'auto'
                 /** 字体名称 */
                 fontFamily: string
                 /** 字体粗细 */
@@ -316,24 +357,33 @@ export declare type AppConfig = {
         /**
          * 是否启用 RoomInfo 弹性缩放
          *
-         * 启用后，RoomInfo 会根据地图缩放程度自动调整大小：
-         * - 地图缩小到一定程度时，缩小到 elasticMinScale
-         * - 正常缩放范围内，保持固定大小
-         * - 地图放大到一定程度时，放大到 elasticMaxScale
+         * 启用后，RoomInfo 会按 `elasticScale.breakpoints` 划出的档位调整大小：
+         * 地图缩到最低档时缩小、放大到最高档时放大、中间档保持固定大小。
          */
         enableElasticScale: boolean
         /**
-         * RoomInfo 最小弹性缩放倍数
+         * RoomInfo 最小弹性缩放倍数（最低档的倍数）
          *
-         * 当地图缩小到一定程度时，RoomInfo 会缩小到此倍数
+         * 与 `elasticMaxScale` 一起构成两档式的简写。要控制中间档或使用多于 3 档，
+         * 改用 `elasticFactors`。
          */
         elasticMinScale: number
         /**
-         * RoomInfo 最大弹性缩放倍数
+         * RoomInfo 最大弹性缩放倍数（最高档的倍数）
          *
-         * 当地图放大到一定程度时，RoomInfo 会放大到此倍数
+         * 与 `elasticMinScale` 一起构成两档式的简写。要控制中间档或使用多于 3 档，
+         * 改用 `elasticFactors`。
          */
         elasticMaxScale: number
+        /**
+         * RoomInfo 各档倍数，长度须等于 `elasticScale.breakpoints.length + 1`
+         *
+         * 给了它就以它为准，`elasticMinScale` / `elasticMaxScale` 不再参与。
+         * 不给则按 `[elasticMinScale, 1, ..., 1, elasticMaxScale]` 展开。
+         *
+         * 长度对不上会打 warn 并**整组降级为不启用**（退回纯反向缩放），不会自动补齐。
+         */
+        elasticFactors?: number[]
     }
 
     /** 路径配置 */
@@ -425,8 +475,6 @@ export declare type AppConfig = {
         // 地毯材质配置，针对地毯需要不同类型的填充材质的情况，比如羊毛地毯，长毛地毯等等
         // 优先级比src要高，非必要情况，非必要不要传递，使用src的配置即可
         material?: { type: number; src: string; opacity: number; scale: number }[]
-        // 地毯是否支持编辑，默认为false，非必要不要开启，会影响地毯绘制性能
-        enableEdit?: boolean
     }
 
     /** 机器人配置 */
@@ -581,6 +629,22 @@ export declare type AppConfig = {
          * - {x: 0.5, y: 1} 表示底部中心（适用于气泡图标）
          */
         anchor: Point
+        /**
+         * 是否启用检测物体图标的弹性缩放
+         *
+         * 启用后图标会按 `elasticScale.breakpoints` 划出的档位调整大小，
+         * 与房间属性气泡在同一刻切档。
+         */
+        enableElasticScale: boolean
+        /**
+         * 检测物体图标各档倍数，长度须等于 `elasticScale.breakpoints.length + 1`
+         *
+         * 倍数与房间属性分开配：图标是小方块、气泡是横向长条，同一个倍数在两者上的
+         * 视觉重量不同。倍数乘在最终尺寸上，含单条数据自带的 `width` / `height`。
+         *
+         * 长度对不上会打 warn 并**整组降级为不启用**（退回纯反向缩放），不会自动补齐。
+         */
+        elasticFactors: number[]
     }
 
     /** 截图配置 */
@@ -698,19 +762,21 @@ export declare type BaseCustomElementParam = {
 }
 
 /** 区域和地毯配置的基础类型 */
-export declare type BaseZoneConfig = {
+export declare type BaseZoneConfig = ZoneBodyStyle & {
     /** 最小尺寸 (米) */
     minSize: number
     /** 最大尺寸 (米)，可选。缺省或 ≤ minSize 时不限制。 */
     maxSize?: number
+    /**
+     * 区域框中心图标。缺省（`undefined`）时不创建任何 Sprite 子对象。
+     *
+     * 图标位置实时取四角点的中心（区域容器自身 `rotation` 恒为 0，旋转改的是
+     * 四角点），并在地图旋转时反向旋转保持水平；`eventMode` 恒为 `'none'`，
+     * 不会挡住区域的体拖拽与点击。
+     */
+    centerIcon?: ZoneCenterIconConfig
     /** 图标容器填充颜色 */
     iconWrapperFillColor: ColorSource
-    /** 描边颜色 */
-    strokeColor: ColorSource
-    /** 描边宽度 */
-    strokeWidth: number
-    /** 填充颜色 */
-    fillColor: ColorSource
     /** 轮廓偏移 */
     outlineOffset: number
     /** 轮廓描边颜色 */
@@ -725,12 +791,39 @@ export declare type BaseZoneConfig = {
     outlineDashArray: [number, number]
     /** 是否显示旋转图标 */
     showRotateButton: boolean
+    /**
+     * 是否显示删除按钮（编辑态）。缺省 `true`。
+     *
+     * 纯 UI 显隐，不是能力禁用——按钮隐藏后该按钮通道失效（PIXI 对
+     * `visible = false` 的对象跳过命中测试），但元素本体的交互不受影响。
+     */
+    showDeleteButton?: boolean
+    /**
+     * 是否显示缩放按钮（编辑态）。缺省 `true`。
+     *
+     * 对启用了纵横比锁定的地毯，横 / 纵向辅助缩放按钮随本开关一并隐藏。
+     */
+    showScaleButton?: boolean
+    /**
+     * 是否显示移动按钮（编辑态）。缺省 `true`。
+     *
+     * **不禁止平移**：区域本体的拖拽走独立的填充（ControlFill）通道，
+     * 隐藏移动按钮只是去掉按钮与它的延长线。
+     */
+    showMoveButton?: boolean
     /** 文本颜色 */
     textColor: ColorSource
     /** 文本位置 */
     textPosition: 'top' | 'right' | 'bottom' | 'left'
     /** 文本偏移 */
     textOffset: number
+    /**
+     * 禁用态样式覆盖块（`runtime.disabled*Ids` 列入的元素生效）。
+     *
+     * 缺省（`undefined`）时禁用态只叠加全局兜底透明度
+     * `controls.disabledStyle.opacity`，主体颜色不变。
+     */
+    disabled?: ZoneDisabledStyle
     /** 编辑模式样式 */
     editing: {
         /** 是否虚线 */
@@ -762,12 +855,19 @@ export declare type Bounds = {
 /** 地毯配置 */
 export declare type CarpetConfig = Omit<
 BaseZoneConfig,
-'strokeColor' | 'strokeWidth'
+'strokeColor' | 'strokeWidth' | 'disabled'
 > & {
     /** 删除图标容器填充颜色，缺省时回退到 iconWrapperFillColor */
     deleteIconWrapperFillColor?: ColorSource
     rotateMode: 'step' | 'free'
     scaleMode: 'free' | 'ratioLocked'
+    /**
+     * 禁用态样式覆盖块（`runtime.disabledCarpetIds` 列入的地毯生效）。
+     *
+     * 地毯主体是纹理贴图 + 体填充，没有描边与虚线，故白名单只有 `fillColor`。
+     * 缺省时禁用态只叠加全局兜底透明度 `controls.disabledStyle.opacity`。
+     */
+    disabled?: Partial<Pick<ZoneBodyStyle, 'fillColor'>> & DisabledStyleBase
 }
 
 /** 组件属性类型 */
@@ -832,6 +932,15 @@ export declare type ControlsConfig = {
     textFontWeight: TextStyleFontWeight
     /** 控制层内部渲染顺序（从下到上） */
     renderOrder: ControlRenderItem[]
+    /**
+     * 禁用态全局兜底样式，只有 `opacity`（唯一跨所有元素类型都成立的视觉
+     * 概念，默认 `0.4`）。各类型配置的 `disabled` 块按字段覆盖它；要改颜色
+     * 或虚线去类型级。
+     */
+    disabledStyle: {
+        /** 禁用态整体透明度（各类型 `disabled.opacity` 可覆盖） */
+        opacity: number
+    }
     /** 禁扫区域配置 */
     forbiddenSweepZone: ZoneConfig
     /** 禁拖区域配置 */
@@ -930,6 +1039,18 @@ export declare type DetectedObjectParam = {
 /** 方向 */
 export declare type Direction = 'horizontal' | 'vertical'
 
+/**
+ * 禁用态样式差量的公共部分。
+ *
+ * `opacity` 是唯一跨所有元素类型都成立的视觉概念：叠加在元素根容器上，
+ * 按 PIXI alpha 级联语义与子对象自身透明度相乘。缺省回退全局兜底
+ * `controls.disabledStyle.opacity`。
+ */
+export declare type DisabledStyleBase = {
+    /** 禁用态整体透明度，缺省回退 `controls.disabledStyle.opacity` */
+    opacity?: number
+}
+
 /** 分割线配置 */
 export declare type DividerConfig = {
     /** 线条颜色 */
@@ -940,8 +1061,10 @@ export declare type DividerConfig = {
     dashLineDashArray: [number, number]
     /** 实线线条宽度 */
     solidLineWidth: number
-    /** 端点大小 */
+    /** 端点大小（外接尺寸，菱形取对角线） */
     endPointSize: number
+    /** 端点形状 (默认 'circle')。'diamond' 会反向旋转以在地图旋转时保持正菱形 */
+    endPointShape: 'circle' | 'diamond'
     /** 端点颜色 */
     endPointColor: ColorSource
     /** 端点描边颜色 */
@@ -952,6 +1075,17 @@ export declare type DividerConfig = {
     hitAreaThickness: number
     /** 当分割线完全处在房间外的时候是否重置分割线 */
     resetDividerWhenOutOfRoom: boolean
+    /**
+     * 越界判据 (默认 'boundingBox')，同时决定 onDividerOutOfRoom 何时触发与
+     * resetDividerWhenOutOfRoom 何时把线拖回。
+     *
+     * - `'boundingBox'` 宽松：整条线段与房间包围盒完全不相交才算越界。
+     * - `'solidLine'` 严格：算不出有效实线（分割线切不动这个房间）即算越界，
+     *   按房间真实填充判定，端点被拖进房间内部同样算。
+     *
+     * 两者是包含关系——整条线跑出包围盒必然算不出实线，反之不然。
+     */
+    outOfRoomCriterion: 'boundingBox' | 'solidLine'
     /** 默认生成的分割线超出房间包围盒的像素值 */
     defaultExtension: number
     /** 默认生成的分割线方向 */
@@ -978,6 +1112,23 @@ export declare type FurnitureConfig = {
     opacity: number
     /** 图标容器填充颜色 */
     iconWrapperFillColor: ColorSource
+    /**
+     * 是否显示删除按钮（编辑态）。缺省 `true`。
+     *
+     * 纯 UI 显隐，不是能力禁用。
+     */
+    showDeleteButton?: boolean
+    /** 是否显示旋转按钮（编辑态）。缺省 `true`。 */
+    showRotateButton?: boolean
+    /** 是否显示缩放按钮（编辑态）。缺省 `true`。 */
+    showScaleButton?: boolean
+    /**
+     * 是否显示移动按钮（编辑态）。缺省 `true`。
+     *
+     * **不禁止平移**：本体拖拽走元素自身的命中区域，隐藏移动按钮只是去掉
+     * 按钮与它的延长线。
+     */
+    showMoveButton?: boolean
     /** 轮廓偏移 */
     outlineOffset: number
     /** 轮廓描边颜色 */
@@ -1006,6 +1157,13 @@ export declare type FurnitureConfig = {
     rotateDirection: 'cw' | 'ccw'
     /** 缩放时是否锁定宽高比 (默认 false) */
     lockAspectRatio: boolean
+    /**
+     * 禁用态样式覆盖块（`runtime.disabledFurnitureIds` 列入的家具生效）。
+     *
+     * 家具主体是纹理贴图，唯一有意义的视觉差量是透明度。禁用透明度叠加在
+     * 家具根容器上，与贴图自身的 `opacity` 相乘。
+     */
+    disabled?: DisabledStyleBase
 }
 
 /** 家具参数 */
@@ -1137,9 +1295,9 @@ export declare type LoggerPayload = {
     ts: number
 }
 
-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_API_METHODS: readonly ["areRoomsAdjacent", "getAdjacentRoomIds", "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", "setDisabledCustomZones"];
 
-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"];
+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", "onDividerOutOfRoom", "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 接口定义
@@ -1544,6 +1702,20 @@ export declare interface MapApi {
      * @returns 是否所有指定的房间都相邻（连通）
      */
     areRoomsAdjacent(roomIds: number[]): boolean;
+    /**
+     * 获取与指定房间相邻的房间 ID 列表
+     *
+     * 支持结构化地图和点阵地图两种协议。判定阈值与 `areRoomsAdjacent` 同为
+     * `config.map.adjacencyThreshold`，结论也一致——
+     * `getAdjacentRoomIds(a)` 含 `b` 等价于 `areRoomsAdjacent([a, b])` 为 true。
+     *
+     * 相邻表一次扫描算出：宿主要得到「与某房间不相邻的房间」（例如房间禁用态
+     * 需要的 `disabledRoomIds`），只需一次调用后取补集。
+     *
+     * @param roomId - 目标房间 ID
+     * @returns 相邻房间 ID 数组（按 ID 升序）；房间不存在或地图未就绪时返回空数组
+     */
+    getAdjacentRoomIds(roomId: number): number[];
     /**
      * 判断一个点是否与充电桩或机器人距离小于阈值。
      *
@@ -1979,6 +2151,15 @@ export declare interface MapCallbacks {
      * @param.en divider - Updated divider data
      */
     onUpdateDivider?: (divider: Point[]) => void;
+    /**
+     * @description.zh 分割线拖出房间回调
+     * @description.en Callback when the divider is dragged out of the room
+     * @description.zh 当用户操作分割线结束时，若整条线段与房间包围盒完全不相交则触发。回调携带的是重置前的点，即用户实际拖到的位置；开启 divider.resetDividerWhenOutOfRoom 时，重置后的位置随即由 onUpdateDivider 抛出。该回调只负责告知，与是否自动重置正交——关闭自动重置时同样触发。
+     * @description.en Triggered when a divider operation ends and the whole segment no longer intersects the room bounding box. The payload is the position before reset, i.e. where the user actually dragged it; when divider.resetDividerWhenOutOfRoom is enabled, the position after reset is reported right after by onUpdateDivider. This callback only reports the verdict and is orthogonal to the reset behavior - it fires even when auto reset is disabled.
+     * @param.zh divider - 重置前的分割线数据（用户实际拖到的位置）
+     * @param.en divider - Divider data before reset (where the user actually dragged it)
+     */
+    onDividerOutOfRoom?: (divider: Point[]) => void;
     /**
      * @description.zh 点击地图回调
      * @description.en Callback when clicking map
@@ -1991,8 +2172,8 @@ export declare interface MapCallbacks {
     /**
      * @description.zh 点击地毯回调
      * @description.en Callback when clicking carpet
-     * @description.zh 当用户点击地毯区域时触发（需要启用 carpet.enableEdit）。
-     * @description.en Triggered when user clicks carpet area (requires carpet.enableEdit to be enabled).
+     * @description.zh 当用户点击地毯区域时触发。
+     * @description.en Triggered when user clicks carpet area.
      * @param.zh carpet - 被点击的地毯信息
      * @param.en carpet - Clicked carpet information
      */
@@ -2359,6 +2540,23 @@ export declare type RampConfig = {
     maxHeight?: number
     /** 四角控制按钮图标容器填充颜色（编辑态显示） */
     iconWrapperFillColor: ColorSource
+    /**
+     * 是否显示删除按钮（编辑态）。缺省 `true`。
+     *
+     * 纯 UI 显隐，不是能力禁用。
+     */
+    showDeleteButton?: boolean
+    /** 是否显示旋转按钮（编辑态）。缺省 `true`。 */
+    showRotateButton?: boolean
+    /** 是否显示缩放按钮（编辑态）。缺省 `true`。 */
+    showScaleButton?: boolean
+    /**
+     * 是否显示移动按钮（编辑态）。缺省 `true`。
+     *
+     * **不禁止平移**：本体拖拽走元素自身的命中区域，隐藏移动按钮只是去掉
+     * 按钮与它的延长线。
+     */
+    showMoveButton?: boolean
     /** 编辑态轮廓相对坡道边缘的偏移（屏幕像素） */
     outlineOffset: number
     /** 编辑态轮廓描边颜色 */
@@ -2375,6 +2573,24 @@ export declare type RampConfig = {
     textColor: ColorSource
     /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
     textOffset: number
+    /**
+     * 禁用态样式覆盖块（`runtime.disabledRampIds` 列入的坡道生效）。
+     *
+     * 白名单只收空闲态真正渲染的坡道本体字段（底色、描边、箭头颜色）；
+     * `outline*` / 按钮 / 尺寸文本只在编辑态渲染，类型上不承诺覆盖。坡道
+     * 没有虚线渲染，故无虚线键。缺省时禁用态只叠加全局兜底透明度
+     * `controls.disabledStyle.opacity`。
+     */
+    disabled?: DisabledStyleBase & {
+        /** 禁用态底色 */
+        fillColor?: ColorSource
+        /** 禁用态描边颜色 */
+        strokeColor?: ColorSource
+        /** 禁用态描边线宽（屏幕像素） */
+        strokeWidth?: number
+        /** 禁用态箭头颜色 */
+        arrowColor?: ColorSource
+    }
 }
 
 /** 坡道参数 */
@@ -2682,6 +2898,13 @@ export declare type RuntimeConfig = {
     unitLabel: string
     /** 是否显示房间属性 */
     showRoomProperty: boolean
+    /**
+     * 是否显示房间属性的折叠指示器（折叠态的小三角）
+     *
+     * 只控制小三角画不画，不影响折叠能力本身：设为 false 后
+     * `roomPropertyFoldIds` 里的房间依旧折叠，只是折叠态完全不可见。
+     */
+    showRoomPropertyFoldIndicator: boolean
     /** 是否显示房间顺序 */
     showRoomOrder: boolean
     /** 是否显示路径 */
@@ -2702,6 +2925,55 @@ export declare type RuntimeConfig = {
     showCustomCarpets: boolean
     /** 选中的房间ID列表 */
     selectRoomIds: number[]
+    /**
+     * 禁用的房间ID列表
+     *
+     * 列入的房间填充为禁用色（`config.room.colors.disabled`），与
+     * `enableRoomSelection` 无关：不进选择模式也照样置灰。禁用优先于选中——
+     * 房间同时出现在 `selectRoomIds` 与本列表时渲染为禁用色（两个列表本应由
+     * 宿主保证互斥）。
+     *
+     * SDK 不拦截交互：禁用房间照常触发 `onClickRoom`，「点了不响应」由宿主在
+     * 回调里判断并 return。本期只作用于房间填充，房间名 / 属性气泡 / 选中指示器
+     * 不跟随。
+     */
+    disabledRoomIds: number[]
+    /**
+     * 禁用的禁扫区域ID列表。
+     *
+     * 与房间禁用（`disabledRoomIds`，只渲染不拦截）**同名不同义**：元素禁用
+     * 会拦截编辑手势（本体拖拽与删除 / 旋转 / 缩放 / 移动按钮全部失效，编辑
+     * 控件不渲染），但点击照常上抛 `onClick*`（宿主可借此弹「不可编辑」提示）。
+     * 视觉上按空闲态渲染并叠加禁用样式差量（`controls.disabledStyle` 全局
+     * 兜底 + 各类型 `disabled` 块覆盖）。禁用优先于编辑：元素同时出现在
+     * `editing*Ids` 与本列表时按禁用处理，也不会被升到本层顶部。取舍见
+     * ADR 0007；层级规则（编辑中的元素不被任何东西遮挡）见 ADR 0009。
+     *
+     * 以下 8 个 `disabled*Ids` 与 `disabledCustomZoneIds` 语义相同，不再逐个
+     * 复述。
+     */
+    disabledForbiddenSweepZoneIds: string[]
+    /** 禁用的禁拖区域ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledForbiddenMopZoneIds: string[]
+    /** 禁用的清洁区域ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledCleanZoneIds: string[]
+    /**
+     * Disabled ids for custom zone types, keyed by zone type. Built-in types
+     * use their own `disabled*ZoneIds` fields. Write through
+     * `setDisabledCustomZones()` — the runtime subscription compares this key's
+     * reference, so in-place nested writes never notify.
+     */
+    disabledCustomZoneIds?: Record<string, string[]>
+    /** 禁用的虚拟墙ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledVirtualWallIds: string[]
+    /** 禁用的门槛ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledThresholdIds: string[]
+    /** 禁用的坡道ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledRampIds: string[]
+    /** 禁用的地毯ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}；禁用同时压过 `selectedCarpetIds` 的选中框） */
+    disabledCarpetIds: string[]
+    /** 禁用的家具ID列表（语义见 {@link RuntimeConfig.disabledForbiddenSweepZoneIds}） */
+    disabledFurnitureIds: string[]
     /** 是否显示充电桩预警圈 */
     showChargingStationRing: boolean
     /** 是否显示机器人预警圈 */
@@ -2884,6 +3156,23 @@ export declare type ThresholdConfig = {
     maxHeight?: number
     /** 四角控制按钮图标容器填充颜色（编辑态显示） */
     iconWrapperFillColor: ColorSource
+    /**
+     * 是否显示删除按钮（编辑态）。缺省 `true`。
+     *
+     * 纯 UI 显隐，不是能力禁用。
+     */
+    showDeleteButton?: boolean
+    /** 是否显示旋转按钮（编辑态）。缺省 `true`。 */
+    showRotateButton?: boolean
+    /** 是否显示缩放按钮（编辑态）。缺省 `true`。 */
+    showScaleButton?: boolean
+    /**
+     * 是否显示移动按钮（编辑态）。缺省 `true`。
+     *
+     * **不禁止平移**：本体拖拽走元素自身的命中区域，隐藏移动按钮只是去掉
+     * 按钮与它的延长线。
+     */
+    showMoveButton?: boolean
     /**
      * 点击热区在条带每一侧向外扩展的可抓边距（屏幕像素，不随地图缩放）。
      * 热区厚度 = 条带高度 + 2 × 该值，因此条带无论多厚都保有固定的可抓边距，
@@ -2906,6 +3195,20 @@ export declare type ThresholdConfig = {
     textColor: ColorSource
     /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
     textOffset: number
+    /**
+     * 禁用态样式覆盖块（`runtime.disabledThresholdIds` 列入的门槛生效）。
+     *
+     * 门槛主体是斜纹条带，按通行类型分两套样式，禁用覆盖也按同一结构给：
+     * `passable` / `impassable` 各自可部分覆盖 {@link ThresholdStyle}。条带
+     * 没有虚线渲染，故无虚线键。缺省时禁用态只叠加全局兜底透明度
+     * `controls.disabledStyle.opacity`。
+     */
+    disabled?: DisabledStyleBase & {
+        /** 禁用态的可通行门槛样式覆盖 */
+        passable?: Partial<ThresholdStyle>
+        /** 禁用态的不可通行门槛样式覆盖 */
+        impassable?: Partial<ThresholdStyle>
+    }
 }
 
 /**
@@ -2956,13 +3259,42 @@ export declare type ThresholdStyle = {
 export declare type ThresholdType = 'passable' | 'impassable'
 
 /** 虚拟墙配置 */
-export declare type VirtualWallConfig = {
-    /** 图标容器填充颜色 */
-    iconWrapperFillColor: ColorSource
+/**
+ * 虚拟墙主体绘制样式 —— 空闲态真正渲染的部分（墙体线段）。
+ * 单独成型是为了让禁用态覆盖块（{@link VirtualWallDisabledStyle}）与本体
+ * 字段同源派生，不会漂移。
+ */
+export declare type VirtualWallBodyStyle = {
     /** 线条宽度 */
     lineWidth: number
     /** 线条颜色 */
     lineColor: ColorSource
+}
+
+export declare type VirtualWallConfig = VirtualWallBodyStyle & {
+    /** 图标容器填充颜色 */
+    iconWrapperFillColor: ColorSource
+    /**
+     * 是否显示删除按钮（编辑态）。缺省 `true`。
+     *
+     * 纯 UI 显隐，不是能力禁用。
+     */
+    showDeleteButton?: boolean
+    /**
+     * 是否显示缩放按钮（编辑态）。缺省 `true`。
+     *
+     * 虚拟墙的这颗按钮是**缩放 + 旋转二合一**（拖动同时改长度与朝向，绕固定
+     * 起点旋转），隐藏它等于同时关掉这两个通道。虚拟墙没有独立的旋转按钮，
+     * 因而不支持 `showRotateButton`。
+     */
+    showScaleButton?: boolean
+    /**
+     * 是否显示移动按钮（编辑态）。缺省 `true`。
+     *
+     * **不禁止平移**：墙体本体的拖拽走线段自身的命中区域，隐藏移动按钮只是
+     * 去掉按钮与它的延长线。
+     */
+    showMoveButton?: boolean
     /** 碰撞区域厚度 */
     hitAreaThickness: number
     /** 轮廓偏移 */
@@ -2985,6 +3317,13 @@ export declare type VirtualWallConfig = {
     minWidth: number
     /** 最大宽度 (米)，可选。缺省或 ≤ minWidth 时不限制。 */
     maxWidth?: number
+    /**
+     * 禁用态样式覆盖块（`runtime.disabledVirtualWallIds` 列入的虚拟墙生效）。
+     *
+     * 缺省（`undefined`）时禁用态只叠加全局兜底透明度
+     * `controls.disabledStyle.opacity`，墙体颜色不变。
+     */
+    disabled?: VirtualWallDisabledStyle
 
     /** 编辑模式样式 */
     editing: {
@@ -3002,6 +3341,21 @@ export declare type VirtualWallConfig = {
     }
 }
 
+/**
+ * 虚拟墙禁用态样式覆盖块。
+ *
+ * 白名单只收空闲态真正渲染的墙体线段字段；`outline*` / 按钮 / 长度文本
+ * 只在编辑态渲染，禁用态按空闲切片显示，类型上不承诺覆盖它们。虚线两键
+ * 覆盖墙体线段的虚实，缺省回退 `normal` 块。
+ */
+export declare type VirtualWallDisabledStyle = Partial<VirtualWallBodyStyle> &
+DisabledStyleBase & {
+    /** 禁用态墙体是否虚线，缺省回退 `normal.isDashed` */
+    isDashed?: boolean
+    /** 禁用态墙体虚线数组，缺省回退 `normal.dashArray` */
+    dashArray?: [number, number]
+}
+
 /** 虚拟墙参数 */
 export declare type VirtualWallParam = {
     /** 虚拟墙ID */
@@ -3082,9 +3436,69 @@ export declare type WayPointParam = {
     point: Point
 }
 
+/**
+ * Zone 主体绘制样式 —— 空闲态真正渲染的部分（体填充与内框描边）。
+ * 单独成型是为了让禁用态覆盖块（{@link ZoneDisabledStyle}）与本体字段
+ * 同源派生，不会漂移。
+ */
+export declare type ZoneBodyStyle = {
+    /** 描边颜色 */
+    strokeColor: ColorSource
+    /** 描边宽度 */
+    strokeWidth: number
+    /** 填充颜色 */
+    fillColor: ColorSource
+}
+
+/**
+ * 区域中心图标配置（类型级粒度：同一区域类型的所有实例共用一个图标）。
+ *
+ * 字段口径对齐 {@link SpotConfig} 的 `iconSrc` / `iconSize` / `iconSizeFixed` /
+ * `iconAnchor` 与其 `editing.showIcon` / `normal.showIcon`。
+ */
+export declare type ZoneCenterIconConfig = {
+    /** 图标资源路径 */
+    src: string
+    /** 图标大小（sizeFixed 时为屏幕像素，否则为地图像素），默认 24 */
+    size?: number
+    /** 图标尺寸是否固定（不跟随地图缩放），默认 true */
+    sizeFixed?: boolean
+    /** 图标锚点（x/y 取同一值），0 为左上、0.5 为居中、1 为右下，默认 0.5 */
+    anchor?: number
+    /** 图标不透明度，默认 1 */
+    opacity?: number
+    /** 编辑态是否显示图标，默认 true */
+    showInEditing?: boolean
+    /** 普通态是否显示图标，默认 true */
+    showInNormal?: boolean
+    /**
+     * 禁用态是否显示图标，缺省回退 `showInNormal`。
+     *
+     * 禁用元素整体变淡时，一枚淡化的类型图标（如禁扫区的禁止标）可能被读成
+     * 「这条规则失效了」——语义含混时用本开关把它藏掉。
+     */
+    showInDisabled?: boolean
+}
+
 /** 区域配置 */
 export declare type ZoneConfig = BaseZoneConfig
 
+/**
+ * 区域禁用态样式覆盖块。
+ *
+ * 白名单只收空闲态真正渲染的主体绘制字段——`outline*` / 按钮 / 尺寸文本
+ * 只在编辑态渲染，而禁用态按空闲切片显示，覆盖它们不会产生任何效果，
+ * 因此类型上不承诺。虚线两键覆盖内框（zoneBorder）的虚实，缺省回退
+ * `normal` 块。
+ */
+export declare type ZoneDisabledStyle = Partial<ZoneBodyStyle> &
+DisabledStyleBase & {
+    /** 禁用态内框是否虚线，缺省回退 `normal.isDashed` */
+    isDashed?: boolean
+    /** 禁用态内框虚线数组，缺省回退 `normal.dashArray` */
+    dashArray?: [number, number]
+}
+
 /** 区域参数 */
 export declare type ZoneParam = {
     /** 区域ID */