@pisell/materials 3.3.77 → 3.3.79

package/es/components/PisellProcedure/hooks/useOverflowActions.d.ts

@@ -0,0 +1,43 @@
+import React from 'react';
+import type { MenuProps } from 'antd';
+/**
+ * useOverflowActions Hook 配置
+ */
+export interface UseOverflowActionsOptions {
+    /** 操作按钮子元素 */
+    children?: React.ReactNode;
+    /** 按钮间距 */
+    gap?: number;
+    /** More 按钮文案 */
+    moreText?: string;
+}
+/**
+ * useOverflowActions Hook 返回值
+ */
+export interface UseOverflowActionsReturn {
+    /** 容器 ref */
+    containerRef: React.RefObject<HTMLDivElement>;
+    /** 测量容器 ref */
+    measureRef: React.RefObject<HTMLDivElement>;
+    /** More 按钮测量 ref */
+    moreButtonRef: React.RefObject<HTMLDivElement>;
+    /** 左侧插槽 ref（用于测量宽度） */
+    leftSlotRef: React.RefObject<HTMLDivElement>;
+    /** 所有操作项 */
+    actionItems: React.ReactNode[];
+    /** 可见的操作项 */
+    visibleActions: React.ReactNode[];
+    /** 溢出的操作项 */
+    overflowActions: React.ReactNode[];
+    /** 是否有溢出 */
+    hasOverflow: boolean;
+    /** More 菜单项 */
+    moreMenuItems: MenuProps['items'];
+    /** 可用宽度（用于调试） */
+    availableWidth: number;
+}
+/**
+ * 溢出收纳 Hook
+ * @description 处理操作按钮的溢出收纳逻辑，支持左侧自定义内容
+ */
+export declare const useOverflowActions: (options: UseOverflowActionsOptions) => UseOverflowActionsReturn;

package/es/components/PisellProcedure/hooks/useOverflowActions.js

