@pisell/materials 1.8.20 → 1.8.21

package/es/components/pisellFloorMapLayout/hooks/useFloorMapEditState.js

@@ -2,15 +2,15 @@ function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" ==
 var _excluded = ["x", "y", "zIndex", "width", "height"];
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
-function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
-function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
-function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
 function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
 function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
@@ -28,14 +28,39 @@ import { createTranslationText } from "../../translation/utils";
 import { mergeCanvasItems } from "../utils/floorMapConfigMerge";
 import { STAGE_DECO_DEFAULT } from "../utils/floorMapStageDefaults";
 import { floorMapViewConfigsEqual, normalizeFloorMapViewConfigFromProp } from "../utils/floorMapViewConfigDiff";
-import { getElementKindConfig, resolveDataBindingPolicy } from "../utils/floorMapElementKindUtils";
+import { getElementKindConfig, resolveDataBindingPolicy, isFloorMapImageElementKind } from "../utils/floorMapElementKindUtils";
 import { DEFAULT_CELL_SIZE } from "../utils/layoutMeasurements";
 import { initFloorMapLayoutLocales } from "../utils/floorMapCanvasDisplay";
-import { FLOOR_MAP_IMAGE_ELEMENT_KIND, FLOOR_MAP_STAGE_ELEMENT_KIND } from "../types";
+import { FLOOR_MAP_STAGE_ELEMENT_KIND } from "../types";
 var IMAGE_PLACE_DEFAULT = {
   width: 400,
   height: 240
 };
+var GRID_VIS_STORAGE_PREFIX = 'pisell-floor-map-layout.grid-visible';
+function getGridVisStorageKey(canvasId) {
+  return "".concat(GRID_VIS_STORAGE_PREFIX, ":").concat(canvasId);
+}
+function readStoredGridVisible(canvasId) {
+  try {
+    var raw = localStorage.getItem(getGridVisStorageKey(canvasId));
+    if (raw == null) return null;
+    if (raw === '1') return true;
+    if (raw === '0') return false;
+    return null;
+  } catch (_unused) {
+    return null;
+  }
+}
+function writeStoredGridVisible(canvasId, visible) {
+  try {
+    localStorage.setItem(getGridVisStorageKey(canvasId), visible ? '1' : '0');
+  } catch (_unused2) {
+    // ignore localStorage failure (private mode / quota / sandbox)
+  }
+}
+
+/** 批量落位时每条相对上一条的偏移（内容坐标） */
+var BATCH_PLACE_OFFSET = 16;
 function newInstanceId() {
   return "elm_".concat(Date.now(), "_").concat(Math.random().toString(36).slice(2, 9));
 }
