@pisell/materials 6.11.42 → 6.11.44

package/es/components/pisellFloorMapLayout/components/ViewControls.js

@@ -15,7 +15,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
  */
 import React, { useState, useRef, useEffect, useCallback } from 'react';
 import classNames from 'classnames';
-import { MinusOutlined, PlusOutlined, FullscreenOutlined, FullscreenExitOutlined, BorderInnerOutlined, LeftOutlined, RightOutlined, ReloadOutlined, ExpandOutlined } from '@ant-design/icons';
+import { MinusOutlined, PlusOutlined, FullscreenOutlined, FullscreenExitOutlined, BorderInnerOutlined, LeftOutlined, RightOutlined, ReloadOutlined, ExpandOutlined, LockOutlined, UnlockOutlined } from '@ant-design/icons';
 import { locales } from '@pisell/utils';
 import "./ViewControls.less";
 var PREFIX = 'pisell-floor-map-layout';
@@ -32,10 +32,15 @@ export function ViewControls(props) {
     scale = _props$scale === void 0 ? 1 : _props$scale,
     _props$isFullscreen = props.isFullscreen,
     isFullscreen = _props$isFullscreen === void 0 ? false : _props$isFullscreen,
+    _props$fitBoundsActiv = props.fitBoundsActive,
+    fitBoundsActive = _props$fitBoundsActiv === void 0 ? false : _props$fitBoundsActiv,
     className = props.className,
     _props$mapGridVisible = props.mapGridVisible,
     mapGridVisible = _props$mapGridVisible === void 0 ? false : _props$mapGridVisible,
     onToggleMapGrid = props.onToggleMapGrid,
+    _props$viewportLocked = props.viewportLocked,
+    viewportLocked = _props$viewportLocked === void 0 ? false : _props$viewportLocked,
+    onToggleViewportLock = props.onToggleViewportLock,
     _props$dockChrome = props.dockChrome,
     dockChrome = _props$dockChrome === void 0 ? false : _props$dockChrome,
     dockExpandedTrailing = props.dockExpandedTrailing,
@@ -46,11 +51,12 @@ export function ViewControls(props) {
   var showFitBounds = config.showFitBounds === true;
   var showFullscreen = config.showFullscreen === true;
   var showGridToggle = config.showGridToggle === true && typeof onToggleMapGrid === 'function';
+  var showViewportLock = config.showViewportLock === true && typeof onToggleViewportLock === 'function';
   var horizontalAlign = (_config$horizontalAli = config.horizontalAlign) !== null && _config$horizontalAli !== void 0 ? _config$horizontalAli : 'start';
   /** 右下 Dock：`row-reverse` 后入口在屏缘右侧，箭头与左下镜像（展开朝内左、收起朝外右） */
   var isDockAlignEnd = horizontalAlign === 'end';
   var scalePercent = Math.round(scale * 100);
-  var showTools = showReset || showFitBounds || showFullscreen || showGridToggle;
+  var showTools = showReset || showFitBounds || showFullscreen || showGridToggle || showViewportLock;
   var hasTrailingSlot = dockExpandedTrailing != null && dockExpandedTrailing !== false;
   var dockHasExpandable = dockChrome && (showTools || hasTrailingSlot);
   var showBar = showZoom || showTools || dockChrome && hasTrailingSlot;
@@ -119,20 +125,32 @@ export function ViewControls(props) {
       scheduleDockCollapse();
     }
   }, [dockExpanded, autoCollapseDockMs, scheduleDockCollapse]);