@@ -0,0 +1,351 @@
+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 _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+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 _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); }
+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 _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+import { isValidElement, cloneElement, useMemo, useState, useRef, useEffect, useCallback } from 'react';
+import { extractButtonLabel } from "../utils/extractText";
+
+/**
+ * useOverflowActions Hook 配置
+ */
+
+/**
+ * useOverflowActions Hook 返回值
+ */
+
+/**
+ * 检查元素是否是按钮（根据类名是否包含 "btn"）
+ */
+var isButtonElement = function isButtonElement(element) {
+  var props = element.props || {};
+  var className = props.className;
+
+  // 检查 className 是否包含 "btn"
+  if (typeof className === 'string' && className.includes('btn')) {
+    return true;
+  }
+
+  // 如果 className 是数组，检查数组中是否有包含 "btn" 的字符串
+  if (Array.isArray(className)) {
+    return className.some(function (cls) {
+      return typeof cls === 'string' && cls.includes('btn');
+    });
+  }
+  return false;
+};
+
+/**
+ * 递归提取所有按钮元素
+ */
+var extractButtons = function extractButtons(node) {
+  var index = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  var buttons = [];
+  if (!node) {
+    return buttons;
+  }
+
+  // 如果是数组，递归处理每个元素
+  if (Array.isArray(node)) {
+    node.forEach(function (item, i) {
+      buttons.push.apply(buttons, _toConsumableArray(extractButtons(item, i)));
+    });
+    return buttons;
+  }
+
+  // 如果是有效的 React 元素
+  if ( /*#__PURE__*/isValidElement(node)) {
+    var element = node;
+
+    // 如果当前元素是按钮，直接添加
+    if (isButtonElement(element)) {
+      var _element$key;
+      buttons.push( /*#__PURE__*/cloneElement(element, {
+        key: (_element$key = element.key) !== null && _element$key !== void 0 ? _element$key : "btn-".concat(index)
+      }));
+      return buttons;
+    }
+
+    // 如果不是按钮，递归处理其 children
+    if (element.props && element.props.children) {
+      var childButtons = extractButtons(element.props.children, index);
+      buttons.push.apply(buttons, _toConsumableArray(childButtons));
+    }
+  }
+  return buttons;
+};
+
+/**
+ * 溢出收纳 Hook
+ * @description 处理操作按钮的溢出收纳逻辑，支持左侧自定义内容
+ */
+export var useOverflowActions = function useOverflowActions(options) {
+  var children = options.children,
+    _options$gap = options.gap,
+    gap = _options$gap === void 0 ? 16 : _options$gap;
+  var containerRef = useRef(null);
+  var measureRef = useRef(null);
+  var moreButtonRef = useRef(null);
+  var leftSlotRef = useRef(null);
+  var _useState = useState([]),
+    _useState2 = _slicedToArray(_useState, 2),
+    itemWidths = _useState2[0],
+    setItemWidths = _useState2[1];
+  var _useState3 = useState(80),
+    _useState4 = _slicedToArray(_useState3, 2),
+    moreButtonWidth = _useState4[0],
+    setMoreButtonWidth = _useState4[1];
+  var _useState5 = useState(0),
+    _useState6 = _slicedToArray(_useState5, 2),
+    availableWidth = _useState6[0],
+    setAvailableWidth = _useState6[1];
+
+  /**
+   * 找到所有按钮元素
+   */
+  var actionItems = useMemo(function () {
+    return extractButtons(children);
+  }, [children]);
+
+  /**
+   * 测量所有按钮的宽度
+   */
+  var measureWidths = useCallback(function () {
+    if (typeof window === 'undefined' || !measureRef.current || !moreButtonRef.current) return;
+    try {
+      // 测量所有按钮宽度（向上取整）
+      var buttons = measureRef.current.querySelectorAll('[data-measure-item]');
+      var widths = [];
+      buttons.forEach(function (btn) {
+        var rect = btn.getBoundingClientRect();
+        if (rect) {
+          widths.push(Math.ceil(rect.width));
+        }
+      });
+      setItemWidths(widths);
+
+      // 测量 More 按钮宽度（向上取整）
+      var moreBtnRect = moreButtonRef.current.getBoundingClientRect();
+      if (moreBtnRect) {
+        var moreBtnWidth = Math.ceil(moreBtnRect.width);
+        setMoreButtonWidth(moreBtnWidth);
+      }
+    } catch (error) {
+      // 静默处理错误，避免影响渲染
+      console.warn('Failed to measure button widths:', error);
+    }
+  }, []);
+
+  /**
+   * 更新可用宽度
+   * 计算逻辑：容器宽度 - 左侧插槽宽度 - 间距
+   * 
+   * 注意：统一使用 getBoundingClientRect() 来获取宽度，
+   * 因为 offsetWidth 返回 CSS 像素不受缩放影响，
+   * 而 getBoundingClientRect() 返回视觉像素（受缩放影响）。
+   * 混用会导致在页面缩放时计算错误。
+   */
+  var updateAvailableWidth = useCallback(function () {
+    if (!containerRef.current || typeof window === 'undefined') return;
+    var parent = containerRef.current.parentElement;
+    if (!parent) {
+      var containerRect = containerRef.current.getBoundingClientRect();
+      setAvailableWidth(Math.floor(containerRect.width));
+      return;
+    }
+    var parentStyle = window.getComputedStyle(parent);
+    var parentRect = parent.getBoundingClientRect();
+
+    // 计算缩放比例，用于将 CSS 像素值（如 padding）转换为视觉像素
+    // offsetWidth 是 CSS 像素，getBoundingClientRect().width 是视觉像素
+    var scale = parent.offsetWidth > 0 ? parentRect.width / parent.offsetWidth : 1;
+
+    // padding 从 getComputedStyle 获取的是 CSS 像素，需要乘以缩放比例
+    var paddingLeft = (parseFloat(parentStyle.paddingLeft) || 0) * scale;
+    var paddingRight = (parseFloat(parentStyle.paddingRight) || 0) * scale;
+    var parentGap = (parseFloat(parentStyle.gap) || gap) * scale;
+
+    // 计算左侧插槽占用的宽度（getBoundingClientRect 已经是视觉像素）
+    var leftSlotWidth = 0;
+    if (leftSlotRef.current) {
+      leftSlotWidth = Math.ceil(leftSlotRef.current.getBoundingClientRect().width);
+      // 如果左侧有内容，加上间距
+      if (leftSlotWidth > 0) {
+        leftSlotWidth += parentGap;
+      }
+    }
+
+    // 计算其他兄弟元素（如 summaryButton）的宽度
+    var otherSiblingWidth = 0;
+    var siblings = parent.children;
+    for (var i = 0; i < siblings.length; i++) {
+      var sibling = siblings[i];
+      // 排除当前容器和隐藏的测量元素
+      if (sibling !== containerRef.current && sibling !== leftSlotRef.current && !sibling.hasAttribute('aria-hidden')) {
+        var siblingWidth = Math.ceil(sibling.getBoundingClientRect().width);
+        if (siblingWidth > 0) {
+          otherSiblingWidth += siblingWidth + parentGap;
+        }
+      }
+    }
+
+    // 可用宽度 = 父容器宽度（视觉像素） - padding - 左侧插槽 - 其他兄弟元素
+    var totalWidth = parentRect.width - paddingLeft - paddingRight;
+    var width = Math.floor(totalWidth - leftSlotWidth - otherSiblingWidth);
+    setAvailableWidth(Math.max(0, width));
+  }, [gap]);
+
+  /**
+   * 初始化测量
+   */
+  useEffect(function () {
+    var rafId = requestAnimationFrame(function () {
+      measureWidths();
+      updateAvailableWidth();
+    });
+    return function () {
+      return cancelAnimationFrame(rafId);
+    };
+  }, [actionItems, measureWidths, updateAvailableWidth]);
+
+  /**
+   * 监听尺寸变化
+   */
+  useEffect(function () {
+    var _containerRef$current;
+    if (typeof window === 'undefined') return;
+    var handleResize = function handleResize() {
+      measureWidths();
+      updateAvailableWidth();
+    };
+    window.addEventListener('resize', handleResize);
+    var parent = (_containerRef$current = containerRef.current) === null || _containerRef$current === void 0 ? void 0 : _containerRef$current.parentElement;
+    var resizeObserver = null;
+    if (parent && typeof ResizeObserver !== 'undefined') {
+      try {
+        resizeObserver = new ResizeObserver(function () {
+          measureWidths();
+          updateAvailableWidth();
+        });
+        resizeObserver.observe(parent);
+      } catch (error) {
+        console.warn('Failed to create ResizeObserver:', error);
+      }
+    }
+
+    // 也监听左侧插槽的尺寸变化
+    if (leftSlotRef.current && typeof ResizeObserver !== 'undefined') {
+      try {
+        var leftObserver = new ResizeObserver(function () {
+          return updateAvailableWidth();
+        });
+        leftObserver.observe(leftSlotRef.current);
+        return function () {
+          var _resizeObserver;
+          window.removeEventListener('resize', handleResize);
+          (_resizeObserver = resizeObserver) === null || _resizeObserver === void 0 || _resizeObserver.disconnect();
+          leftObserver.disconnect();
+        };
+      } catch (error) {
+        console.warn('Failed to create ResizeObserver for leftSlot:', error);
+      }
+    }
+    return function () {
+      var _resizeObserver2;
+      window.removeEventListener('resize', handleResize);
+      (_resizeObserver2 = resizeObserver) === null || _resizeObserver2 === void 0 || _resizeObserver2.disconnect();
+    };
+  }, [measureWidths, updateAvailableWidth]);
+
+  /**
+   * 计算可见项数量
+   * 根据可用宽度计算能显示多少个按钮
+   */
+  var visibleCount = useMemo(function () {
+    if (itemWidths.length === 0 || availableWidth === 0) {
+      return actionItems.length;
+    }
+    var totalItems = itemWidths.length;
+    var totalButtonsWidth = itemWidths.reduce(function (sum, w) {
+      return sum + w;
+    }, 0);
+    var totalGapsWidth = (totalItems - 1) * gap;
+    var allButtonsWidth = totalButtonsWidth + totalGapsWidth;
+
+    // 所有按钮都能放下
+    if (allButtonsWidth <= availableWidth) {
+      return totalItems;
+    }
+
+    // 需要 More 按钮，预留 More 按钮的空间
+    var spaceForButtons = availableWidth - moreButtonWidth - gap;
+    if (spaceForButtons <= 0) {
+      // 空间不足时，不保留任何按钮，全部收纳到 More 菜单
+      return 0;
+    }
+
+    // 从右边开始计算能放下多少个按钮（保留主要操作）
+    var usedWidth = 0;
+    var count = 0;
+    for (var i = totalItems - 1; i >= 0; i--) {
+      var itemWidth = itemWidths[i];
+      var gapWidth = count > 0 ? gap : 0;
+      var requiredWidth = itemWidth + gapWidth;
+      if (usedWidth + requiredWidth <= spaceForButtons) {
+        usedWidth += requiredWidth;
+        count++;
+      } else {
+        break;
+      }
+    }
+
+    // 不强制保留最后一个按钮，空间不足时全部收纳到 More 菜单
+    return count;
+  }, [itemWidths, availableWidth, gap, moreButtonWidth, actionItems.length]);
+
+  // 计算溢出项和可见项
+  var overflowCount = Math.max(0, actionItems.length - visibleCount);
+  var overflowActions = actionItems.slice(0, overflowCount);
+  var visibleActions = actionItems.slice(overflowCount);
+  var hasOverflow = overflowCount > 0;
+
+  /**
+   * 构建 More 菜单项
+   */
+  var moreMenuItems = useMemo(function () {
+    return overflowActions.map(function (action, index) {
+      if (! /*#__PURE__*/isValidElement(action)) return null;
+      var buttonProps = action.props;
+      var label = extractButtonLabel(buttonProps, "\u64CD\u4F5C ".concat(index + 1));
+      var originalOnClick = buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.onClick;
+      return {
+        key: "overflow-".concat(index),
+        label: label,
+        onClick: originalOnClick ? function () {
+          return originalOnClick({});
+        } : undefined,
+        disabled: (buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.disabled) || (buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.loading),
+        danger: buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.danger,
+        icon: buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.icon,
+        title: buttonProps === null || buttonProps === void 0 ? void 0 : buttonProps.title
+      };
+    }).filter(Boolean);
+  }, [overflowActions]);
+  return {
+    containerRef: containerRef,
+    measureRef: measureRef,
+    moreButtonRef: moreButtonRef,
+    leftSlotRef: leftSlotRef,
+    actionItems: actionItems,
+    visibleActions: visibleActions,
+    overflowActions: overflowActions,
+    hasOverflow: hasOverflow,
+    moreMenuItems: moreMenuItems,
+    availableWidth: availableWidth
+  };
+};

