@pisell/materials 1.8.31 → 1.8.33

package/lib/components/dataSourceComponents/dataSourceForm/serve.d.ts

@@ -0,0 +1,201 @@
+export interface DataSourceType {
+    key: string;
+    displayName: string;
+    status: string;
+    type: string;
+    isDBInstance: boolean;
+    collections: Collection[];
+}
+export declare type ActionsItem = {
+    method: string;
+    path: string;
+    params: {
+        name: string;
+        value: string;
+    }[];
+    headers: {
+        name: string;
+        value: string;
+    }[];
+    body: Record<string, any>;
+};
+export interface Collection {
+    name: string;
+    title: string;
+    tableName: string;
+    timestamps: boolean;
+    autoGenId: boolean;
+    filterTargetKey: string;
+    fields: Field[];
+    introspected: boolean;
+    unavailableActions: any[];
+    actions: {
+        get: ActionsItem;
+        update: ActionsItem;
+        create: ActionsItem;
+        delete: ActionsItem;
+        list: ActionsItem;
+    };
+}
+interface Field {
+    name: string;
+    type: string;
+    allowNull: boolean;
+    primaryKey: boolean;
+    unique: boolean;
+    autoIncrement: boolean;
+    description?: (null | string)[];
+    possibleTypes?: string[];
+    rawType: string;
+    interface: string;
+    uiSchema: UiSchema;
+    key?: string;
+    collectionName?: string;
+    collectionKey?: any;
+    dataSourceKey?: string;
+    defaultValue?: any;
+}
+interface UiSchema {
+    type?: string;
+    'x-component': string;
+    'x-component-props'?: Xcomponentprops;
+    'x-validator'?: string;
+    title: string;
+    default?: any;
+    enum?: any[];
+}
+interface Xcomponentprops {
+    style?: Style;
+    autoSize?: AutoSize;
+    stringMode?: boolean;
+    step?: string;
+    dateFormat?: string;
+    showTime?: boolean;
+}
+interface AutoSize {
+    minRows: number;
+}
+interface Style {
+    width: string;
+}
+/**
+ * 获取nocobase自定义数据源
+ */
+export declare const getNocobaseDataSource: () => Promise<DataSourceType[]>;
+/**
+ * 获取nocobase主数据源
+ */
+export declare const getNocobaseMainDataSource: () => Promise<any>;
+/**
+ * 获取nocobase数据源设置
+ */
+export declare const getNocobaseDataSourceOptions: () => Promise<any>;
+/**
+ * 创建nocobase数据
+ */
+export declare const createNocobaseData: (params: {
+    key: string;
+    data: any;
+    headers?: any;
+}) => Promise<any>;
+/**
+ * nocobase get数据
+ */
+export declare const getNocobaseData: (params: {
+    key: string;
+    query: Record<string, any>;
+    headers?: any;
+}) => Promise<any>;
+/**
+ * 自定义api接口
+ */
+export declare const customApi: (url: string, data: Record<string, any>, options: {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    baseUrl?: string | undefined;
+    headers?: {
+        name: string;
+        value: any;
+    }[] | undefined;
+    params?: {
+        name: string;
+        value: any;
+    }[] | undefined;
+    body?: Record<string, any> | undefined;
+    dataSourceKey?: string | undefined;
+}) => Promise<any>;
+/**
+ * 更新nocobase数据
+ */
+export declare const updateNocobaseData: (params: {
+    key: string;
+    data: any;
+    headers?: any;
+    query?: Record<string, any> | undefined;
+}) => Promise<any>;
+/**
+ * 获取nocobase数据列表
+ */
+export declare const getNocobaseDataList: (allParams: {
+    key: string;
+    params: {
+        page: number;
+        pageSize: number;
+    };
+    headers?: any;
+}) => Promise<any>;
+/**
+ * 删除nocobase数据
+ */
+export declare const deleteNocobaseData: (key: string, id: string, headers?: any) => Promise<any>;
+/**
+ * 获取formSettingMeta数据
+ * @param params 请求参数
+ * @param params.sectionCodes 配置段代码数组，如 ['payment']
+ * @param params.businessCode 业务代码
+ * @param params.channelCode 渠道代码
+ * @param params.isBoard 是否包含board_code参数
+ * @returns Promise<any> 返回设置元数据
+ */
+export declare const getFormSettingMetaData: (params: {
+    sectionCodes: string[];
+    scope: string;
+    target?: string | undefined;
+}) => Promise<any>;
+/**
+ * 更新租户设置数据
+ * @param params 请求参数
+ * @param params.businessCode 业务代码
+ * @param params.channelCode 渠道代码
+ * @param params.boardCode 板块代码
+ * @param params.data 要更新的数据对象，如 {"order.prefix":"","order.suffix":"","payment.number":""}
+ * @returns Promise<any> 返回更新结果
+ */
+export declare const updateTenantSetting: (params: {
+    scope: string;
+    target?: string | undefined;
+    data: Record<string, any>;
+}) => Promise<any>;
+export declare type DeviceSettingScene = 'template' | 'profile' | 'instance';
+/**
+ * 获取设备设置元数据（POST 类型 GET）
+ * @param params.scene 场景，默认 template
+ * @param params.sceneRequestId URL 中 {id} 占位符的实际取值
+ * @param params.items 需要获取的字段列表，例如 ['order.name', 'order.id']
+ */
+export declare const getDeviceSettingMetaData: (params: {
+    scene?: DeviceSettingScene | undefined;
+    sceneRequestId: string;
+    items: string[];
+}) => Promise<any>;
+/**
+ * 更新设备设置数据
+ * @param params.scene 场景，默认 template
+ * @param params.sceneRequestId URL 中 {id} 占位符的实际取值
+ * @param params.data 需要更新的字段值对象
+ */
+export declare const updateDeviceSetting: (params: {
+    scene?: DeviceSettingScene | undefined;
+    sceneRequestId: string;
+    data: Record<string, any>;
+}) => Promise<any>;
+export {};