-  var renderToolButtons = function renderToolButtons() {
+
+  /**
+   * 右下 Dock（align-end）收起态已在 `dock-collapsed-extras` 暴露锁 / 全览，
+   * 展开后 extras 仍贴边可见，展开条内不再重复渲染这两项。
+   */
+  var renderToolButtons = function renderToolButtons(opts) {
+    var omitLock = (opts === null || opts === void 0 ? void 0 : opts.omitViewportLock) === true;
+    var omitFit = (opts === null || opts === void 0 ? void 0 : opts.omitFitBounds) === true;
     return /*#__PURE__*/React.createElement(React.Fragment, null, showReset ? /*#__PURE__*/React.createElement("button", {
       type: "button",
       className: "".concat(PREFIX, "-view-controls-tool-btn"),
       onClick: function onClick() {
         return api.resetTransform();
       },
+      disabled: viewportLocked,
+      "aria-disabled": viewportLocked,
       "aria-label": locales.getText("".concat(I18N_VC, ".reset-aria"))
-    }, /*#__PURE__*/React.createElement(ReloadOutlined, null)) : null, showFitBounds && api.fitBounds ? /*#__PURE__*/React.createElement("button", {
+    }, /*#__PURE__*/React.createElement(ReloadOutlined, null)) : null, showFitBounds && api.fitBounds && !omitFit ? /*#__PURE__*/React.createElement("button", {
       type: "button",
-      className: "".concat(PREFIX, "-view-controls-tool-btn"),
+      className: classNames("".concat(PREFIX, "-view-controls-tool-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-tool-btn--active"), fitBoundsActive && !viewportLocked)),
       onClick: function onClick() {
         return api.fitBounds();
       },
+      disabled: viewportLocked,
+      "aria-disabled": viewportLocked,
+      "aria-pressed": fitBoundsActive,
       "aria-label": locales.getText("".concat(I18N_VC, ".fit-bounds-aria"))
     }, /*#__PURE__*/React.createElement(ExpandOutlined, null)) : null, showGridToggle ? /*#__PURE__*/React.createElement("button", {
       type: "button",
@@ -142,15 +160,28 @@ export function ViewControls(props) {
       },
       "aria-pressed": mapGridVisible,
       "aria-label": locales.getText(mapGridVisible ? "".concat(I18N_VC, ".grid-hide-aria") : "".concat(I18N_VC, ".grid-show-aria"))
-    }, /*#__PURE__*/React.createElement(BorderInnerOutlined, null)) : null, showFullscreen && api.toggleFullscreen ? /*#__PURE__*/React.createElement("button", {
+    }, /*#__PURE__*/React.createElement(BorderInnerOutlined, null)) : null, showViewportLock && !omitLock ? /*#__PURE__*/React.createElement("button", {
       type: "button",
-      className: "".concat(PREFIX, "-view-controls-tool-btn"),
+      className: classNames("".concat(PREFIX, "-view-controls-tool-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-tool-btn--active"), viewportLocked)),
+      onClick: function onClick() {
+        return onToggleViewportLock();
+      },
+      "aria-pressed": viewportLocked,
+      "aria-label": locales.getText(viewportLocked ? "".concat(I18N_VC, ".viewport-unlock-aria") : "".concat(I18N_VC, ".viewport-lock-aria")),
+      title: locales.getText(viewportLocked ? "".concat(I18N_VC, ".viewport-unlock-aria") : "".concat(I18N_VC, ".viewport-lock-aria"))
+    }, viewportLocked ? /*#__PURE__*/React.createElement(LockOutlined, null) : /*#__PURE__*/React.createElement(UnlockOutlined, null)) : null, showFullscreen && api.toggleFullscreen ? /*#__PURE__*/React.createElement("button", {
+      type: "button",
+      className: classNames("".concat(PREFIX, "-view-controls-tool-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-tool-btn--active"), isFullscreen)),
       onClick: function onClick() {
         return api.toggleFullscreen();
       },
+      "aria-pressed": isFullscreen,
       "aria-label": locales.getText(isFullscreen ? "".concat(I18N_VC, ".fullscreen-exit-aria") : "".concat(I18N_VC, ".fullscreen-aria"))
     }, isFullscreen ? /*#__PURE__*/React.createElement(FullscreenExitOutlined, null) : /*#__PURE__*/React.createElement(FullscreenOutlined, null)) : null);
   };