package/es/components/PisellProcedure/hooks/useResponsiveClass.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 使用响应式类名的 Hook
+ *
+ * @description 根据容器宽度计算响应式类名，延迟应用以避免宽度抖动
+ */
+export declare const useResponsiveClass: (containerWidth: number) => string;

package/es/components/PisellProcedure/hooks/useResponsiveClass.js

@@ -0,0 +1,47 @@
+/**
+ * 响应式断点常量
+ */
+var RESPONSIVE_BREAKPOINTS = {
+  lg: 1133,
+  // ≥1133px: 默认样式（405px）
+  md: 960,
+  // 960px-1133px: 376px ~ 405px 线性插值
+  sm: 744 // 744px-960px: 290px ~ 376px 线性插值
+};
+
+/**
+ * 响应式类名映射
+ */
+var RESPONSIVE_CLASSES = {
+  md: 'pisell-procedure-sidebar--responsive-md',
+  sm: 'pisell-procedure-sidebar--responsive-sm',
+  xs: 'pisell-procedure-sidebar--responsive-xs' // 最小宽度（< 744px）
+};
+
+/**
+ * 根据容器宽度获取响应式类名
+ */
+var getResponsiveClass = function getResponsiveClass(width) {
+  if (width === 0 || !width) return '';
+  if (width >= RESPONSIVE_BREAKPOINTS.lg) {
+    return ''; // 使用默认样式
+  }
+  if (width >= RESPONSIVE_BREAKPOINTS.md) {
+    return RESPONSIVE_CLASSES.md;
+  }
+  if (width >= RESPONSIVE_BREAKPOINTS.sm) {
+    return RESPONSIVE_CLASSES.sm;
+  }
+
+  // 容器宽度 < 744px，使用最小宽度样式
+  return RESPONSIVE_CLASSES.xs;
+};
+
+/**
+ * 使用响应式类名的 Hook
+ * 
+ * @description 根据容器宽度计算响应式类名，延迟应用以避免宽度抖动
+ */
+export var useResponsiveClass = function useResponsiveClass(containerWidth) {
+  return getResponsiveClass(containerWidth);
+};