package/lib/components/dataSourceComponents/dataSourceForm/serve.js

@@ -232,7 +232,8 @@ var getDeviceSettingMetaData = async (params) => {
     {
       headers: {
         "Content-Type": "application/json"
-      }
+      },
+      isPisell2: true
     }
   );
 };
@@ -254,7 +255,8 @@ var updateDeviceSetting = async (params) => {
     {
       headers: {
         "Content-Type": "application/json"
-      }
+      },
+      isPisell2: true
     }
   );
 };

package/lib/components/dataSourceComponents/fields/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 declare const formFieldMap: {
     FormItemCheckbox: import("react").FC<{}> & {
         Group: import("react").FC<import("./Checkbox/type").CheckboxGroupProps & import("../dataSourceForm/utils").WithModeProps>;
@@ -19,7 +20,7 @@ declare const formFieldMap: {
         Subdomain: import("react").FC<import("antd").InputProps & {
             onChange: (value: string) => void;
             onBlur?: ((e: import("react").FocusEvent<HTMLInputElement, Element>) => void) | undefined;
-            rootDomain: "custom" | "saas" | "xzero";
+            rootDomain: "custom" | "xzero" | "saas";
             customDomain?: string | undefined;
             value?: string | undefined;
             tenantId: string;
@@ -34,7 +35,7 @@ declare const formFieldMap: {
     };
     FormItemSelect: (props: import("antd").SelectProps<any, import("antd/es/select").DefaultOptionType> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -61,7 +62,7 @@ declare const formFieldMap: {
     FormItemIconSelect: import("react").FC<import("./IconSelect/type").IconSelectProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps>;
     FormItemRecordListWrapper: (props: import("./RecordListWrapper/type").RecordListWrapperProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -71,7 +72,7 @@ declare const formFieldMap: {
     }) => import("react").JSX.Element;
     FormItemTabs: (props: import("./Tabs/type").TabsProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
         options?: any;
-        optionSourceType?: "default" | "custom" | "api" | undefined;
+        optionSourceType?: "custom" | "default" | "api" | undefined;
         labelField: string;
         valueField: string;
         extraParams?: Record<string, any> | undefined;
@@ -80,7 +81,7 @@ declare const formFieldMap: {
         extraParams?: Record<string, any> | undefined;
     }) => import("react").JSX.Element;
 };
-declare const getFieldComponent: (fieldComponent: string) => (import("react").FC<import("./Input/type").InputProps> & {
+declare const getFieldComponent: (fieldComponent: string) => import("react").FC<any> | import("react").FC<import("./DatePicker").DataSourceDatePickerProps> | (import("react").FC<import("./Input/type").InputProps> & {
     JSON: import("react").FC<any>;
     Password: import("react").FC<import("antd/es/input").PasswordProps & import("react").RefAttributes<import("antd").InputRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps>;
     TextArea: import("react").FC<import("antd/es/input").TextAreaProps & import("react").RefAttributes<import("antd/es/input/TextArea").TextAreaRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps>;
@@ -93,24 +94,24 @@ declare const getFieldComponent: (fieldComponent: string) => (import("react").FC
     Subdomain: import("react").FC<import("antd").InputProps & {
         onChange: (value: string) => void;
         onBlur?: ((e: import("react").FocusEvent<HTMLInputElement, Element>) => void) | undefined;
-        rootDomain: "custom" | "saas" | "xzero";
+        rootDomain: "custom" | "xzero" | "saas";
         customDomain?: string | undefined;
         value?: string | undefined;
         tenantId: string;
         name?: string | undefined;
         fieldKey?: string | undefined;
     } & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps>;
-}) | import("react").FC<any> | import("react").FC<import("./Upload/type").UploadProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | (import("react").FC<{}> & {
+}) | (import("react").FC<{}> & {
     Group: import("react").FC<import("./Checkbox/type").CheckboxGroupProps & import("../dataSourceForm/utils").WithModeProps>;
 } & {
     Group: import("react").FC<import("./Checkbox/type").CheckboxGroupProps & import("../dataSourceForm/utils").WithModeProps>;
-}) | import("react").FC<import("./ColorPicker/type").ColorPickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./DatePicker").DataSourceDatePickerProps> | (import("react").FC<{}> & {
+}) | import("react").FC<import("./ColorPicker/type").ColorPickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | (import("react").FC<{}> & {
     Group: import("react").FC<import("./Radio/type").RadioGroupProps & import("../dataSourceForm/utils").WithModeProps>;
 } & {
     Group: import("react").FC<import("./Radio/type").RadioGroupProps & import("../dataSourceForm/utils").WithModeProps>;
 }) | ((props: import("antd").SelectProps<any, import("antd/es/select").DefaultOptionType> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;
@@ -119,9 +120,9 @@ declare const getFieldComponent: (fieldComponent: string) => (import("react").FC
     extraParams?: Record<string, any> | undefined;
 }) => import("react").JSX.Element) | import("react").FC<import("./TimePicker/type").TimePickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Input.Phone/WithMode").PhoneInputProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Input.Mobile/WithMode").PhoneInputProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("antd").InputProps & {
     onChange: (value: string) => void;
-} & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("antd").InputProps & import("react").RefAttributes<import("antd").InputRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("antd/es/input").PasswordProps & import("react").RefAttributes<import("antd").InputRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Radio/type").RadioGroupProps & import("../dataSourceForm/utils").WithModeProps> | import("react").FC<import("./Checkbox/type").CheckboxGroupProps & import("../dataSourceForm/utils").WithModeProps> | import("react").FC<import("./DateRangePicker/type").DateRangePickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Translation/type").TranslationProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./IconSelect/type").IconSelectProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | ((props: import("./RecordListWrapper/type").RecordListWrapperProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
+} & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("antd").InputProps & import("react").RefAttributes<import("antd").InputRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("antd/es/input").PasswordProps & import("react").RefAttributes<import("antd").InputRef> & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Radio/type").RadioGroupProps & import("../dataSourceForm/utils").WithModeProps> | import("react").FC<import("./Checkbox/type").CheckboxGroupProps & import("../dataSourceForm/utils").WithModeProps> | import("react").FC<import("./DateRangePicker/type").DateRangePickerProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Upload/type").UploadProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./Translation/type").TranslationProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | import("react").FC<import("./IconSelect/type").IconSelectProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps> | ((props: import("./RecordListWrapper/type").RecordListWrapperProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;
@@ -130,7 +131,7 @@ declare const getFieldComponent: (fieldComponent: string) => (import("react").FC
     extraParams?: Record<string, any> | undefined;
 }) => import("react").JSX.Element) | ((props: import("./Tabs/type").TabsProps & import("../dataSourceForm/utils").WithModeProps & import("../dataSourceForm/utils").WithFormItemProps & {
     options?: any;
-    optionSourceType?: "default" | "custom" | "api" | undefined;
+    optionSourceType?: "custom" | "default" | "api" | undefined;
     labelField: string;
     valueField: string;
     extraParams?: Record<string, any> | undefined;

package/lib/components/dataSourceComponents/hooks/useActions.d.ts

@@ -0,0 +1,18 @@
+import { DataSourceType } from '../provider/dataSource/DataSourceContext';
+export interface UseActionsParams {
+    dataSource?: DataSourceType;
+    currentValue?: 'server' | 'local';
+    __designMode?: string;
+    extraParams?: Record<string, any>;
+}
+declare const useActions: ({ dataSource: propsDataSource, currentValue: propsCurrentValue, __designMode, extraParams: propsExtraParams, }?: UseActionsParams) => {
+    create: (this: unknown, values: Record<string, any>) => Promise<any>;
+    get: (this: unknown) => Promise<any>;
+    update: (this: unknown, values: Record<string, any>) => Promise<any>;
+    list: (this: unknown, params: {
+        page: number;
+        pageSize: number;
+    }) => Promise<any>;
+    destroy: (this: unknown, id: string) => Promise<any>;
+};
+export default useActions;

package/lib/components/pisellFloorMapLayout/PisellFloorMapLayout.js

@@ -79,6 +79,7 @@ function PisellFloorMapLayoutInner(props, ref) {
     pan = {},
     controls = {},
     enableHover = true,
+    readModeSelectedItemId,
     onItemClick,
     onItemHover,
     onItemLeave,
@@ -776,7 +777,8 @@ function PisellFloorMapLayoutInner(props, ref) {
                   onItemHover,
                   onItemLeave,
                   getMergedItemWrapperStyle,
-                  onInteractionChange: setIsInteractingWithElement
+                  onInteractionChange: setIsInteractingWithElement,
+                  readModeSelectedItemId
                 }
               ),
               isFloorMapView && mode === "edit" && (placeMode == null ? void 0 : placeMode.type) === "scene" && /* @__PURE__ */ import_react.default.createElement(

package/lib/components/pisellFloorMapLayout/components/ItemLayer.d.ts

@@ -42,6 +42,10 @@ export interface ItemLayerProps<T extends FloorMapItemBase> {
     onItemLeave?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
     /** 每项外层容器额外样式（与定位样式合并） */
     getMergedItemWrapperStyle?: (item: T, index: number) => CSSProperties | undefined;
+    /**
+     * 阅读态：与 {@link rowKey} 解析 id 相等的图元加选中外圈（如详情 Modal 打开时）。
+     */
+    readModeSelectedItemId?: string | null;
     /**
      * 与编辑态一致：在含 `data-pisell-floor-room-scroll-surface` 的区域内按下时置 true，
      * 用于禁用 Transform 画布平移，避免图元内纵向滑动拖动画布。

package/lib/components/pisellFloorMapLayout/components/ItemLayer.js

@@ -38,6 +38,7 @@ var import_classnames = __toESM(require("classnames"));
 var import_ItemLayer = require("./ItemLayer.less");
 var PREFIX = "pisell-floor-map-layout";
 var ROOM_SCROLL_SURFACE_SELECTOR = "[data-pisell-floor-room-scroll-surface]";
+var READ_MODE_SELECTED_STACK_Z = 1e6;
 function getItemKey(item, index, rowKey) {
   if (!rowKey) return item.id;
   if (typeof rowKey === "string")
@@ -76,6 +77,7 @@ function ItemLayer(props) {
     onItemLeave,
     getMergedItemWrapperStyle,
     onInteractionChange,
+    readModeSelectedItemId,
     className
   } = props;
   const notifyRoomScrollSurfaceActive = (0, import_react.useCallback)(() => {
@@ -142,13 +144,15 @@ function ItemLayer(props) {
       }
       const key = getItemKey(item, index, rowKey);
       const shapeStyle = getShapeStyle(item.shape);
+      const selectedRead = readModeSelectedItemId != null && String(readModeSelectedItemId).trim() !== "" && key === String(readModeSelectedItemId);
       return /* @__PURE__ */ import_react.default.createElement(
         "div",
         {
           key,
           className: (0, import_classnames.default)(`${PREFIX}-item`, {
             [`${PREFIX}-item-hoverable`]: enableHover,
-            [`${PREFIX}-item-hover-outline`]: enableHover && itemHoverOutline
+            [`${PREFIX}-item-hover-outline`]: enableHover && itemHoverOutline,
+            [`${PREFIX}-item-read-selected`]: selectedRead
           }),
           style: {
             position: "absolute",
@@ -157,7 +161,7 @@ function ItemLayer(props) {
             width,
             height,
             boxSizing: "border-box",
-            zIndex: item.zIndex ?? 0,
+            zIndex: selectedRead ? READ_MODE_SELECTED_STACK_Z + (item.zIndex ?? 0) : item.zIndex ?? 0,
             ...shapeStyle,
             ...getMergedItemWrapperStyle == null ? void 0 : getMergedItemWrapperStyle(item, index)
           },
@@ -184,7 +188,8 @@ function ItemLayer(props) {
     onItemLeave,
     getMergedItemWrapperStyle,
     handleItemPointerDownCapture,
-    handleItemTouchStartCapture
+    handleItemTouchStartCapture,
+    readModeSelectedItemId
   ]);
   return /* @__PURE__ */ import_react.default.createElement(
     "div",

package/lib/components/pisellFloorMapLayout/components/ItemLayer.less

@@ -13,10 +13,17 @@
 
   /** hover 描边与编辑态选中一致（见 EditableItemLayer：`pisell-floor-map-layout-editable-item-selected`） */
 
-  &-hoverable&-hover-outline:hover {
+  // &-hoverable&-hover-outline:hover {
+  //   outline: 3px solid var(--fmap-primary, #1677ff);
+  //   outline-offset: 0;
+  //   box-shadow: 0 0 0 1px rgba(22, 119, 255, 0.25);
+  //   z-index: 1;
+  // }
+
+  /** 阅读态：详情弹层等打开时由业务传入 `readModeSelectedItemId`，与编辑态选中描边一致 */
+  &-read-selected {
     outline: 3px solid var(--fmap-primary, #1677ff);
     outline-offset: 0;
     box-shadow: 0 0 0 1px rgba(22, 119, 255, 0.25);
-    z-index: 1;
   }
 }

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

@@ -25,6 +25,7 @@ module.exports = __toCommonJS(useFloorMapTransformMetrics_exports);
 var import_react = require("react");
 var import_layoutMeasurements = require("../utils/layoutMeasurements");
 var import_floorMapViewportPersistence = require("./floorMapViewportPersistence");
+var FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS = 400;
 function useFloorMapTransformMetrics(params) {
   const {
     items,
@@ -79,6 +80,15 @@ function useFloorMapTransformMetrics(params) {
   const [isFullscreen, setIsFullscreen] = (0, import_react.useState)(false);
   const lastFitSnapshotRef = (0, import_react.useRef)(null);
   const [isAtFitBounds, setIsAtFitBounds] = (0, import_react.useState)(false);
+  const fitBoundsTweenHoldRef = (0, import_react.useRef)(false);
+  const fitBoundsTweenHoldClearTimerRef = (0, import_react.useRef)(null);
+  const clearFitBoundsTweenHold = (0, import_react.useCallback)(() => {
+    if (fitBoundsTweenHoldClearTimerRef.current != null) {
+      clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+      fitBoundsTweenHoldClearTimerRef.current = null;
+    }
+    fitBoundsTweenHoldRef.current = false;
+  }, []);
   const [viewportLocked, setViewportLockedState] = (0, import_react.useState)(
     () => viewportPersistKey ? (0, import_floorMapViewportPersistence.readPersistedViewportLock)(viewportPersistKey) : false
   );
@@ -242,43 +252,56 @@ function useFloorMapTransformMetrics(params) {
     const wrapper = container.querySelector(".react-transform-wrapper");
     if (!wrapper) return false;
     const wrapperRect = wrapper.getBoundingClientRect();
-    if (wrapperRect.width <= 0 || wrapperRect.height <= 0) return false;
+    const wEl = wrapper;
+    const layoutW = wEl.clientWidth > 0 ? wEl.clientWidth : wrapperRect.width;
+    const layoutH = wEl.clientHeight > 0 ? wEl.clientHeight : wrapperRect.height;
+    if (layoutW <= 0 || layoutH <= 0) return false;
+    const applyProgrammaticFit = (fx, fy, fScale) => {
+      clearFitBoundsTweenHold();
+      lastFitSnapshotRef.current = { x: fx, y: fy, scale: fScale };
+      setIsAtFitBounds(true);
+      fitBoundsTweenHoldRef.current = true;
+      fitBoundsTweenHoldClearTimerRef.current = setTimeout(() => {
+        fitBoundsTweenHoldClearTimerRef.current = null;
+        fitBoundsTweenHoldRef.current = false;
+        const cur = lastTransformRef.current;
+        const s = lastFitSnapshotRef.current;
+        if (!s) return;
+        const same = Math.abs(s.x - cur.x) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(s.y - cur.y) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(s.scale - cur.scale) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_SCALE_EPSILON;
+        setIsAtFitBounds(same);
+      }, FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS);
+      ctx.setTransform(fx, fy, fScale);
+    };
     const pixelBox = isFloorMapView && effectiveItemUnit === "pixel" && items.length > 0 ? (0, import_layoutMeasurements.getPixelBoundingBox)(items, cellSize) : null;
     if (pixelBox) {
       const bw = Math.max(1, pixelBox.maxRight - pixelBox.minLeft);
       const bh = Math.max(1, pixelBox.maxBottom - pixelBox.minTop);
       const edgePx = 0;
-      const availW = Math.max(1, wrapperRect.width - 2 * edgePx);
-      const availH = Math.max(1, wrapperRect.height - 2 * edgePx);
+      const availW = Math.max(1, layoutW - 2 * edgePx);
+      const availH = Math.max(1, layoutH - 2 * edgePx);
       const raw2 = Math.min(availW / bw, availH / bh);
       const nextScale2 = Math.min(raw2, zoom.max ?? 2);
       const ap = alignPadSingle ?? padSingle;
       const bboxCx = ap + bw / 2;
       const bboxCy = ap + bh / 2;
-      const x2 = wrapperRect.width / 2 - bboxCx * nextScale2;
-      const y2 = wrapperRect.height / 2 - bboxCy * nextScale2;
-      ctx.setTransform(x2, y2, nextScale2);
-      lastFitSnapshotRef.current = { x: x2, y: y2, scale: nextScale2 };
-      setIsAtFitBounds(true);
+      const x2 = layoutW / 2 - bboxCx * nextScale2;
+      const y2 = layoutH / 2 - bboxCy * nextScale2;
+      applyProgrammaticFit(x2, y2, nextScale2);
       return true;
     }
     if (contentWidth <= 0 || contentHeight <= 0) return false;
-    const raw = Math.min(
-      wrapperRect.width / contentWidth,
-      wrapperRect.height / contentHeight
-    );
+    const raw = Math.min(layoutW / contentWidth, layoutH / contentHeight);
     const nextScale = Math.min(raw, zoom.max ?? 2);
     const padA = alignPadSingle ?? 0;
     const x = import_floorMapViewportPersistence.VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
     const y = import_floorMapViewportPersistence.VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
-    ctx.setTransform(x, y, nextScale);
-    lastFitSnapshotRef.current = { x, y, scale: nextScale };
-    setIsAtFitBounds(true);
+    applyProgrammaticFit(x, y, nextScale);
     return true;
   }, [
+    clearFitBoundsTweenHold,
     contentWidth,
     contentHeight,
-    zoom.max,
+    zoom,
     transformRef,
     alignPadSingle,
     isFloorMapView,
@@ -424,12 +447,19 @@ function useFloorMapTransformMetrics(params) {
       const snap = lastFitSnapshotRef.current;
       if (snap) {
         const same = Math.abs(snap.x - x) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(snap.y - y) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(snap.scale - nextScale) < import_floorMapViewportPersistence.FIT_BOUNDS_MATCH_SCALE_EPSILON;
+        if (fitBoundsTweenHoldRef.current) {
+          if (same) {
+            clearFitBoundsTweenHold();
+            setIsAtFitBounds(true);
+          }
+          return;
+        }
         setIsAtFitBounds((prev) => prev === same ? prev : same);
       } else {
         setIsAtFitBounds((prev) => prev ? false : prev);
       }
     },
-    []
+    [clearFitBoundsTweenHold]
   );
   const persistCurrentViewport = (0, import_react.useCallback)(() => {
     const snapshot = lastTransformRef.current;
@@ -445,6 +475,7 @@ function useFloorMapTransformMetrics(params) {
   viewportPersistKeyRef.current = viewportPersistKey;
   const applyPersistedViewport = (0, import_react.useCallback)(
     (cached) => {
+      clearFitBoundsTweenHold();
       const ctx = transformRef.current;
       if (!ctx) return false;
       ctx.setTransform(cached.x, cached.y, cached.scale, 0);
@@ -459,7 +490,7 @@ function useFloorMapTransformMetrics(params) {
       }
       return true;
     },
-    [transformRef]
+    [clearFitBoundsTweenHold, transformRef]
   );
   (0, import_react.useEffect)(() => {
     if (!viewportPersistKey) return;
@@ -516,6 +547,10 @@ function useFloorMapTransformMetrics(params) {
       }
       (_a = flushPersistRef.current) == null ? void 0 : _a.call(flushPersistRef);
       flushPersistRef.current = null;
+      if (fitBoundsTweenHoldClearTimerRef.current != null) {
+        clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+        fitBoundsTweenHoldClearTimerRef.current = null;
+      }
     };
   }, [viewportPersistKey]);
   return {

package/lib/components/pisellFloorMapLayout/types.d.ts

@@ -528,6 +528,11 @@ export interface PisellFloorMapLayoutProps<T extends FloorMapItemBase = FloorMap
      * 是否开启 hover 高亮或 hover 事件，默认 true
      */
     enableHover?: boolean;
+    /**
+     * 阅读态（`mode === 'read'`）：与 {@link rowKey} 解析出的图元 id 相等时，外层容器加选中描边（如详情弹层打开时锚定画布上的桌位）。
+     * 传 `null` / `undefined` / 空字符串时不展示选中外圈。
+     */
+    readModeSelectedItemId?: string | null;
     /**
      * 资源项点击回调
      */