+
+  /** Dock 展开条内是否还有「工具区」按钮（排除已在收起条 mirror 的锁 / 全览） */
+  var dockExpandedBarHasToolButtons = showReset || showFitBounds && Boolean(api.fitBounds) && !isDockAlignEnd || showGridToggle || showViewportLock && !isDockAlignEnd || showFullscreen && Boolean(api.toggleFullscreen);
   var renderDockExpandableBarContents = function renderDockExpandableBarContents() {
     return /*#__PURE__*/React.createElement(React.Fragment, null, showZoom ? /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
       type: "button",
@@ -158,6 +189,8 @@ export function ViewControls(props) {
       onClick: function onClick() {
         return api.zoomOut();
       },
+      disabled: viewportLocked,
+      "aria-disabled": viewportLocked,
       "aria-label": locales.getText("".concat(I18N_VC, ".zoom-out-aria"))
     }, /*#__PURE__*/React.createElement(MinusOutlined, null)), /*#__PURE__*/React.createElement("span", {
       className: "".concat(PREFIX, "-view-controls-zoom-value")
@@ -167,11 +200,16 @@ export function ViewControls(props) {
       onClick: function onClick() {
         return api.zoomIn();
       },
+      disabled: viewportLocked,
+      "aria-disabled": viewportLocked,
       "aria-label": locales.getText("".concat(I18N_VC, ".zoom-in-aria"))
-    }, /*#__PURE__*/React.createElement(PlusOutlined, null))) : null, showZoom && (showTools || hasTrailingSlot) ? /*#__PURE__*/React.createElement("div", {
+    }, /*#__PURE__*/React.createElement(PlusOutlined, null))) : null, showZoom && (dockExpandedBarHasToolButtons || hasTrailingSlot) ? /*#__PURE__*/React.createElement("div", {
       className: "".concat(PREFIX, "-view-controls-bar-divider"),
       "aria-hidden": true
-    }) : null, showTools ? renderToolButtons() : null, hasTrailingSlot ? /*#__PURE__*/React.createElement("div", {
+    }) : null, dockExpandedBarHasToolButtons ? renderToolButtons({
+      omitViewportLock: isDockAlignEnd,
+      omitFitBounds: isDockAlignEnd
+    }) : null, hasTrailingSlot ? /*#__PURE__*/React.createElement("div", {
       className: "".concat(PREFIX, "-view-controls-dock-trailing")
     }, dockExpandedTrailing) : null, /*#__PURE__*/React.createElement("button", {
       type: "button",
@@ -184,12 +222,54 @@ export function ViewControls(props) {
   if (!showBar) {
     return null;
   }
-  if (dockChrome && dockHasExpandable) {
+
+  /**
+   * Dock 收起态额外暴露的高频按钮（不必先展开就能点）。
+   * 当前包含「视口锁定」「适配视口（全览）」——两者都是单击操作，不依赖展开条里的状态展示。
+   * 展开时这块和 expand-btn 一起 width→0 收掉，让位给 dock-slide。
+   */
+  var renderDockCollapsedExtras = function renderDockCollapsedExtras() {
+    var showLockChip = showViewportLock;
+    var showFitChip = showFitBounds && Boolean(api.fitBounds);
+    if (!showLockChip && !showFitChip) return null;
+    /**
+     * align-end（画布右下 dock）下 extras 与 expand-btn / slide 做"连体"，
+     * 展开态仍贴右缘可见，因此不参与 panel-open 收起，也保持可聚焦/无 aria-hidden。
+     */
+    var collapseExtras = dockExpanded && !isDockAlignEnd;
     return /*#__PURE__*/React.createElement("div", {
+      className: classNames("".concat(PREFIX, "-view-controls-dock-collapsed-extras"), _defineProperty({}, "".concat(PREFIX, "-view-controls-dock-collapsed-extras--panel-open"), collapseExtras)),
+      "aria-hidden": collapseExtras
+    }, showLockChip ? /*#__PURE__*/React.createElement("button", {
+      type: "button",
+      className: classNames("".concat(PREFIX, "-view-controls-tool-btn"), "".concat(PREFIX, "-view-controls-dock-collapsed-extras-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-tool-btn--active"), viewportLocked)),
+      onClick: function onClick() {
+        return onToggleViewportLock();
+      },
+      tabIndex: collapseExtras ? -1 : 0,
+      "aria-pressed": viewportLocked,
+      "aria-label": locales.getText(viewportLocked ? "".concat(I18N_VC, ".viewport-unlock-aria") : "".concat(I18N_VC, ".viewport-lock-aria")),
+      title: locales.getText(viewportLocked ? "".concat(I18N_VC, ".viewport-unlock-aria") : "".concat(I18N_VC, ".viewport-lock-aria"))
+    }, viewportLocked ? /*#__PURE__*/React.createElement(LockOutlined, null) : /*#__PURE__*/React.createElement(UnlockOutlined, null)) : null, showFitChip ? /*#__PURE__*/React.createElement("button", {
+      type: "button",
+      className: classNames("".concat(PREFIX, "-view-controls-tool-btn"), "".concat(PREFIX, "-view-controls-dock-collapsed-extras-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-tool-btn--active"), fitBoundsActive && !viewportLocked)),
+      onClick: function onClick() {
+        return api.fitBounds();
+      },
+      disabled: viewportLocked,
+      "aria-disabled": viewportLocked,
+      "aria-pressed": fitBoundsActive,
+      tabIndex: collapseExtras ? -1 : 0,
+      "aria-label": locales.getText("".concat(I18N_VC, ".fit-bounds-aria")),
+      title: locales.getText("".concat(I18N_VC, ".fit-bounds-aria"))
+    }, /*#__PURE__*/React.createElement(ExpandOutlined, null)) : null);
+  };
+  if (dockChrome && dockHasExpandable) {
+    return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("div", {
       className: classNames("".concat(PREFIX, "-view-controls"), "".concat(PREFIX, "-view-controls--dock"), horizontalAlign === 'end' && "".concat(PREFIX, "-view-controls--align-end"), className)
     }, /*#__PURE__*/React.createElement("div", {
       className: "".concat(PREFIX, "-view-controls-dock-row")
-    }, /*#__PURE__*/React.createElement("button", {
+    }, renderDockCollapsedExtras(), /*#__PURE__*/React.createElement("button", {
       type: "button",
       className: classNames("".concat(PREFIX, "-view-controls-dock-expand-btn"), _defineProperty({}, "".concat(PREFIX, "-view-controls-dock-expand-btn--panel-open"), dockExpanded)),
       onClick: handleDockExpand,
@@ -204,7 +284,7 @@ export function ViewControls(props) {
       className: classNames("".concat(PREFIX, "-view-controls-bar"), "".concat(PREFIX, "-view-controls-bar--dock")),
       role: "group",
       onPointerDown: handleDockBarPointerDown
-    }, renderDockExpandableBarContents())) : null));
+    }, renderDockExpandableBarContents())) : null)));
   }
   var barClass = classNames("".concat(PREFIX, "-view-controls-bar"), _defineProperty({}, "".concat(PREFIX, "-view-controls-bar--dock"), dockChrome));
   return /*#__PURE__*/React.createElement("div", {
@@ -219,6 +299,8 @@ export function ViewControls(props) {
     onClick: function onClick() {
       return api.zoomOut();
     },
+    disabled: viewportLocked,
+    "aria-disabled": viewportLocked,
     "aria-label": locales.getText("".concat(I18N_VC, ".zoom-out-aria"))
   }, /*#__PURE__*/React.createElement(MinusOutlined, null)), /*#__PURE__*/React.createElement("span", {
     className: "".concat(PREFIX, "-view-controls-zoom-value")
@@ -228,6 +310,8 @@ export function ViewControls(props) {
     onClick: function onClick() {
       return api.zoomIn();
     },
+    disabled: viewportLocked,
+    "aria-disabled": viewportLocked,
     "aria-label": locales.getText("".concat(I18N_VC, ".zoom-in-aria"))
   }, /*#__PURE__*/React.createElement(PlusOutlined, null))) : null, !dockChrome && showTools ? /*#__PURE__*/React.createElement(React.Fragment, null, showZoom ? /*#__PURE__*/React.createElement("div", {
     className: "".concat(PREFIX, "-view-controls-bar-divider"),

package/es/components/pisellFloorMapLayout/components/ViewControls.less

@@ -111,23 +111,60 @@
       background: #f2f4f7;
       color: #101828;
     }
+
+    /**
+     * 视口锁定时：zoom +/- / reset / fit-bounds 等改变视角的按钮 disabled。
+     * 给出灰态 + 禁用 hover 反馈，避免点击但实际拒绝带来的迷惑感。
+     */
+    &:disabled,
+    &[aria-disabled='true'] {
+      cursor: not-allowed;
+      color: #d0d5dd;
+      background: transparent;
+    }
+
+    &:disabled:hover,
+    &[aria-disabled='true']:hover {
+      background: transparent;
+      color: #d0d5dd;
+    }
   }
 
-  &-bar > &-tool-btn--active {
-    background: #fff4ed;
-    color: #ff692e;
+  /**
+   * 工具按钮激活态（展开条内与外侧折叠 pill 共用同一套色值）。
+   * 主色链：`--color-primary`（与主色展开键、业务 HUD 一致）→ `--fmap-primary`（PisellFloorMapLayout 注入）
+   * → 兜底 #1677ff。淡底用 color-mix 12%/18% hover。
+   */
+  .vc-tool-btn-active-colors() {
+    @vc-p: var(--color-primary, var(--fmap-primary, #1677ff));
+
+    background: color-mix(in srgb, @vc-p 12%, #fff);
+    color: @vc-p;
 
     &:hover {
-      background: #ffe8d9;
-      color: #ff692e;
+      background: color-mix(in srgb, @vc-p 18%, #fff);
+      color: @vc-p;
+    }
+
+    &:disabled,
+    &[aria-disabled='true'] {
+      background: transparent;
+      color: #d0d5dd;
     }
   }
 
+  &-bar > &-tool-btn--active,
+  &-dock-collapsed-extras > &-tool-btn--active {
+    .vc-tool-btn-active-colors();
+  }
+
   /* —— 平面图 Dock：折叠入口与展开横条共用同一外框高度，避免切换时跳动 —— */
   @dock-btn-size: 42px;
   @dock-icon-px: 18px;
   /** 折叠按钮正方形边长 = 展开条高度（含 1px 边框的 border-box） */
   @dock-chrome-outer: 56px;
+  /** Dock 展开/收起：与 slide、expand、extras 共用，linear 避免 ease 带来的「回弹」观感 */
+  @dock-slide-ms: 0.18s;
 
   &--dock {
     left: 14px;
@@ -153,9 +190,9 @@
     }
 
     /**
-     * 展开/收起：max-width 过渡（变长 / 变短），内层 bar 为 width:max-content
+     * 展开/收起：max-width 过渡（变长 / 变短），内层 bar 为 width:max-content。
+     * 使用 linear + 统一时长（@dock-slide-ms），避免 ease 曲线与 max-width「大数值」组合带来的回弹感。
      */
-
     .pisell-floor-map-layout-view-controls-dock-slide {
       box-sizing: border-box;
       max-width: 0;
@@ -164,7 +201,7 @@
       display: flex;
       flex-direction: row;
       align-items: center;
-      transition: max-width 0.32s cubic-bezier(0.22, 1, 0.36, 1);
+      transition: max-width @dock-slide-ms linear;
     }
 
     .pisell-floor-map-layout-view-controls-dock-slide--open {
@@ -220,6 +257,14 @@
       }
     }
 
+    /**
+     * 展开条内激活态：与外侧折叠 pill（锁定 / 全览）同一套色，选择器挂在 bar--dock 上提高优先级，
+     * 避免与其它 hover / 尺寸规则叠在一起时展开条观感发灰、与 pill 不一致。
+     */
+    .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-tool-btn--active {
+      .vc-tool-btn-active-colors();
+    }
+
     .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-zoom-value {
       min-width: 50px;
       height: @dock-btn-size;
@@ -245,24 +290,30 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    border: 1px solid #e8eaed;
+    border: 1px solid transparent;
     border-radius: 14px;
-    background: #fff;
-    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+    /**
+     * 主题色背景：与左下「Today sales」chip 同步走 antd primary 变量；
+     * 兜底 #5d3f9f 跟随项目其它主色 token，主题改色时自动同步。
+     * 边框透明保留圆角，避免主题色与浅灰描边混色。
+     */
+    background: var(--color-primary, var(--ant-color-primary, #5d3f9f));
+    box-shadow: 0 4px 16px rgba(15, 23, 42, 0.22);
     cursor: pointer;
-    color: #101828;
+    color: #fff;
     font-size: @dock-icon-px;
     line-height: 0;
     appearance: none;
     flex-shrink: 0;
     overflow: hidden;
-    transition: width 0.32s cubic-bezier(0.22, 1, 0.36, 1),
-    min-width 0.32s cubic-bezier(0.22, 1, 0.36, 1),
-    max-width 0.32s cubic-bezier(0.22, 1, 0.36, 1),
-    opacity 0.22s ease,
-    border-color 0.22s ease,
-    box-shadow 0.22s ease,
-    margin 0.32s cubic-bezier(0.22, 1, 0.36, 1);
+    transition: width @dock-slide-ms linear,
+      min-width @dock-slide-ms linear,
+      max-width @dock-slide-ms linear,
+      opacity @dock-slide-ms linear,
+      border-color @dock-slide-ms linear,
+      box-shadow @dock-slide-ms linear,
+      filter @dock-slide-ms linear,
+      margin @dock-slide-ms linear;
 
     /** 与右侧条带同时：条带变长时入口收起为 0 宽；收起条带时入口从 0 拉回到正方形 */
 
@@ -279,7 +330,8 @@
     }
 
     &:hover {
-      background: #f9fafb;
+      /** 与 Today chip 一致：主题色上用 brightness 让 hover 永远比静态色暗一档 */
+      filter: brightness(0.92);
     }
 
     .anticon {
@@ -297,6 +349,156 @@
     }
   }
 
+  /**
+   * Dock 收起态额外按钮 pill：
+   * - 折叠时 DOM 在 expand-btn 之前（屏缘一侧），与展开入口并排；
+   * - dockExpanded 时与 expand-btn 同步 width→0、opacity→0，让位给 dock-slide 横向展开；
+   * - 默认 align（左下）：extras 在左缘，用 margin-right:8px 与 expand-btn 留缝；
+   * - align-end（右下）row-reverse 后 extras 贴右缘，用 margin-left:8px 与左侧 expand 留缝。
+   */
+  &-dock-collapsed-extras {
+    box-sizing: border-box;
+    height: @dock-chrome-outer;
+    min-height: @dock-chrome-outer;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 5px;
+    padding: 0 10px;
+    margin-right: 8px;
+    border: 1px solid #e8eaed;
+    border-radius: 14px;
+    background: #fff;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+    flex-shrink: 0;
+    overflow: hidden;
+    transition: max-width @dock-slide-ms linear,
+      opacity @dock-slide-ms linear,
+      border-color @dock-slide-ms linear,
+      box-shadow @dock-slide-ms linear,
+      margin @dock-slide-ms linear,
+      padding @dock-slide-ms linear;
+    max-width: 240px;
+  }
+
+  /**
+   * 右下 dock：row-reverse 后 DOM [extras][expand][slide] 呈 [slide][expand][extras]，
+   * extras 贴右缘。本场景下整组按钮做成「连体 pill」：
+   *
+   *   - 折叠态视觉：[紫色 expand-btn][锁定/全览 extras]
+   *   - 展开态视觉：[slide-bar 工具条][锁定/全览 extras]
+   *   - 展开方向：slide max-width 由 0 → 720px，由于父级锚定 `right:14px`，
+   *     整组横向"从右往左"伸长，视觉上工具条从 extras 左侧扩出来。
+   *
+   * 实现方式：把 box-shadow / border / border-radius 统一挂到外层 `dock-row` 容器上，
+   * 内层 slide-bar / expand-btn / extras 全部去掉自己的边框圆角与投影，
+   * 由 `overflow: hidden` 的外壳负责整体裁剪。这样：
+   *   - 整组只有一道阴影，无相邻拼接处的接缝阴影；
+   *   - 子元素切换宽度（max-width / width）时阴影边界跟随容器自然增长，无需 clip-path 修补；
+   *   - 紫色 expand-btn / 白色 extras / 白色 slide-bar 在同一个外壳里平铺，自动呈现连体观感。
+   */
+  &--align-end .pisell-floor-map-layout-view-controls-dock-row {
+    border: 1px solid #e8eaed;
+    border-radius: 14px;
+    background: #fff;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+    overflow: hidden;
+    /** 容器高度对齐 chrome 高度，避免子元素 1px 边框被外壳 border 双层叠加 */
+    height: @dock-chrome-outer;
+    min-height: @dock-chrome-outer;
+    max-height: @dock-chrome-outer;
+  }
+
+  /** 内层 slide-bar：去掉自身边框圆角阴影，背景仍为白以承接 zoom / 工具按钮 */
+  &--align-end
+    .pisell-floor-map-layout-view-controls-dock-slide
+    .pisell-floor-map-layout-view-controls-bar--dock {
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+    /** 高度由外壳决定，自身按外壳内填满 */
+    height: 100%;
+    min-height: 0 !important;
+    max-height: none !important;
+    /**
+     * 贴邻 extras 那一侧（DOM 内的右侧）padding 清零，避免与 extras 左 padding 叠加成接缝空隙；
+     * 外壳左侧（slide-bar 视觉左缘）保留 12px，与外壳圆角留出呼吸空间。
+     */
+    padding-right: 0;
+  }
+
+  /** 紫色入口：去掉自身投影圆角与边框，仅保留紫色底色，由外壳裁出连体圆角 */
+  &--align-end &-dock-expand-btn {
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+  }
+
+  /**
+   * 锁定 / 全览 extras：去掉自身边框圆角阴影与外边距，背景仍为白，贴外壳右缘排布；
+   * 贴邻 slide-bar / expand-btn 那一侧（DOM 内的左侧）padding 清零，避免接缝空隙。
+   */
+  &--align-end &-dock-collapsed-extras {
+    margin: 0;
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+    padding-left: 0;
+  }
+
+  /** 展开态保留 extras 显示在右侧（覆盖通用 panel-open 的收起规则） */
+  &--align-end &-dock-collapsed-extras--panel-open {
+    max-width: 240px;
+    margin: 0;
+    padding: 0 10px 0 0;
+    opacity: 1;
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+    pointer-events: auto;
+  }
+
+  &-dock-collapsed-extras-btn {
+    width: @dock-btn-size;
+    min-width: @dock-btn-size;
+    max-width: @dock-btn-size;
+    height: @dock-btn-size;
+    min-height: @dock-btn-size !important;
+    max-height: @dock-btn-size !important;
+    border-radius: 8px;
+    font-size: @dock-icon-px;
+    line-height: 0;
+
+    .anticon,
+    .pisell-lowcode-icon,
+    span[role='img'] {
+      font-size: @dock-icon-px !important;
+      line-height: 0;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .anticon svg,
+    .pisell-lowcode-icon svg,
+    span[role='img'] svg {
+      width: @dock-icon-px !important;
+      height: @dock-icon-px !important;
+      display: block;
+    }
+  }
+
+  &-dock-collapsed-extras--panel-open {
+    max-width: 0;
+    margin-left: 0;
+    margin-right: 0;
+    padding: 0;
+    opacity: 0;
+    border-color: transparent;
+    box-shadow: none;
+    pointer-events: none;
+  }
+
   &-dock-trailing {
     display: inline-flex;
     align-items: center;
@@ -319,7 +521,8 @@
 
 @media (prefers-reduced-motion: reduce) {
   .pisell-floor-map-layout-view-controls--dock .pisell-floor-map-layout-view-controls-dock-slide,
-  .pisell-floor-map-layout-view-controls--dock .pisell-floor-map-layout-view-controls-dock-expand-btn {
+  .pisell-floor-map-layout-view-controls--dock .pisell-floor-map-layout-view-controls-dock-expand-btn,
+  .pisell-floor-map-layout-view-controls--dock .pisell-floor-map-layout-view-controls-dock-collapsed-extras {
     transition-duration: 0.01ms;
   }
 }

package/es/components/pisellFloorMapLayout/components/ViewControlsWithZoom.d.ts

@@ -7,11 +7,17 @@ export interface ViewControlsWithZoomProps {
     config?: FloorMapControlsConfig;
     scale?: number;
     isFullscreen?: boolean;
+    /** 当前 transform 是否吻合「适配视口」结果，用于按钮激活态 */
+    fitBoundsActive?: boolean;
     fitBounds: () => void;
     /** 未传时不展示全屏按钮（如编辑态 floorMapFullscreenMode 为 disabled） */
     toggleFullscreen?: () => void;
     mapGridVisible?: boolean;
     onToggleMapGrid?: () => void;
+    /** 视口锁定态（true 时所有视角写入入口被禁用） */
+    viewportLocked?: boolean;
+    /** 切换视口锁定；未传时不展示锁定按钮 */
+    onToggleViewportLock?: () => void;
     dockChrome?: boolean;
     dockExpandedTrailing?: React.ReactNode;
     autoCollapseDockMs?: number;

package/es/components/pisellFloorMapLayout/components/ViewControlsWithZoom.js

@@ -23,8 +23,11 @@ export function ViewControlsWithZoom(props) {
     config: props.config,
     scale: props.scale,
     isFullscreen: props.isFullscreen,
+    fitBoundsActive: props.fitBoundsActive,
     mapGridVisible: props.mapGridVisible,
     onToggleMapGrid: props.onToggleMapGrid,
+    viewportLocked: props.viewportLocked,
+    onToggleViewportLock: props.onToggleViewportLock,
     dockChrome: props.dockChrome,
     dockExpandedTrailing: props.dockExpandedTrailing,
     autoCollapseDockMs: props.autoCollapseDockMs

package/es/components/pisellFloorMapLayout/floorMapLayoutConstants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 平面图布局根节点 BEM 前缀，与 `PisellFloorMapLayout.less` 中主 class 一致。
+ */
+export declare const FLOOR_MAP_LAYOUT_CLASS_PREFIX = "pisell-floor-map-layout";

package/es/components/pisellFloorMapLayout/floorMapLayoutConstants.js

@@ -0,0 +1,4 @@
+/**
+ * 平面图布局根节点 BEM 前缀，与 `PisellFloorMapLayout.less` 中主 class 一致。
+ */
+export var FLOOR_MAP_LAYOUT_CLASS_PREFIX = 'pisell-floor-map-layout';

package/es/components/pisellFloorMapLayout/hooks/floorMapViewportPersistence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 平面图视口缓存：localStorage 读写、锁定态；供 useFloorMapTransformMetrics 使用。
+ */
+/** 平面图包围盒单侧默认外扩（像素）；过大会导致首屏大量空白 */
+export declare const DEFAULT_BOUNDING_PADDING = 56;
+/** 视口内与首屏对齐时，图元束左上与容器边缘的留白 */
+export declare const VIEWPORT_TOP_LEFT_MARGIN = 16;
+/** 平面图视口（缩放 + 平移）持久化到 localStorage 的 key 前缀 */
+export declare const VIEWPORT_STORAGE_PREFIX = "pisell-floor-map-layout.viewport:";
+/** 视口锁定态持久化前缀（与视口位置分开存储） */
+export declare const VIEWPORT_LOCK_STORAGE_PREFIX = "pisell-floor-map-layout.viewport-lock:";
+/** 视口持久化写入节流（避免拖动 / 缩放过程中高频写 localStorage） */
+export declare const VIEWPORT_PERSIST_DEBOUNCE_MS = 300;
+/** 判定当前 transform 是否处于「适配视口」结果时的容差 */
+export declare const FIT_BOUNDS_MATCH_POS_EPSILON = 0.5;
+export declare const FIT_BOUNDS_MATCH_SCALE_EPSILON = 0.005;
+export interface ViewportSnapshot {
+    x: number;
+    y: number;
+    scale: number;
+}
+export declare function readPersistedViewport(key: string): ViewportSnapshot | null;
+export declare function writePersistedViewport(key: string, snapshot: ViewportSnapshot): void;
+export declare function readPersistedViewportLock(key: string): boolean;
+export declare function writePersistedViewportLock(key: string, locked: boolean): void;