package/es/components/PisellProcedure/hooks/useSidebarHeight.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 尺寸值接口
+ */
+interface SizeValues {
+    containerSelector?: string;
+    containerHeight?: number;
+    headerHeight?: number;
+    footerHeight: number;
+}
+/**
+ * 使用 Sidebar 高度的 Hook
+ *
+ * @description 计算并管理 Sidebar 的高度，确保在尺寸稳定后才应用
+ */
+export declare const useSidebarHeight: (isSizeStable: boolean, sizeValues: SizeValues) => number | undefined;
+export {};

package/es/components/PisellProcedure/hooks/useSidebarHeight.js

@@ -0,0 +1,158 @@
+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); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+/**
+ * 尺寸值接口
+ */
+
+/**
+ * 使用 Sidebar 高度的 Hook
+ *
+ * @description 计算并管理 Sidebar 的高度，确保在尺寸稳定后才应用
+ */
+export var useSidebarHeight = function useSidebarHeight(isSizeStable, sizeValues) {
+  var _useState = useState(undefined),
+    _useState2 = _slicedToArray(_useState, 2),
+    siderHeight = _useState2[0],
+    setSiderHeight = _useState2[1];
+  var hasInitializedRef = useRef(false);
+  var rafIdRef = useRef(null);
+  var stableCheckCountRef = useRef(0);
+  var previousSiderHeightRef = useRef(undefined);
+  var sizeValuesRef = useRef(sizeValues);
+
+  // 更新最新的尺寸值
+  useEffect(function () {
+    sizeValuesRef.current = sizeValues;
+  }, [sizeValues]);
+
+  /**
+   * 获取 body 元素的 CSS transform Y 轴缩放比例
+   * @returns scaleY 缩放比例
+   */
+  var getBodyScaleY = useCallback(function () {
+    try {
+      if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return 1;
+      }
+      var bodyTransform = getComputedStyle(document.body).transform;
+      var scaleY = 1;
+      if (bodyTransform !== 'none') {
+        var matrix = new DOMMatrix(bodyTransform);
+        scaleY = matrix.d; // Y 轴缩放
+      }
+      return scaleY;
+    } catch (error) {
+      return 1;
+    }
+  }, []);
+
+  /**
+   * 计算高度的函数
+   * @description 计算时会考虑 body 上的 CSS transform 缩放，返回缩放校正后的实际逻辑高度
+   */
+  var calculateHeight = useCallback(function () {
+    var _sizeValuesRef$curren = sizeValuesRef.current,
+      containerSelector = _sizeValuesRef$curren.containerSelector,
+      containerHeight = _sizeValuesRef$curren.containerHeight,
+      headerHeight = _sizeValuesRef$curren.headerHeight,
+      footerHeight = _sizeValuesRef$curren.footerHeight;
+
+    // 优先使用容器高度，如果没有提供容器选择器或容器高度无效，则使用视口高度
+    var baseHeight;
+    if (containerSelector && containerSelector.trim() && containerHeight && containerHeight > 0) {
+      baseHeight = containerHeight;
+    } else {
+      baseHeight = typeof window !== 'undefined' ? window.innerHeight : 0;
+    }
+    var bodyPadding = 16 * 2; // 上下各16px
+    var headerHeightValue = headerHeight || 0;
+    var calculatedHeight = baseHeight - headerHeightValue - footerHeight - bodyPadding;
+
+    // 获取 body 的 Y 轴缩放比例，并计算校正后的高度
+    var scaleY = getBodyScaleY();
+    var scaledHeight = calculatedHeight / scaleY;
+
+    // 保留两位小数
+    return Math.round(scaledHeight * 100) / 100;
+  }, [sizeValuesRef.current, getBodyScaleY]);
+
+  // 使用 requestAnimationFrame 确保在浏览器重绘后计算，更稳定
+  useEffect(function () {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return;
+    }
+
+    // 如果尺寸还未稳定，清除之前的动画帧，重置检查计数
+    if (!isSizeStable) {
+      hasInitializedRef.current = false;
+      stableCheckCountRef.current = 0;
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+      }
+      return;
+    }
+
+    // 清除之前的动画帧
+    if (rafIdRef.current !== null) {
+      cancelAnimationFrame(rafIdRef.current);
+    }
+
+    /**
+     * 稳定性检查函数：连续3次检查尺寸都稳定才认为真正稳定
+     */
+    var checkStability = function checkStability() {
+      // 再次检查尺寸是否稳定（防止在等待期间尺寸又变化了）
+      if (!isSizeStable) {
+        stableCheckCountRef.current = 0;
+        return;
+      }
+      var calculatedHeight = calculateHeight();
+
+      // 如果高度无效，重置计数
+      if (calculatedHeight <= 0) {
+        stableCheckCountRef.current = 0;
+        return;
+      }
+
+      // 获取上一次的高度用于比较
+      var previousHeight = previousSiderHeightRef.current;
+
+      // 如果已经初始化过，且高度变化小于阈值（10px），直接使用之前的高度
+      if (hasInitializedRef.current && previousHeight !== undefined && Math.abs(calculatedHeight - previousHeight) < 10) {
+        return; // 高度变化太小，不更新
+      }
+
+      // 连续3次检查高度都相同（或变化很小），才认为稳定
+      stableCheckCountRef.current += 1;
+      if (stableCheckCountRef.current >= 3) {
+        // 稳定了，应用高度
+        previousSiderHeightRef.current = calculatedHeight;
+        setSiderHeight(calculatedHeight);
+        hasInitializedRef.current = true;
+        stableCheckCountRef.current = 0; // 重置计数
+      } else {
+        // 还未稳定，继续等待下一次重绘
+        rafIdRef.current = requestAnimationFrame(checkStability);
+      }
+    };
+
+    // 使用 requestAnimationFrame 确保在浏览器重绘后检查
+    rafIdRef.current = requestAnimationFrame(checkStability);
+
+    // 清理函数
+    return function () {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = null;
+      }
+    };
+  }, [isSizeStable, calculateHeight]);
+  return siderHeight;
+};