@@ -58,7 +83,8 @@ export function useFloorMapEditState(params) {
     dataSourceRecordForm = params.dataSourceRecordForm,
     dataSourceLabels = params.dataSourceLabels,
     layoutPrefix = params.layoutPrefix,
-    contentOffsetRef = params.contentOffsetRef;
+    contentOffsetRef = params.contentOffsetRef,
+    showDataSourceRecordFormBlock = params.showDataSourceRecordFormBlock;
   var engineCtx = useEngineContext();
   var engineLocale = (engineCtx === null || engineCtx === void 0 || (_engineCtx$engine = engineCtx.engine) === null || _engineCtx$engine === void 0 || (_engineCtx$engine = _engineCtx$engine.props) === null || _engineCtx$engine === void 0 ? void 0 : _engineCtx$engine.locale) || 'zh-CN';
   var _useState = useState(null),
@@ -85,13 +111,36 @@ export function useFloorMapEditState(params) {
     _useState12 = _slicedToArray(_useState11, 2),
     savingRecord = _useState12[0],
     setSavingRecord = _useState12[1];
+  /**
+   * 本地“已提交保存”的基线快照：
+   * - 点击「完成编辑/保存」后立即置为当前 draft，避免等待上游 props 回写期间仍显示“未持久化”提示；
+   * - 用户后续再改动 draft 时，dirty 会再次为 true。
+   */
+  var _useState13 = useState(null),
+    _useState14 = _slicedToArray(_useState13, 2),
+    savedBaselineConfig = _useState14[0],
+    setSavedBaselineConfig = _useState14[1];
   var config = isFloorMapView ? draftConfig !== null && draftConfig !== void 0 ? draftConfig : floorMapConfigProp : null;
   var configRef = useRef(config);
   configRef.current = config;
   useEffect(function () {
     if (!floorMapConfigProp) return;
-    var nextConfig = normalizeFloorMapViewConfigFromProp(floorMapConfigProp);
+    var baseConfig = normalizeFloorMapViewConfigFromProp(floorMapConfigProp);
+    var nextConfig = _objectSpread(_objectSpread({}, baseConfig), {}, {
+      canvases: baseConfig.canvases.map(function (canvas) {
+        var _canvas$mapLayer;
+        var stored = readStoredGridVisible(canvas.id);
+        if (stored == null) return canvas;
+        return _objectSpread(_objectSpread({}, canvas), {}, {
+          mapLayer: _objectSpread(_objectSpread({}, (_canvas$mapLayer = canvas.mapLayer) !== null && _canvas$mapLayer !== void 0 ? _canvas$mapLayer : {}), {}, {
+            showGrid: stored
+          })
+        });
+      })
+    });
     setDraftConfig(nextConfig);
+    /** 上游配置已刷新，以服务端/父级为准，清空本地临时保存基线 */
+    setSavedBaselineConfig(null);
     var enabled = nextConfig.canvases.filter(function (c) {
       return c.enabled;
     }).sort(function (a, b) {
@@ -108,9 +157,9 @@ export function useFloorMapEditState(params) {
   /** 当前草稿与上游持久化 `floorMapConfig`（经同等规范化）是否不一致 */
   var isLayoutDirty = useMemo(function () {
     if (!isFloorMapView || !draftConfig || !floorMapConfigProp) return false;
-    var baseline = normalizeFloorMapViewConfigFromProp(floorMapConfigProp);
+    var baseline = savedBaselineConfig !== null && savedBaselineConfig !== void 0 ? savedBaselineConfig : normalizeFloorMapViewConfigFromProp(floorMapConfigProp);
     return !floorMapViewConfigsEqual(draftConfig, baseline);
-  }, [isFloorMapView, draftConfig, floorMapConfigProp]);
+  }, [isFloorMapView, draftConfig, floorMapConfigProp, savedBaselineConfig]);
   var handleAddCanvas = useCallback(function () {
     initFloorMapLayoutLocales(engineLocale);
     var label = locales.getText('pisell-floor-map-layout.canvas-tabs.default-new-canvas-name');
@@ -241,7 +290,7 @@ export function useFloorMapEditState(params) {
   var placeOverlayClass = "".concat(layoutPrefix, "-place-overlay");
 
   /**
-   * 在内容坐标系下按「新建图元」模式落一条 sceneElement（点击落点与侧栏拖拽共用）
+   * 在内容坐标系下按「新建图元」模式落 sceneElement（支持 recordIds 批量；点击与拖拽共用）
    * @returns 是否已成功写入草稿（校验失败时为 false）
    */
   var applyScenePlacementAtCoords = useCallback(function (contentX, contentY, scene) {
@@ -257,6 +306,29 @@ export function useFloorMapEditState(params) {
       return allKeys.includes(k);
     }) : allKeys;
     var pickKey = (_ref = (_scene$dataSourceKey = scene.dataSourceKey) !== null && _scene$dataSourceKey !== void 0 ? _scene$dataSourceKey : allowedKeys[0]) !== null && _ref !== void 0 ? _ref : allKeys[0];
+    var recordIdsToPlace = scene.recordIds && scene.recordIds.length > 0 ? scene.recordIds : scene.recordId ? [scene.recordId] : [];
+    var isStage = scene.elementKind === FLOOR_MAP_STAGE_ELEMENT_KIND;
+    var isImage = isFloorMapImageElementKind(scene.elementKind);
+    var w = isImage ? IMAGE_PLACE_DEFAULT.width : isStage ? STAGE_DECO_DEFAULT.width : defaultPlacementWidth;
+    var h = isImage ? IMAGE_PLACE_DEFAULT.height : isStage ? STAGE_DECO_DEFAULT.height : defaultPlacementHeight;
+    var useDecoSize = policy === 'none' && scene.elementKind !== FLOOR_MAP_STAGE_ELEMENT_KIND && !isImage;
+    var buildOneElement = function buildOneElement(dataBinding, x, y, name) {
+      return _objectSpread({
+        instanceId: newInstanceId(),
+        canvasId: currentCanvasId,
+        x: x,
+        y: y,
+        name: name,
+        zIndex: isImage ? -5 : 0,
+        width: useDecoSize ? defaultDecoSize : w,
+        height: useDecoSize ? defaultDecoSize : h,
+        elementKind: scene.elementKind,
+        shape: isStage || isImage ? 'rect' : kindConfig === null || kindConfig === void 0 ? void 0 : kindConfig.defaultShape,
+        dataBinding: dataBinding
+      }, isImage ? {
+        imageUrl: ''
+      } : {});
+    };
     var dataBinding;
     if (policy !== 'none' && pickKey) {
       var _dataSources$pickKey;
@@ -266,14 +338,15 @@ export function useFloorMapEditState(params) {
           dataSourceKey: pickKey,
           recordId: "new_".concat(Date.now())
         };
-      } else if (!scene.recordId) {
+      } else if (recordIdsToPlace.length === 0) {
         if (policy === 'required') {
           message.warning('请先在侧栏选择数据源与数据行，再落位');
           return false;
         }
-      } else {
+      } else if (recordIdsToPlace.length === 1) {
+        var rid = recordIdsToPlace[0];
         var record = dsList.find(function (r) {
-          return r.id === scene.recordId;
+          return r.id === rid;
         });
         if (!record) {
           message.error('所选记录不存在，请重新选择数据行');
@@ -281,52 +354,80 @@ export function useFloorMapEditState(params) {
         }
         var cand = {
           dataSourceKey: pickKey,
-          recordId: scene.recordId
+          recordId: rid
         };
         if (duplicateBinding(config.sceneElements, cand)) {
           message.warning('该数据记录已在平面图中绑定，请勿重复添加');
           return false;
         }
         dataBinding = cand;
+      } else {
+        var newEls = [];
+        var skippedDup = 0;
+        var skippedMissing = 0;
+        var placeIndex = 0;
+        var seenInBatch = new Set();
+        recordIdsToPlace.forEach(function (rid) {
+          var _row$name;
+          var record = dsList.find(function (r) {
+            return r.id === rid;
+          });
+          if (!record) {
+            skippedMissing += 1;
+            return;
+          }
+          var cand = {
+            dataSourceKey: pickKey,
+            recordId: rid
+          };
+          if (seenInBatch.has(rid) || duplicateBinding(config.sceneElements, cand)) {
+            skippedDup += 1;
+            return;
+          }
+          seenInBatch.add(rid);
+          var row = record;
+          var placementName = String((_row$name = row === null || row === void 0 ? void 0 : row.name) !== null && _row$name !== void 0 ? _row$name : rid);
+          newEls.push(buildOneElement(cand, contentX + placeIndex * BATCH_PLACE_OFFSET, contentY + placeIndex * BATCH_PLACE_OFFSET, placementName));
+          placeIndex += 1;
+        });
+        if (skippedDup > 0) {
+          message.warning("\u5DF2\u8DF3\u8FC7 ".concat(skippedDup, " \u6761\u5DF2\u5728\u5E73\u9762\u56FE\u4E2D\u7ED1\u5B9A\u7684\u8BB0\u5F55"));
+        }
+        if (skippedMissing > 0) {
+          message.warning("\u6709 ".concat(skippedMissing, " \u6761\u8BB0\u5F55\u4E0D\u5B58\u5728\uFF0C\u5DF2\u8DF3\u8FC7"));
+        }
+        if (newEls.length === 0) {
+          message.warning('没有可落位的记录');
+          return false;
+        }
+        setDraftConfig(function (prev) {
+          var _prev$sceneElements4;
+          return prev ? _objectSpread(_objectSpread({}, prev), {}, {
+            sceneElements: [].concat(_toConsumableArray((_prev$sceneElements4 = prev.sceneElements) !== null && _prev$sceneElements4 !== void 0 ? _prev$sceneElements4 : []), newEls)
+          }) : prev;
+        });
+        return true;
       }
     }
-    var isStage = scene.elementKind === FLOOR_MAP_STAGE_ELEMENT_KIND;
-    var isImage = scene.elementKind === FLOOR_MAP_IMAGE_ELEMENT_KIND;
-    var w = isImage ? IMAGE_PLACE_DEFAULT.width : isStage ? STAGE_DECO_DEFAULT.width : defaultPlacementWidth;
-    var h = isImage ? IMAGE_PLACE_DEFAULT.height : isStage ? STAGE_DECO_DEFAULT.height : defaultPlacementHeight;
-    var useDecoSize = policy === 'none' && scene.elementKind !== FLOOR_MAP_STAGE_ELEMENT_KIND && !isImage;
     var placementName = function (_kindConfig$defaultPr, _kindConfig$defaultPr2) {
       if (isStage) return STAGE_DECO_DEFAULT.name;
       if (isImage) return '底图';
       var db = dataBinding;
-      if (db && scene.recordId) {
-        var _dataSources$db$dataS, _row$name;
+      var rid = recordIdsToPlace[0];
+      if (db && rid) {
+        var _dataSources$db$dataS, _row$name2;
         var row = dataSources === null || dataSources === void 0 || (_dataSources$db$dataS = dataSources[db.dataSourceKey]) === null || _dataSources$db$dataS === void 0 ? void 0 : _dataSources$db$dataS.find(function (r) {
-          return r.id === db.recordId;
+          return r.id === rid;
         });
-        return String((_row$name = row === null || row === void 0 ? void 0 : row.name) !== null && _row$name !== void 0 ? _row$name : db.recordId);
+        return String((_row$name2 = row === null || row === void 0 ? void 0 : row.name) !== null && _row$name2 !== void 0 ? _row$name2 : rid);
       }
       return (_kindConfig$defaultPr = kindConfig === null || kindConfig === void 0 || (_kindConfig$defaultPr2 = kindConfig.defaultPresentation) === null || _kindConfig$defaultPr2 === void 0 ? void 0 : _kindConfig$defaultPr2.title) !== null && _kindConfig$defaultPr !== void 0 ? _kindConfig$defaultPr : '';
     }();
-    var newEl = _objectSpread({
-      instanceId: newInstanceId(),
-      canvasId: currentCanvasId,
-      x: contentX,
-      y: contentY,
-      name: placementName,
-      zIndex: isImage ? -5 : 0,
-      width: useDecoSize ? defaultDecoSize : w,
-      height: useDecoSize ? defaultDecoSize : h,
-      elementKind: scene.elementKind,
-      shape: isStage || isImage ? 'rect' : kindConfig === null || kindConfig === void 0 ? void 0 : kindConfig.defaultShape,
-      dataBinding: dataBinding
-    }, isImage ? {
-      imageUrl: ''
-    } : {});
+    var newEl = buildOneElement(dataBinding, contentX, contentY, placementName);
     setDraftConfig(function (prev) {
-      var _prev$sceneElements4;
+      var _prev$sceneElements5;
       return prev ? _objectSpread(_objectSpread({}, prev), {}, {
-        sceneElements: [].concat(_toConsumableArray((_prev$sceneElements4 = prev.sceneElements) !== null && _prev$sceneElements4 !== void 0 ? _prev$sceneElements4 : []), [newEl])
+        sceneElements: [].concat(_toConsumableArray((_prev$sceneElements5 = prev.sceneElements) !== null && _prev$sceneElements5 !== void 0 ? _prev$sceneElements5 : []), [newEl])
       }) : prev;
     });
     return true;
@@ -356,10 +457,32 @@ export function useFloorMapEditState(params) {
     setSaving(true);
     try {
       onSave(draftConfig);
+      /** 先本地确认“已提交保存”，让提示即时消失；后续以 props 回写为准 */
+      setSavedBaselineConfig(draftConfig);
     } finally {
       setSaving(false);
     }
   }, [draftConfig, onSave]);
+
+  /** 切换当前画布草稿中的 mapLayer.showGrid（随布局保存持久化） */
+  var toggleDraftCanvasShowGrid = useCallback(function () {
+    setDraftConfig(function (prev) {
+      if (!prev || !currentCanvasId) return prev;
+      return _objectSpread(_objectSpread({}, prev), {}, {
+        canvases: prev.canvases.map(function (c) {
+          var _c$mapLayer;
+          if (c.id !== currentCanvasId) return c;
+          var nextShow = !Boolean((_c$mapLayer = c.mapLayer) === null || _c$mapLayer === void 0 ? void 0 : _c$mapLayer.showGrid);
+          writeStoredGridVisible(currentCanvasId, nextShow);
+          return _objectSpread(_objectSpread({}, c), {}, {
+            mapLayer: _objectSpread(_objectSpread({}, c.mapLayer), {}, {
+              showGrid: nextShow
+            })
+          });
+        })
+      });
+    });
+  }, [currentCanvasId]);
   var handleEditPanelUpdate = useCallback(function (patch) {
     if (!selectedId) return;
     var bindingPatch = patch.dataBinding;
@@ -383,10 +506,10 @@ export function useFloorMapEditState(params) {
   var handleEditPanelDelete = useCallback(function () {
     if (!selectedId) return;
     setDraftConfig(function (prev) {
-      var _prev$sceneElements5;
+      var _prev$sceneElements6;
       if (!prev) return prev;
       return _objectSpread(_objectSpread({}, prev), {}, {
-        sceneElements: ((_prev$sceneElements5 = prev.sceneElements) !== null && _prev$sceneElements5 !== void 0 ? _prev$sceneElements5 : []).filter(function (e) {
+        sceneElements: ((_prev$sceneElements6 = prev.sceneElements) !== null && _prev$sceneElements6 !== void 0 ? _prev$sceneElements6 : []).filter(function (e) {
           return e.instanceId !== selectedId;
         })
       });
@@ -408,7 +531,8 @@ export function useFloorMapEditState(params) {
     recordFormColumns: dataSourceFormColumns,
     dataSourceRecordForm: dataSourceRecordForm,
     dataSourceLabels: dataSourceLabels,
-    layoutDraftDirty: isLayoutDirty
+    layoutDraftDirty: isLayoutDirty,
+    showDataSourceRecordFormBlock: showDataSourceRecordFormBlock
   } : null;
   return {
     config: config,
@@ -431,6 +555,7 @@ export function useFloorMapEditState(params) {
     placeSceneElementFromPaletteDrop: placeSceneElementFromPaletteDrop,
     editPanelParams: editPanelParams,
     placeOverlayClass: placeOverlayClass,
-    isLayoutDirty: isLayoutDirty
+    isLayoutDirty: isLayoutDirty,
+    toggleDraftCanvasShowGrid: toggleDraftCanvasShowGrid
   };
 }

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

@@ -56,7 +56,7 @@ export declare function useFloorMapTransformMetrics<T extends FloorMapItemBase>(
     setScale: import("react").Dispatch<import("react").SetStateAction<number>>;
     isFullscreen: boolean;
     toggleFullscreen: () => void;
-    fitBounds: () => void;
+    fitBounds: () => boolean;
     lastTransformRef: MutableRefObject<{
         x: number;
         y: number;

package/es/components/pisellFloorMapLayout/hooks/useFloorMapTransformMetrics.js

@@ -13,7 +13,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 /**
  * 视口 / 地图区尺寸、内容区宽高与偏移、缩放与全屏、fitBounds、拖拽图元后恢复 transform
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { getContentSize, getPixelBoundingBox } from "../utils/layoutMeasurements";
 
 /** 平面图包围盒单侧默认外扩（像素）；过大会导致首屏大量空白 */
@@ -89,6 +89,9 @@ export function useFloorMapTransformMetrics(params) {
       return ro.disconnect();
     };
   }, []);
+
+  /** 默认开启：有空图元时首屏 fit 全图；仅 `autoFitOnMount: false` 关闭 */
+  var autoFitOnMount = zoom.autoFitOnMount !== false;
   var zoomConfig = useMemo(function () {
     var _zoom$defaultScale, _zoom$min, _zoom$max, _zoom$step;
     return {
@@ -172,6 +175,10 @@ export function useFloorMapTransformMetrics(params) {
         done: false
       };
     }
+    if (autoFitOnMount) {
+      initialAlignRef.current.done = true;
+      return;
+    }
     if (alignPadSingle == null) {
       initialAlignRef.current.done = false;
       return;
@@ -194,7 +201,7 @@ export function useFloorMapTransformMetrics(params) {
       cancelled = true;
       cancelAnimationFrame(raf);
     };
-  }, [isFloorMapView, frameResetKey, alignPadSingle, initialPositionX, initialPositionY, zoomConfig.initialScale, transformRef]);
+  }, [isFloorMapView, frameResetKey, alignPadSingle, initialPositionX, initialPositionY, zoomConfig.initialScale, transformRef, autoFitOnMount]);
   useEffect(function () {
     var el = containerRef.current;
     if (!el) return;
@@ -217,20 +224,131 @@ export function useFloorMapTransformMetrics(params) {
       (_el$requestFullscreen = el.requestFullscreen) === null || _el$requestFullscreen === void 0 || _el$requestFullscreen.call(el);
     }
   }, []);
+
+  /** @returns 是否已调用 setTransform（用于首屏 autoFit：避免空跑仍标记 done） */
   var fitBounds = useCallback(function () {
-    var _zoom$max2;
+    var _zoom$max3;
     var ctx = transformRef.current;
     var container = containerRef.current;
-    if (!ctx || !container) return;
+    if (!ctx || !container) return false;
     var wrapper = container.querySelector('.react-transform-wrapper');
-    if (!wrapper) return;
+    if (!wrapper) return false;
     var wrapperRect = wrapper.getBoundingClientRect();
-    var nextScale = Math.min(wrapperRect.width / contentWidth, wrapperRect.height / contentHeight, (_zoom$max2 = zoom.max) !== null && _zoom$max2 !== void 0 ? _zoom$max2 : 2);
+    if (wrapperRect.width <= 0 || wrapperRect.height <= 0) return false;
+
+    /**
+     * 平面图像素模式：按「图元轴对齐包围盒」缩放并居中，不按整块 content（含编辑态撑满视口的空白）适配。
+     * 画布 DOM 尺寸与网格空白不变，仅改变视口 transform；视口边可贴边（edgePx=0）。
+     */
+    var pixelBox = isFloorMapView && effectiveItemUnit === 'pixel' && items.length > 0 ? getPixelBoundingBox(items, cellSize) : null;
+    if (pixelBox) {
+      var _zoom$max2;
+      var bw = Math.max(1, pixelBox.maxRight - pixelBox.minLeft);
+      var bh = Math.max(1, pixelBox.maxBottom - pixelBox.minTop);
+      var edgePx = 0;
+      var availW = Math.max(1, wrapperRect.width - 2 * edgePx);
+      var availH = Math.max(1, wrapperRect.height - 2 * edgePx);
+      var _raw = Math.min(availW / bw, availH / bh);
+      var _nextScale = Math.min(_raw, (_zoom$max2 = zoom.max) !== null && _zoom$max2 !== void 0 ? _zoom$max2 : 2);
+      var ap = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : padSingle;
+      var bboxCx = ap + bw / 2;
+      var bboxCy = ap + bh / 2;
+      var _x = wrapperRect.width / 2 - bboxCx * _nextScale;
+      var _y = wrapperRect.height / 2 - bboxCy * _nextScale;
+      ctx.setTransform(_x, _y, _nextScale);
+      return true;
+    }
+    if (contentWidth <= 0 || contentHeight <= 0) return false;
+    /** 非平面图或无图元：仍按整块 content 适配 */
+    var raw = Math.min(wrapperRect.width / contentWidth, wrapperRect.height / contentHeight);
+    var nextScale = Math.min(raw, (_zoom$max3 = zoom.max) !== null && _zoom$max3 !== void 0 ? _zoom$max3 : 2);
     var padA = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : 0;
     var x = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
     var y = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
     ctx.setTransform(x, y, nextScale);
-  }, [contentWidth, contentHeight, zoom.max, transformRef, alignPadSingle]);
+    return true;
+  }, [contentWidth, contentHeight, zoom.max, transformRef, alignPadSingle, isFloorMapView, effectiveItemUnit, items, cellSize, padSingle]);
+
+  /**
+   * autoFitOnMount：每个画布在「有图元且 content 尺寸已按包围盒算好」后执行一次 fitBounds。
+   * 避免首帧 items 仍为空时用占位尺寸 fit 完并标记 done，导致异步图元加载后不再适配。
+   */
+  var autoFitOnceRef = useRef({
+    frame: '',
+    done: false
+  });
+  var prevItemsCountForAutoFitRef = useRef(null);
+  /**
+   * 首屏 auto fit：时序上易出现「Transform 未挂载 / wrapper 尺寸为 0 / 内容区尚未提交」，
+   * 用 layoutEffect + 双 rAF 贴近浏览器布局完成时刻；仅 fitBounds 真正 setTransform 后才记 done；
+   * viewportSize 纳入依赖以便父级 flex 迟到的尺寸更新后重试（超次不伪造 done）。
+   */
+  useLayoutEffect(function () {
+    if (!isFloorMapView || !autoFitOnMount || frameResetKey === undefined) return;
+    var frame = String(frameResetKey);
+    if (autoFitOnceRef.current.frame !== frame) {
+      autoFitOnceRef.current = {
+        frame: frame,
+        done: false
+      };
+      prevItemsCountForAutoFitRef.current = null;
+    }
+    var itemCount = items.length;
+    var prevN = prevItemsCountForAutoFitRef.current;
+    if (prevN !== null && prevN === 0 && itemCount > 0) {
+      autoFitOnceRef.current.done = false;
+    }
+    prevItemsCountForAutoFitRef.current = itemCount;
+    if (autoFitOnceRef.current.done) return;
+    if (effectiveItemUnit === 'pixel' && itemCount === 0) {
+      return;
+    }
+    if (contentWidth <= 0 || contentHeight <= 0) return;
+    var cancelled = false;
+    var raf = 0;
+    var attempts = 0;
+    var MAX_AUTO_FIT_ATTEMPTS = 160;
+    var tick = function tick() {
+      if (cancelled) return;
+      if (attempts >= MAX_AUTO_FIT_ATTEMPTS) return;
+      var ctx = transformRef.current;
+      var container = containerRef.current;
+      var wrapper = container === null || container === void 0 ? void 0 : container.querySelector('.react-transform-wrapper');
+      if (!ctx || !wrapper) {
+        attempts += 1;
+        raf = requestAnimationFrame(tick);
+        return;
+      }
+      var rect = wrapper.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) {
+        attempts += 1;
+        raf = requestAnimationFrame(tick);
+        return;
+      }
+
+      /** 再等两帧：react-zoom-pan-pinch 与 TransformComponent 常在本帧之后才把可测布局写稳 */
+      raf = requestAnimationFrame(function () {
+        if (cancelled) return;
+        raf = requestAnimationFrame(function () {
+          if (cancelled) return;
+          var ok = fitBounds();
+          if (ok) {
+            autoFitOnceRef.current.done = true;
+            return;
+          }
+          attempts += 1;
+          if (attempts < MAX_AUTO_FIT_ATTEMPTS) {
+            raf = requestAnimationFrame(tick);
+          }
+        });
+      });
+    };
+    raf = requestAnimationFrame(tick);
+    return function () {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+    };
+  }, [isFloorMapView, autoFitOnMount, frameResetKey, effectiveItemUnit, items.length, contentWidth, contentHeight, viewportSize.width, viewportSize.height, mapAreaSize.width, mapAreaSize.height, fitBounds, transformRef]);
   var lastTransformRef = useRef({
     x: 0,
     y: 0,

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

@@ -3,8 +3,10 @@
  * 空间布局视图：在二维平面按坐标渲染资源，支持缩放/平移/复位；支持 floorMapConfig + mode 平面图视图
  */
 export { PisellFloorMapLayout } from './PisellFloorMapLayout';
-export type { PisellFloorMapLayoutProps, PisellFloorMapLayoutRef, FloorMapItemBase, FloorMapItemUnit, FloorMapLayerConfig, FloorMapZoomConfig, FloorMapPanConfig, FloorMapControlsConfig, FloorMapItemShape, FloorMapBackgroundType, FloorMapPanBoundary, FloorMapLayoutMode, FloorMapGridLayoutConfig, FloorMapCanvas, FloorMapElement, FloorMapData, FloorMapViewConfig, FloorMapCanvasUiConfig, FloorMapSceneElement, FloorMapSceneElementDataBinding, FloorMapPlaceMode, FloorMapElementKindCategory, FloorMapElementDataBindingPolicy, FloorMapElementDefaultPresentation, FloorMapEdge, FloorMapElementKindConfig, FloorMapElementType, FloorMapTextSlot, FloorMapDataSources, FloorMapRenderOptions, FloorMapEditPanelParams, DataSourceFormColumn, FloorMapMergedItem, FloorMapRecordFormRenderContext, FloorMapDataSourceRecordFormContent, FloorMapFullscreenMode, FloorMapLayoutContextValue, } from './types';
+export type { PisellFloorMapLayoutProps, PisellFloorMapLayoutRef, FloorMapItemBase, FloorMapItemUnit, FloorMapLayerConfig, FloorMapZoomConfig, FloorMapPanConfig, FloorMapControlsConfig, FloorMapItemShape, FloorMapBackgroundType, FloorMapPanBoundary, FloorMapLayoutMode, FloorMapGridLayoutConfig, FloorMapCanvas, FloorMapCanvasNameI18n, FloorMapElement, FloorMapData, FloorMapViewConfig, FloorMapCanvasUiConfig, FloorMapSceneElement, FloorMapSceneElementDataBinding, FloorMapPlaceMode, FloorMapElementKindCategory, FloorMapElementDataBindingPolicy, FloorMapElementDefaultPresentation, FloorMapEdge, FloorMapElementKindConfig, FloorMapElementType, FloorMapTextSlot, FloorMapDataSources, FloorMapRenderOptions, FloorMapEditPanelParams, DataSourceFormColumn, FloorMapMergedItem, FloorMapRecordFormRenderContext, FloorMapDataSourceRecordFormContent, FloorMapFullscreenMode, FloorMapLayoutContextValue, FloorMapViewportOverlayRenderArgs, } from './types';
 export { FLOOR_MAP_STAGE_ELEMENT_KIND, FLOOR_MAP_IMAGE_ELEMENT_KIND, } from './types';
+export { renderFloorMapFallbackPlaceholder } from './utils/floorMapFallbackRender';
+export { isFloorMapImageElementKind } from './utils/floorMapElementKindUtils';
 export { FloorMapLayoutProvider, useFloorMapLayoutContext, EMPTY_FLOOR_MAP_LAYOUT_CONTEXT, } from './context/FloorMapLayoutContext';
 export type { FloorMapLayoutProviderProps } from './context/FloorMapLayoutContext';
 export { mergeFloorMapLayoutPropsFromContext } from './context/mergeFloorMapLayoutContext';

package/es/components/pisellFloorMapLayout/index.js

@@ -4,6 +4,8 @@
  */
 export { PisellFloorMapLayout } from "./PisellFloorMapLayout";
 export { FLOOR_MAP_STAGE_ELEMENT_KIND, FLOOR_MAP_IMAGE_ELEMENT_KIND } from "./types";
+export { renderFloorMapFallbackPlaceholder } from "./utils/floorMapFallbackRender";
+export { isFloorMapImageElementKind } from "./utils/floorMapElementKindUtils";
 export { FloorMapLayoutProvider, useFloorMapLayoutContext, EMPTY_FLOOR_MAP_LAYOUT_CONTEXT } from "./context/FloorMapLayoutContext";
 export { mergeFloorMapLayoutPropsFromContext } from "./context/mergeFloorMapLayoutContext";
 export { FloorMapImageElement } from "./components/FloorMapImageElement";

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

@@ -46,6 +46,8 @@ declare const _default: {
         'pisell-floor-map-layout.edit-panel.extra-image-url': string;
         'pisell-floor-map-layout.edit-panel.ph-https': string;
         'pisell-floor-map-layout.edit-panel.label-canvas': string;
+        'pisell-floor-map-layout.edit-panel.label-element-kind': string;
+        'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': string;
         'pisell-floor-map-layout.edit-panel.apply': string;
         'pisell-floor-map-layout.edit-panel.data-binding': string;
         'pisell-floor-map-layout.edit-panel.data-binding-note': string;
@@ -106,6 +108,8 @@ declare const _default: {
         'pisell-floor-map-layout.edit-panel.extra-image-url': string;
         'pisell-floor-map-layout.edit-panel.ph-https': string;
         'pisell-floor-map-layout.edit-panel.label-canvas': string;
+        'pisell-floor-map-layout.edit-panel.label-element-kind': string;
+        'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': string;
         'pisell-floor-map-layout.edit-panel.apply': string;
         'pisell-floor-map-layout.edit-panel.data-binding': string;
         'pisell-floor-map-layout.edit-panel.data-binding-note': string;
@@ -166,6 +170,8 @@ declare const _default: {
         'pisell-floor-map-layout.edit-panel.extra-image-url': string;
         'pisell-floor-map-layout.edit-panel.ph-https': string;
         'pisell-floor-map-layout.edit-panel.label-canvas': string;
+        'pisell-floor-map-layout.edit-panel.label-element-kind': string;
+        'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': string;
         'pisell-floor-map-layout.edit-panel.apply': string;
         'pisell-floor-map-layout.edit-panel.data-binding': string;
         'pisell-floor-map-layout.edit-panel.data-binding-note': string;

package/es/components/pisellFloorMapLayout/locales.js

@@ -29,7 +29,7 @@ export default {
     'pisell-floor-map-layout.edit-panel.element-props': 'Element',
     'pisell-floor-map-layout.edit-panel.close-aria': 'Close',
     'pisell-floor-map-layout.edit-panel.hint-apply': 'Position or size changed — click Apply to update the canvas.',
-    'pisell-floor-map-layout.edit-panel.hint-save': 'Layout draft is not saved — click Save at the top.',
+    'pisell-floor-map-layout.edit-panel.hint-save': 'Layout draft is not saved — click Done editing to save.',
     'pisell-floor-map-layout.edit-panel.section-layout': 'Position · Layer · Size',
     'pisell-floor-map-layout.edit-panel.lock-on': 'Locked: drag/resize disabled on canvas; click to unlock',
     'pisell-floor-map-layout.edit-panel.lock-off': 'Lock to disable drag and resize on canvas',
@@ -46,6 +46,8 @@ export default {
     'pisell-floor-map-layout.edit-panel.extra-image-url': 'Use a network image URL; lower layer to place under tables.',
     'pisell-floor-map-layout.edit-panel.ph-https': 'https://...',
     'pisell-floor-map-layout.edit-panel.label-canvas': 'Canvas',
+    'pisell-floor-map-layout.edit-panel.label-element-kind': 'Element type',
+    'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': 'Data binding was cleared because it does not apply to the new type.',
     'pisell-floor-map-layout.edit-panel.apply': 'Apply',
     'pisell-floor-map-layout.edit-panel.data-binding': 'Data binding',
     'pisell-floor-map-layout.edit-panel.data-binding-note': 'Changing data source or row writes to the layout draft; click Save at the top to persist.',
@@ -89,7 +91,7 @@ export default {
     'pisell-floor-map-layout.edit-panel.element-props': '图元属性',
     'pisell-floor-map-layout.edit-panel.close-aria': '关闭',
     'pisell-floor-map-layout.edit-panel.hint-apply': '位置、尺寸等已修改，请点击「应用」同步到画布。',
-    'pisell-floor-map-layout.edit-panel.hint-save': '布局草稿未持久化，请点击顶部「保存」。',
+    'pisell-floor-map-layout.edit-panel.hint-save': '布局草稿未持久化，请点击「完成编辑」保存。',
     'pisell-floor-map-layout.edit-panel.section-layout': '位置 · 层级 · 尺寸',
     'pisell-floor-map-layout.edit-panel.lock-on': '已锁定：画布不可拖拽/缩放；点击解锁',
     'pisell-floor-map-layout.edit-panel.lock-off': '锁定后画布不可拖拽与改尺寸',
@@ -106,6 +108,8 @@ export default {
     'pisell-floor-map-layout.edit-panel.extra-image-url': '可填网络图片地址；将层级调低可铺在桌位下方作底图。',
     'pisell-floor-map-layout.edit-panel.ph-https': 'https://...',
     'pisell-floor-map-layout.edit-panel.label-canvas': '所属画布',
+    'pisell-floor-map-layout.edit-panel.label-element-kind': '图元类型',
+    'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': '新类型与原先绑定不兼容，已清除数据绑定。',
     'pisell-floor-map-layout.edit-panel.apply': '应用',
     'pisell-floor-map-layout.edit-panel.data-binding': '数据绑定',
     'pisell-floor-map-layout.edit-panel.data-binding-note': '修改数据源或绑定行会立即写入布局草稿；持久化请点击顶部「保存」。',
@@ -149,7 +153,7 @@ export default {
     'pisell-floor-map-layout.edit-panel.element-props': '圖元屬性',
     'pisell-floor-map-layout.edit-panel.close-aria': '關閉',
     'pisell-floor-map-layout.edit-panel.hint-apply': '位置、尺寸等已修改，請點擊「套用」同步到畫布。',
-    'pisell-floor-map-layout.edit-panel.hint-save': '佈局草稿未持久化，請點擊頂部「儲存」。',
+    'pisell-floor-map-layout.edit-panel.hint-save': '佈局草稿未持久化，請點擊「完成編輯」儲存。',
     'pisell-floor-map-layout.edit-panel.section-layout': '位置 · 層級 · 尺寸',
     'pisell-floor-map-layout.edit-panel.lock-on': '已鎖定：畫布不可拖曳/縮放；點擊解鎖',
     'pisell-floor-map-layout.edit-panel.lock-off': '鎖定後畫布不可拖曳與改尺寸',
@@ -166,6 +170,8 @@ export default {
     'pisell-floor-map-layout.edit-panel.extra-image-url': '可填網絡圖片地址；將層級調低可鋪在桌位下方作底圖。',
     'pisell-floor-map-layout.edit-panel.ph-https': 'https://...',
     'pisell-floor-map-layout.edit-panel.label-canvas': '所屬畫布',
+    'pisell-floor-map-layout.edit-panel.label-element-kind': '圖元類型',
+    'pisell-floor-map-layout.edit-panel.hint-kind-binding-cleared': '新類型與原先綁定不相容，已清除數據綁定。',
     'pisell-floor-map-layout.edit-panel.apply': '套用',
     'pisell-floor-map-layout.edit-panel.data-binding': '數據綁定',
     'pisell-floor-map-layout.edit-panel.data-binding-note': '修改數據源或綁定行會立即寫入佈局草稿；持久化請點擊頂部「儲存」。',