package/es/components/PisellProcedure/hooks/useStepManager.d.ts

@@ -0,0 +1,50 @@
+import type { StepChangeResult } from '../types';
+import type { PisellStepsProps } from '../../PisellSteps/types';
+/**
+ * useStepManager Hook 配置
+ */
+export interface UseStepManagerOptions {
+    /** 步骤条配置 */
+    stepsProps?: PisellStepsProps;
+    /** 初始步骤索引 */
+    defaultCurrent?: number;
+    /** 上一步事件回调 */
+    onPrev?: (current: number) => boolean | void;
+    /** 下一步事件回调 */
+    onNext?: (current: number) => boolean | void;
+    /** 步骤变化回调 */
+    onStepsChange?: (result: StepChangeResult) => void;
+    /** 跳转到指定步骤 */
+    goToStep?: (step: number) => void;
+}
+/**
+ * useStepManager Hook 返回值
+ */
+export interface UseStepManagerReturn {
+    /** 当前步骤索引 */
+    currentStep: number;
+    /** 步骤列表 */
+    items: any[];
+    /** 步骤总数 */
+    totalSteps: number;
+    /** 上一步 */
+    goPrev: () => StepChangeResult | null;
+    /** 下一步 */
+    goNext: () => StepChangeResult | null;
+    /** 跳转到指定步骤 */
+    goToStep: (step: number) => StepChangeResult | null;
+}
+/**
+ * 步骤管理 Hook
+ *
+ * @description 管理多步骤流程的状态和操作
+ * @example
+ * const { currentStep, goPrev, goNext } = useStepManager({
+ *   stepsProps: { items: [...] },
+ *   defaultCurrent: 0,
+ *   onPrev: (current) => { ... },
+ *   onNext: (current) => { ... },
+ *   onStepsChange: (result) => { ... },
+ * });
+ */
+export declare const useStepManager: ({ stepsProps, defaultCurrent, onPrev, onNext, onStepsChange, }: UseStepManagerOptions) => UseStepManagerReturn;