@zat-design/sisyphus-react 4.5.8-beta.4 → 4.5.8-beta.5

package/es/ProEditTable/components/RcTable/BaseTable.js

@@ -27,6 +27,7 @@ const BaseTable = ({
     isHideCheckBox,
     rowDraggable,
     pagination,
+    paginationValidationEnabled,
     scroll,
     summary,
     page,
@@ -37,7 +38,7 @@ const BaseTable = ({
   const [errorLength] = useEditTableError({
     containerNode: tableRef.current,
     className: 'ant-form-item-explain-error',
-    isEnabled: pagination // 分页时启用
+    isEnabled: paginationValidationEnabled
   });
   const getScroll = useCallback(() => {
     if (!scroll) return null;
@@ -87,17 +88,17 @@ const BaseTable = ({
         });
       },
       itemRender: (index, type, originalElement) => {
-        return type === 'page' && page.pageNum === index && errorLength ? /*#__PURE__*/_jsxs("div", {
+        return paginationValidationEnabled && type === 'page' && page.pageNum === index && errorLength ? /*#__PURE__*/_jsxs("div", {
           className: "pro-edit-table-pagination-item-badge",
           children: [/*#__PURE__*/_jsx(Badge, {
             count: errorLength
           }), originalElement]
         }) : originalElement;
       },
-      onChange: handlePageChange,
-      ...pagination,
-      current: page.pageNum,
-      pageSize: page.pageSize
+      ...(typeof pagination === 'object' ? pagination : {}),
+      current: (typeof pagination === 'object' ? pagination.current : undefined) ?? page.pageNum,
+      pageSize: (typeof pagination === 'object' ? pagination.pageSize : undefined) ?? page.pageSize,
+      onChange: handlePageChange
     } : false,
     scroll: getScroll()
   };

package/es/ProEditTable/components/RcTable/DraggableTable.js

@@ -165,8 +165,6 @@ const DraggableTable = ({
     ...resetProps,
     rowKey: tableRowKey,
     pagination: pagination ? {
-      current: page.pageNum,
-      pageSize: page.pageSize,
       showSizeChanger: false,
       showQuickJumper: true,
       total: value?.length,
@@ -176,8 +174,10 @@ const DraggableTable = ({
           total
         });
       },
-      onChange: handlePageChange,
-      ...pagination
+      ...(typeof pagination === 'object' ? pagination : {}),
+      current: (typeof pagination === 'object' ? pagination.current : undefined) ?? page.pageNum,
+      pageSize: (typeof pagination === 'object' ? pagination.pageSize : undefined) ?? page.pageSize,
+      onChange: handlePageChange
     } : false,
     scroll: getScroll(),
     summary

package/es/ProEditTable/components/RenderField/index.js

@@ -25,7 +25,7 @@ import ConfirmWrapper from "../../../ProForm/components/render/ConfirmWrapper";
 import { getDefaultProps } from "../../utils/getDefaultProps";
 import ListChangedWrapper from "./ListChangedWrapper";
 import useShouldUpdateForTable from "../../utils/useShouldUpdateForTable";
-import { OMIT_FORM_ITEM_AND_DOM_KEYS, arePropsEqual } from "./tools";
+import { OMIT_FORM_ITEM_AND_DOM_KEYS, arePropsEqual, hasRowFunctionDependency, mergeOnFieldChangeRow } from "./tools";
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 const RenderField = ({
   text: value,
@@ -237,21 +237,7 @@ const RenderField = ({
   // 因为这些函数依赖行数据，当行数据变化时需要重新计算
   // 扩展到所有模式（single/multiple/cell），统一行为
   // 注意：需要检查原始的 component/editRender，而不是处理后的 lastComponent
-  const hasFunctionDependency = _isFunction(column?.disabled) ||
-  // disabled 是函数
-  _isFunction(fieldProps) ||
-  // fieldProps 是函数
-  _isFunction(required) ||
-  // required 是函数
-  _isFunction(rules) ||
-  // rules 是函数
-  _isFunction(column?.isEditable) ||
-  // isEditable 是函数
-  _isFunction(component) ||
-  // component 是函数
-  _isFunction(editRender) ||
-  // editRender 是函数
-  _isFunction(viewRender); // viewRender 是函数
+  const hasFunctionDependency = hasRowFunctionDependency(column);
 
   // 移除 isSingleMode 限制，让所有模式都支持响应式更新
   // 性能优化已通过 useShouldUpdateForTable hook 的缓存和防抖机制实现
@@ -349,8 +335,8 @@ const RenderField = ({
   if (isView) {
     // 存在viewRender覆盖默认值
     if (typeof viewRender === 'function') {
-      currentValue = column?.dataIndex?.includes('-') ? value : currentValue;
-      const View = viewRender(currentValue, record || {}, options);
+      const latestCurrentValue = dataIndex ? rowData?.[dataIndex] : value;
+      const View = viewRender(latestCurrentValue, rowData || {}, options);
       TargetComponent = /*#__PURE__*/_jsx(Container, {
         viewEmpty: viewEmpty,
         children: View
@@ -438,7 +424,20 @@ const RenderField = ({
         TargetComponent?.props?.onFieldChange && (await TargetComponent.props.onFieldChange(...callArgs));
         onFieldChange && (await onFieldChange(...callArgs));
 
-        // onFieldChange 内已通过 form.setFieldValue(子路径) 或原地改 record 更新 store；此处再整行 setFieldValue(rowPath, rowAfter) 易用滞后快照覆盖 Field 刚写入的新值（如 formType）。仅延后读表做校验与 forceUpdate，不再整行回写。
+        // 原地修改 row 会改变 store 内的对象，但不会通知 Form 和只读单元格重新渲染。
+        // 只通知相对回调前真正变化的子字段，避免整行回写覆盖回调内显式 setFieldValue 的新值。
+        const latestStoreRow = form.getFieldValue(rowPath, true) || {};
+        const nextStoreRow = mergeOnFieldChangeRow(orgRow, row, latestStoreRow);
+        if (nextStoreRow !== latestStoreRow) {
+          // ProEditTable 注册在整个列表路径上，子行写入不会通知该 Form.Item。
+          // 以最新列表为底只替换当前行，确保其他行与显式 store 写入不被覆盖。
+          const latestList = form.getFieldValue(namePath, true) || [];
+          const nextList = [...latestList];
+          nextList[index] = nextStoreRow;
+          form.setFieldValue(namePath, nextList);
+        }
+
+        // 延后读取通知后的最新 store，统一处理联动校验与行刷新。
         setTimeout(() => {
           const rowAfter = form.getFieldValue(rowPath, true) ?? row;
           if (validateTrigger && validateTrigger.includes('onChange')) {
@@ -597,7 +596,9 @@ const RenderField = ({
       source: 'ProEditTable'
     }
   }), [cellName, lastFieldProps, TargetComponent?.props, namePath, index, lastDisabled, handleChange, handleBlur, confirm, lastDesensitization, names, originalName, viewEmpty, lastValueType, isView, otherProps?.desensitizationKey]);
-  componentProps = _omit(componentProps, ['onFieldChange', 'namePath', 'index', ...OMIT_FORM_ITEM_AND_DOM_KEYS]);
+  componentProps = _omit(componentProps, ['onFieldChange', 'namePath', 'index',
+  // precision 是 InputNumber 的有效 fieldProps，仅在真正渲染原生 DOM 时过滤
+  ...OMIT_FORM_ITEM_AND_DOM_KEYS.filter(key => key !== 'precision')]);
   if (['Switch', 'SwitchCheckbox'].includes(type)) {
     lastFormItemProps.valuePropName = 'checked';
   }
@@ -751,7 +752,7 @@ const RenderField = ({
     // 查看模式
     if (latestIsView) {
       if (typeof viewRender === 'function') {
-        const latestCurrentValue = dataIndex ? latestRowData?.[dataIndex] : null;
+        const latestCurrentValue = dataIndex ? latestRowData?.[dataIndex] : value;
         const View = viewRender(latestCurrentValue, latestRowData || {}, options);
         latestTargetComponent = /*#__PURE__*/_jsx(Container, {
           viewEmpty: viewEmpty,

package/es/ProEditTable/components/RenderField/tools.d.ts

@@ -1,5 +1,12 @@
 import { InternalNamePath, NamePath } from 'antd/lib/form/interface';
 import { GetOriginalValueParams, RenderFieldComparableProps } from './propsType';
+/** 判断列是否包含可能依赖整行数据的函数型配置。 */
+export declare const hasRowFunctionDependency: (column: Record<string, any> | null | undefined) => boolean;
+/**
+ * 将 onFieldChange 中原地修改的字段合并到最新 Form Store 行。
+ * Store 若已将同一字段显式写成其他值，则保留 Store 值。
+ */
+export declare const mergeOnFieldChangeRow: (beforeRow: Record<string, any> | null | undefined, mutatedRow: Record<string, any> | null | undefined, latestStoreRow: Record<string, any> | null | undefined) => Record<string, any>;
 /** 列配置中不应透传到 Form.Item 或 DOM 的字段（与 ProForm Render 保持一致） */
 export declare const OMIT_FORM_ITEM_AND_DOM_KEYS: string[];
 /** 克隆子元素时需从 props 中剔除，避免透传到 div 等 DOM 导致 React 警告 */

package/es/ProEditTable/components/RenderField/tools.js

@@ -4,6 +4,33 @@ import _isEqual from "lodash/isEqual";
 import _get from "lodash/get";
 import { customEqualForFunction } from "../../../utils";
 import { getNamePath, isRecordShallowEqual } from "../../utils/tools";
+const ROW_FUNCTION_DEPENDENCY_KEYS = ['component', 'editRender', 'fieldProps', 'rules', 'required', 'disabled', 'isEditable', 'valueType', 'viewRender'];
+
+/** 判断列是否包含可能依赖整行数据的函数型配置。 */
+export const hasRowFunctionDependency = column => ROW_FUNCTION_DEPENDENCY_KEYS.some(key => _isFunction(column?.[key]));
+
+/**
+ * 将 onFieldChange 中原地修改的字段合并到最新 Form Store 行。
+ * Store 若已将同一字段显式写成其他值，则保留 Store 值。
+ */
+export const mergeOnFieldChangeRow = (beforeRow, mutatedRow, latestStoreRow) => {
+  const before = beforeRow || {};
+  const mutated = mutatedRow || {};
+  const latest = latestStoreRow || {};
+  const changedKeys = Array.from(new Set([...Object.keys(before), ...Object.keys(mutated)])).filter(key => !_isEqual(before[key], mutated[key]));
+  let nextRow = latest;
+  changedKeys.forEach(key => {
+    const storeChangedExplicitly = !_isEqual(latest[key], before[key]) && !_isEqual(latest[key], mutated[key]);
+    if (!storeChangedExplicitly) {
+      nextRow = {
+        ...nextRow,
+        [key]: mutated[key]
+      };
+    }
+  });
+  return nextRow;
+};
+
 /** 列配置中不应透传到 Form.Item 或 DOM 的字段（与 ProForm Render 保持一致） */
 export const OMIT_FORM_ITEM_AND_DOM_KEYS = ['format', 'toISOString', 'toCSTString', 'switchValue', 'precision', 'clearNotShow', 'dependNames', 'shouldCellUpdate' // 表格内部性能优化属性，不应传递给 Form.Item
 ];
@@ -91,9 +118,9 @@ export const arePropsEqual = (prevProps, nextProps) => {
     config: nextConfig
   } = nextProps;
 
-  // 函数型动态属性（component/editRender/fieldProps/rules/required/disabled/isEditable/valueType）
+  // 函数型动态属性（component/editRender/fieldProps/rules/required/disabled/isEditable/valueType/viewRender）
   // 可能依赖行内兄弟字段；行对象为同引用（原地修改）时，浅比较无法区分，需强制重渲染
-  const hasFunctionDependency = _isFunction(prevColumn?.component) || _isFunction(prevColumn?.editRender) || _isFunction(prevColumn?.fieldProps) || _isFunction(prevColumn?.rules) || _isFunction(prevColumn?.required) || _isFunction(prevColumn?.disabled) || _isFunction(prevColumn?.isEditable) || _isFunction(prevColumn?.valueType) || _isFunction(nextColumn?.component) || _isFunction(nextColumn?.editRender) || _isFunction(nextColumn?.fieldProps) || _isFunction(nextColumn?.rules) || _isFunction(nextColumn?.required) || _isFunction(nextColumn?.disabled) || _isFunction(nextColumn?.isEditable) || _isFunction(nextColumn?.valueType);
+  const hasFunctionDependency = hasRowFunctionDependency(prevColumn) || hasRowFunctionDependency(nextColumn);
   if (hasFunctionDependency && prevRecord === nextRecord) {
     return false;
   }

package/es/ProEditTable/index.js

@@ -25,6 +25,7 @@ const ProEditTable = ({
   className,
   columns,
   mode = 'multiple',
+  paginationMode = 'normal',
   stripe = true,
   draggable = false,
   disabled = false,
@@ -118,6 +119,14 @@ const ProEditTable = ({
     selectedRows,
     page
   } = state;
+  const paginationEnabled = Boolean(pagination);
+  const paginationValidationEnabled = paginationEnabled && paginationMode === 'validate';
+  const paginationConfig = typeof pagination === 'object' ? pagination : undefined;
+  const resolvedPage = useMemo(() => ({
+    pageNum: paginationConfig?.current ?? page.pageNum,
+    pageSize: paginationConfig?.pageSize ?? page.pageSize
+  }), [page.pageNum, page.pageSize, paginationConfig?.current, paginationConfig?.pageSize]);
+  const mergedSelectedRowKeys = rowSelection?.selectedRowKeys ?? selectedRowKeys;
   const virtualRowName = getNamePath(_isArray(name) ? name : [name], virtualKey);
 
   // 样式处理
@@ -166,31 +175,26 @@ const ProEditTable = ({
 
   // 分页变更
   const handlePageChange = useCallback(async (current, pageSize) => {
-    try {
-      if (pagination) {
-        if (pageSize !== page.pageSize) {
-          setState({
-            page: {
-              pageNum: current,
-              pageSize
-            }
-          });
-          return;
-        }
+    if (!paginationEnabled) return;
+    const isPageSizeChange = pageSize !== resolvedPage.pageSize;
+    if (paginationValidationEnabled && !isPageSizeChange) {
+      try {
         await form.validateFields([name], {
           recursive: true
         });
-        setState({
-          page: {
-            pageNum: current,
-            pageSize: pageSize ?? page.pageSize
-          }
-        });
+      } catch (error) {
+        handleScrollToError();
+        return;
       }
-    } catch (error) {
-      handleScrollToError();
     }
-  }, [pagination, page.pageSize, form, name]);
+    setState({
+      page: {
+        pageNum: current,
+        pageSize: pageSize ?? resolvedPage.pageSize
+      }
+    });
+    paginationConfig?.onChange?.(current, pageSize);
+  }, [form, name, paginationConfig?.onChange, paginationEnabled, paginationValidationEnabled, resolvedPage.pageSize]);
   const config = useMemo(() => ({
     form,
     mode,
@@ -205,7 +209,7 @@ const ProEditTable = ({
     actionProps,
     toolbarProps,
     setState,
-    selectedRowKeys,
+    selectedRowKeys: mergedSelectedRowKeys,
     selectedRows,
     onlyOneLineMsg,
     deletePoConfirmMsg,
@@ -220,7 +224,7 @@ const ProEditTable = ({
     tableRef,
     max,
     tableLength: value?.length,
-    page,
+    page: resolvedPage,
     originalValues,
     errorStore: errorStoreRef.current,
     prefixCls,
@@ -236,7 +240,7 @@ const ProEditTable = ({
     ...resetProps
   }), [actionDirection, actionProps, actionWidth, columns, deletePoConfirmMsg, diffConfig, editingKeys, emptyBtnText, form,
   // forceUpdate 不应该作为依赖项，因为它是触发刷新的信号，而非用于比较的数据
-  getIsNew, handlePageChange, insertType, isView, max, mode, mulDeletePoConfirmMsg, name, namePath, onlyOneLineMsg, originalValues, prefixCls, requiredAlign, resetProps, rowDisabled, selectedRowKeys, selectedRows, shouldUpdateDebounce, tableRef, toolbarProps, value?.length, viewEmpty, virtualKey, page]);
+  getIsNew, handlePageChange, insertType, isView, max, mode, mulDeletePoConfirmMsg, name, namePath, onlyOneLineMsg, originalValues, prefixCls, requiredAlign, resetProps, rowDisabled, mergedSelectedRowKeys, selectedRows, shouldUpdateDebounce, tableRef, toolbarProps, value?.length, viewEmpty, virtualKey, resolvedPage]);
 
   // 编辑行设置下样式
   const _rowClassName = record => {
@@ -267,19 +271,12 @@ const ProEditTable = ({
   }, [toolbarProps]);
 
   // 是否隐藏勾选框
-  const isHideCheckBox = isForbiddenBtn('mulDelete');
+  const isHideCheckBox = !rowSelection && isForbiddenBtn('mulDelete');
 
   // 复选框
   const _rowSelection = {
     fixed: true,
-    selectedRowKeys,
     columnWidth: 48,
-    onChange: (selectedRowKeys, selectedRows) => {
-      setState({
-        selectedRowKeys,
-        selectedRows
-      });
-    },
     getCheckboxProps: record => {
       if (rowDisabled) {
         const _disabled = rowDisabled(record);
@@ -290,7 +287,15 @@ const ProEditTable = ({
       return {};
     },
     hideSelectAll: isHideCheckBox,
-    ...rowSelection
+    ...rowSelection,
+    selectedRowKeys: mergedSelectedRowKeys,
+    onChange: (nextSelectedRowKeys, nextSelectedRows, info) => {
+      setState({
+        selectedRowKeys: nextSelectedRowKeys,
+        selectedRows: nextSelectedRows
+      });
+      rowSelection?.onChange?.(nextSelectedRowKeys, nextSelectedRows, info);
+    }
   };
 
   // 空列表状态
@@ -411,13 +416,14 @@ const ProEditTable = ({
     isHideCheckBox,
     rowDraggable,
     pagination,
+    paginationValidationEnabled,
     scroll,
     summary: _summary,
-    page,
+    page: resolvedPage,
     formatMessage,
     locale,
     handlePageChange
-  }), [_className, _columns, _rowClassName, disabled, editingKeys, formatMessage, handlePageChange, headerRender, isHideCheckBox, locale, page, pagination, renderRowSelection, rowDraggable, rowKey, tableRowKey, scroll, _summary, tableRef, enrichedValue, virtualKey]);
+  }), [_className, _columns, _rowClassName, disabled, editingKeys, formatMessage, handlePageChange, headerRender, isHideCheckBox, locale, pagination, paginationValidationEnabled, renderRowSelection, rowDraggable, rowKey, tableRowKey, scroll, _summary, tableRef, enrichedValue, resolvedPage, virtualKey]);
 
   // 拖拽排序后，enrichedValue 中含 _dragIndex/_rowIndex（内部字段），需清除后再传给外部 onChange
   const handleDragChange = useCallback(newValue => {
@@ -446,20 +452,20 @@ const ProEditTable = ({
       ref: affixRef,
       ..._toolbarSticky,
       children: /*#__PURE__*/_jsx("div", {
-        className: `pro-edit-table-toolbar${pagination ? ' pro-edit-table-toolbar-fixed' : ''}`,
+        className: `pro-edit-table-toolbar${paginationEnabled ? ' pro-edit-table-toolbar-fixed' : ''}`,
         children: /*#__PURE__*/_jsx(RenderToolbar, {
           ...config
         })
       })
     }) : /*#__PURE__*/_jsx("div", {
-      className: `pro-edit-table-toolbar${pagination ? ' pro-edit-table-toolbar-fixed' : ''}`,
+      className: `pro-edit-table-toolbar${paginationEnabled ? ' pro-edit-table-toolbar-fixed' : ''}`,
       children: /*#__PURE__*/_jsx(RenderToolbar, {
         ...config
       })
     }) : null, footerRender ? /*#__PURE__*/_jsx("div", {
       className: "pro-edit-table-footer",
       children: footerRender
-    }) : null, pagination ? /*#__PURE__*/_jsx("div", {
+    }) : null, paginationValidationEnabled ? /*#__PURE__*/_jsx("div", {
       id: `pro-edit-table-pagination-${Array.isArray(config.name) ? config.name.filter(Boolean).join('-') : config.name || 'default'}`,
       onClick: () => {
         onPageCheck({
@@ -467,7 +473,7 @@ const ProEditTable = ({
           name,
           value,
           columns,
-          page,
+          page: resolvedPage,
           pagination,
           isView,
           disabled,

package/es/ProEditTable/propsType.d.ts

@@ -232,6 +232,7 @@ export type ProEditTableRefType = ProEditTableRefProps;
  */
 export type ProEditTableMode = 'single' | 'multiple';
 export type ProEditTableModeType = ProEditTableMode;
+export type ProEditTablePaginationMode = 'normal' | 'validate';
 /**
  * 表格插入类型
  */
@@ -268,6 +269,11 @@ export interface ProEditTableProps<T = any> extends Omit<TableProps<T>, 'onChang
      * @default multiple
      */
     mode?: ProEditTableMode;
+    /**
+     * 分页行为模式。normal 仅使用 antd 分页，validate 会在切页前校验当前表格
+     * @default normal
+     */
+    paginationMode?: ProEditTablePaginationMode;
     /**
      * 必填对齐方式, 默认右对齐
      * @default right

package/es/ProEditTable/utils/index.js

@@ -12,6 +12,7 @@ import { customValidate, getNamePath, splitNames, handleScrollToError, cloneDeep
 import { filterInternalFields } from "../../ProForm/utils";
 import ProTooltip from "../../ProTooltip";
 import { RenderField, ActionButton } from "../components";
+import { hasRowFunctionDependency } from "../components/RenderField/tools";
 import locale from "../../locale";
 
 /**
@@ -345,7 +346,7 @@ export const transformColumns = (columns = [], config, caches) => {
       const hasComponent = _isFunction(item.component);
       // 函数型动态属性会依赖整行数据（可能是当前列之外的兄弟字段），
       // 这类列在行内任意字段变化时都需重渲染，不能只比对本列 dataIndex
-      const hasFunctionDependency = hasComponent || _isFunction(item.editRender) || _isFunction(item.fieldProps) || _isFunction(item.rules) || _isFunction(item.required) || _isFunction(item.disabled) || _isFunction(item.isEditable) || _isFunction(item.valueType);
+      const hasFunctionDependency = hasRowFunctionDependency(item);
       const columnCacheKey = `${Array.isArray(name) ? name.join('.') : String(name)}::${String(columnName)}`;
 
       // Fix 问题1：用原始列引用（克隆前）比对 dataSource
@@ -399,7 +400,7 @@ export const transformColumns = (columns = [], config, caches) => {
             return true;
           }
         }
-        // 函数型动态属性（component/fieldProps/rules/required/disabled/isEditable/valueType）
+        // 函数型动态属性（component/fieldProps/rules/required/disabled/isEditable/valueType/viewRender）
         // 可能依赖行内其他字段（兄弟字段），需比较整行；
         // 同引用原地修改时 isEqual 恒为 true，无法感知，必须强制重渲染
         if (hasFunctionDependency) {

package/es/ProLayout/components/ProHeader/index.js

@@ -431,6 +431,7 @@ const ProHeader = props => {
       } : {}),
       zIndex
     },
+    "data-pro-step-sticky-header": hasFixedTop ? 'true' : undefined,
     children: finalTitle ? /*#__PURE__*/_jsx("div", {
       className: "pro-header-title",
       children: finalTitle

package/es/ProStep/components/Anchor/index.js

@@ -1,6 +1,6 @@
 import cn from 'classnames';
 import { Badge } from 'antd';
-import { handleScroll } from "../../utils";
+import { handleScroll as defaultHandleScroll } from "../../utils";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const AnchorSvg = ({
   color
@@ -42,7 +42,8 @@ export const MenuItem = props => {
     errorNum,
     currentNum,
     targetOffset,
-    scrollToError = true
+    scrollToError = true,
+    onAnchorClick = defaultHandleScroll
   } = props;
   const renderMenuIcon = () => {
     if (isCurrentStep) {
@@ -81,7 +82,7 @@ export const MenuItem = props => {
       current: isCurrentStep && onOff
     }),
     onClick: () => {
-      handleScroll(code, {
+      onAnchorClick(code, {
         targetOffset,
         scrollToError
       });

package/es/ProStep/components/Item/index.js

@@ -1,6 +1,6 @@
 import _isBoolean from "lodash/isBoolean";
 // @ts-nocheck
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import LazyLoad, { forceCheck } from "../LazyLoad";
 import { useStep } from "../../index";
 import ProCollapse from "../../../ProLayout/components/ProCollapse";
@@ -25,9 +25,9 @@ const ProStepItem = ({
   const {
     register,
     collapse,
-    lazyLoad: globalLazyLoad,
-    targetOffset
+    lazyLoad: globalLazyLoad
   } = useStep();
+  const itemRef = useRef(null);
   const lazyLoad = stepLazyLoad ?? globalLazyLoad;
   useEffect(() => {
     // Schedule registration to avoid re-render issues
@@ -37,6 +37,7 @@ const ProStepItem = ({
         title,
         order,
         lazyLoad,
+        element: itemRef.current,
         ...restProps
       });
     }, 0);
@@ -59,10 +60,11 @@ const ProStepItem = ({
   // If there's no `register` function or if collapsing is enabled, wrap in ProCollapse
   if (!register || collapse && collapseItem && title) {
     return /*#__PURE__*/_jsx("div", {
+      ref: itemRef,
       className: "pro-step-item",
       id: id,
       style: {
-        scrollMarginTop: targetOffset ? `${targetOffset}px` : undefined
+        scrollMarginTop: 'var(--pro-step-anchor-offset)'
       },
       children: /*#__PURE__*/_jsx(ProCollapse, {
         title: title,
@@ -85,10 +87,11 @@ const ProStepItem = ({
 
   // Otherwise, just render children
   return /*#__PURE__*/_jsx("div", {
+    ref: itemRef,
     className: "pro-step-item",
     id: id,
     style: {
-      scrollMarginTop: targetOffset ? `${targetOffset}px` : undefined
+      scrollMarginTop: 'var(--pro-step-anchor-offset)'
     },
     children: renderChildren()
   });

package/es/ProStep/components/Step/index.d.ts

@@ -1,6 +1,10 @@
 import React from 'react';
 import { ProStepType } from '../../propsType';
-export declare const Step: ({ fixedTop, dataSource, activeKey, errorCollection, style, targetOffset, scrollToError, }: import("../../propsType").ProStepPropsType & {
+export declare const Step: ({ fixedTop, dataSource, activeKey, errorCollection, style, targetOffset, scrollToError, onAnchorClick, }: import("../../propsType").ProStepPropsType & {
     errorCollection: object;
+    onAnchorClick?: (id: string, options?: {
+        targetOffset?: string | number;
+        scrollToError?: boolean;
+    }) => void;
 }) => React.JSX.Element;
 export default Step;

package/es/ProStep/components/Step/index.js

@@ -4,8 +4,8 @@ import ProIcon from "../../../ProIcon/index";
 import catalogSvg from "../../../assets/catalog.svg";
 import Anchor from "../Anchor";
 import locale from "../../../locale";
+import { DEFAULT_FIXED_TOP } from "../../constants";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const DEFAULT_FIXED_TOP = 'var(--pro-layout-content-sticky-top, 64px)';
 const toCssLength = value => typeof value === 'number' ? `${value}px` : value;
 export const Step = ({
   fixedTop = DEFAULT_FIXED_TOP,
@@ -14,7 +14,8 @@ export const Step = ({
   errorCollection,
   style,
   targetOffset,
-  scrollToError
+  scrollToError,
+  onAnchorClick
 }) => {
   const [onOff, setOnOff] = useState(false);
   const fixedTopCss = toCssLength(fixedTop);
@@ -36,9 +37,10 @@ export const Step = ({
       item.currentNum = index + 1;
       item.errorNum = errorNum;
       item.targetOffset = targetOffset;
+      item.onAnchorClick = onAnchorClick;
     });
     return nextDataSource;
-  }, [dataSource, activeKey, errorCollection]);
+  }, [dataSource, activeKey, errorCollection, onAnchorClick, targetOffset]);
   const handleMouseEnter = () => {
     setOnOff(true);
   };

package/es/ProStep/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_FIXED_TOP = "var(--pro-layout-content-sticky-top, 64px)";

package/es/ProStep/constants.js

@@ -0,0 +1 @@
+export const DEFAULT_FIXED_TOP = 'var(--pro-layout-content-sticky-top, 64px)';

package/es/ProStep/index.js

@@ -1,11 +1,17 @@
 import _debounce from "lodash/debounce";
-import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useSetState, useLocalStorageState } from 'ahooks';
 import { handleScroll, handleScrollError } from "./utils";
 import Step from "./components/Step";
 import Item from "./components/Item";
 import Listener from "./components/Listener";
+import { DEFAULT_FIXED_TOP } from "./constants";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_ANCHOR_GAP = '16px';
+const ANCHOR_SCROLL_DELAY = 50;
+const STICKY_HEADER_SELECTOR = '[data-pro-step-sticky-header="true"]';
+const toCssLength = value => typeof value === 'number' ? `${value}px` : value;
+
 // 创建上下文并提供类型
 export const ProStepContext = /*#__PURE__*/createContext(null);
 export const useStep = () => {
@@ -23,13 +29,24 @@ const ProStep = ({
   });
   // 注册子节点id与title映射的集合
   const registerMap = useRef({});
+  const wrapperRef = useRef(null);
+  const stickyHeaderRef = useRef(null);
+  const autoAnchorEnabledRef = useRef(false);
+  const scrollTaskRef = useRef(null);
   const [, setLocalData] = useLocalStorageState('cache-pro-step');
   const ids = Object.keys(registerMap.current);
   const {
     collapse = false,
     lazyLoad = false,
-    targetOffset
+    targetOffset,
+    fixedTop
   } = resetProps;
+  const hasExplicitTargetOffset = targetOffset !== undefined && targetOffset !== null;
+  const anchorBase = fixedTop === undefined || fixedTop === null ? DEFAULT_FIXED_TOP : toCssLength(fixedTop);
+  const autoAnchorOffset = `calc(${anchorBase} + var(--pro-step-sticky-header-height, 0px) + ${DEFAULT_ANCHOR_GAP})`;
+  const wrapperStyle = hasExplicitTargetOffset ? {
+    '--pro-step-anchor-offset': toCssLength(targetOffset)
+  } : undefined;
   const dataSource = useMemo(() => {
     if (resetProps?.dataSource) {
       return resetProps?.dataSource;
@@ -56,12 +73,14 @@ const ProStep = ({
     order,
     disabled,
     lazyLoad,
+    element,
     ...rest
   }) => {
     const record = {};
     record.id = id;
     record.title = title;
     record.order = order;
+    record.element = element;
     if (!registerMap.current[id]) {
       debounceReRender();
     }
@@ -100,6 +119,80 @@ const ProStep = ({
       });
     }
   };
+  const measureStickyHeader = useCallback((detect = false) => {
+    if (hasExplicitTargetOffset) {
+      return false;
+    }
+    if (!detect && !autoAnchorEnabledRef.current) {
+      return false;
+    }
+    const wrapper = wrapperRef.current;
+    if (!wrapper) {
+      return false;
+    }
+    const currentHeader = stickyHeaderRef.current;
+    const header = currentHeader && currentHeader.parentElement === wrapper ? currentHeader : Array.from(wrapper.children).find(element => element.matches(STICKY_HEADER_SELECTOR));
+    if (!header) {
+      autoAnchorEnabledRef.current = false;
+      stickyHeaderRef.current = null;
+      wrapper.style.removeProperty('--pro-step-sticky-header-height');
+      wrapper.style.removeProperty('--pro-step-anchor-offset');
+      return false;
+    }
+    autoAnchorEnabledRef.current = true;
+    stickyHeaderRef.current = header;
+    wrapper.style.setProperty('--pro-step-sticky-header-height', `${header.getBoundingClientRect().height}px`);
+    wrapper.style.setProperty('--pro-step-anchor-offset', autoAnchorOffset);
+    return true;
+  }, [autoAnchorOffset, hasExplicitTargetOffset]);
+  useLayoutEffect(() => {
+    autoAnchorEnabledRef.current = false;
+    if (hasExplicitTargetOffset || !measureStickyHeader(true)) {
+      return undefined;
+    }
+    const header = stickyHeaderRef.current;
+    if (!header || typeof ResizeObserver === 'undefined') {
+      return undefined;
+    }
+    const observer = new ResizeObserver(() => {
+      measureStickyHeader();
+    });
+    observer.observe(header);
+    return () => {
+      observer.disconnect();
+      autoAnchorEnabledRef.current = false;
+      stickyHeaderRef.current = null;
+    };
+  }, [hasExplicitTargetOffset, measureStickyHeader]);
+  useEffect(() => {
+    return () => {
+      if (scrollTaskRef.current !== null) {
+        window.clearTimeout(scrollTaskRef.current);
+      }
+    };
+  }, []);
+  const scrollToStep = useCallback((id, options) => {
+    if (autoAnchorEnabledRef.current) {
+      measureStickyHeader();
+    }
+    const root = wrapperRef.current;
+    if (!root) {
+      return;
+    }
+    const registeredElement = registerMap.current[id]?.element;
+    const target = registeredElement && root.contains(registeredElement) ? registeredElement : Array.from(root.querySelectorAll('.pro-step-item')).find(item => item.id === id);
+    if (scrollTaskRef.current !== null) {
+      window.clearTimeout(scrollTaskRef.current);
+    }
+    scrollTaskRef.current = window.setTimeout(() => {
+      scrollTaskRef.current = null;
+      handleScroll(id, {
+        ...options,
+        root,
+        target
+      });
+    }, ANCHOR_SCROLL_DELAY);
+  }, [measureStickyHeader]);
   const notify = async params => {
     const {
       excludes
@@ -121,7 +214,7 @@ const ProStep = ({
     setState({
       errorCollection: nextErrorCollection
     });
-    handleScrollError();
+    handleScrollError(undefined, wrapperRef.current || document);
     return res;
   };
   const triggerTo = async keys => {
@@ -139,7 +232,7 @@ const ProStep = ({
     setState({
       errorCollection: nextErrorCollection
     });
-    handleScrollError();
+    handleScrollError(undefined, wrapperRef.current || document);
     return result;
   };
   return /*#__PURE__*/_jsx(ProStepContext.Provider, {
@@ -149,19 +242,22 @@ const ProStep = ({
       register,
       notify,
       triggerTo,
-      handleScroll,
+      handleScroll: scrollToStep,
       lazyLoad,
       targetOffset,
       unNotify,
       source: 'ProStep'
     },
     children: /*#__PURE__*/_jsxs("div", {
+      ref: wrapperRef,
       className: "pro-step-wrapper",
       id: "pro-step",
+      style: wrapperStyle,
       children: [children, /*#__PURE__*/_jsx(Step, {
         ...resetProps,
         dataSource: dataSource,
-        errorCollection: errorCollection
+        errorCollection: errorCollection,
+        onAnchorClick: scrollToStep
       })]
     })
   });

package/es/ProStep/propsType.d.ts

@@ -45,8 +45,8 @@ export interface ProStepPropsType {
     children?: ReactNode;
     /** 组件自定义样式 */
     style?: CSSProperties;
-    /** 滚动偏移量（单位：像素） */
-    targetOffset?: number;
+    /** 完整滚动偏移量，显式设置时覆盖 ProHeader 自动偏移 */
+    targetOffset?: string | number;
     /** 是否使用折叠标题 */
     collapse?: boolean;
     /** 是否自动滚动到第一个报错的步骤 */
@@ -102,8 +102,8 @@ export interface ProStepContextType {
     handleScroll: (id: string, options?: ScrollOptions) => void;
     /** 懒加载配置 */
     lazyLoad?: boolean | any;
-    /** 滚动偏移量 */
-    targetOffset?: number;
+    /** 完整滚动偏移量 */
+    targetOffset?: string | number;
     /** 取消注册函数 */
     unNotify: (keys: string | string[]) => void;
     /** 来源 */
@@ -126,6 +126,8 @@ export interface RegisterParams {
     order: number;
     /** 是否禁用 */
     disabled?: boolean;
+    /** 当前步骤项 DOM，仅供 ProStep 实例内定位使用 */
+    element?: HTMLElement | null;
     /** 懒加载配置 */
     lazyLoad?: boolean | any;
     /** 允许其他任意属性 */
@@ -144,6 +146,8 @@ export interface RegisterMapItem {
     order: number;
     /** 提交事件 */
     subEvent?: () => Promise<any>;
+    /** 当前步骤项 DOM，仅供 ProStep 实例内定位使用 */
+    element?: HTMLElement | null;
     /** 允许其他任意属性 */
     [key: string]: any;
 }
@@ -161,7 +165,7 @@ export interface NotifyParams {
  */
 export interface ScrollOptions {
     /** 目标偏移量 */
-    targetOffset?: number;
+    targetOffset?: string | number;
     /** 是否滚动到错误位置 */
     scrollToError?: boolean;
 }
@@ -213,9 +217,11 @@ export interface MenuItemProps {
     /** 当前数量 */
     currentNum?: number;
     /** 目标偏移量 */
-    targetOffset?: number;
+    targetOffset?: string | number;
     /** 是否滚动到错误位置 */
     scrollToError?: boolean;
+    /** 当前 ProStep 实例的锚点处理器 */
+    onAnchorClick?: (id: string, options?: ScrollOptions) => void;
 }
 /**
  * ProStep 组件基础类型

package/es/ProStep/utils/index.d.ts

@@ -1,17 +1,17 @@
 import React from 'react';
-import type { LoadedMapType } from '../propsType';
+import type { LoadedMapType, ScrollOptions } from '../propsType';
 /**
  * 滚动到错误位置, 延迟200ms解决ProForm错误还未生成
  */
-export declare const handleScrollError: (dom?: HTMLElement) => void;
+export declare const handleScrollError: (dom?: HTMLElement, root?: ParentNode) => void;
 /**
  * 处理滚动到指定元素位置, 如发现有错误, 则优先滚动到错误位置
  * @param id 目标元素的ID
  * @param options 滚动选项
  */
-export declare const handleScroll: (id: string, options?: {
-    targetOffset?: number;
-    scrollToError?: boolean;
+export declare const handleScroll: (id: string, options?: ScrollOptions & {
+    root?: ParentNode;
+    target?: HTMLElement | null;
 }) => void;
 /**
  * 获取加载模块数据信息

package/es/ProStep/utils/index.js

@@ -1,12 +1,13 @@
 import _pick from "lodash/pick";
-import _debounce from "lodash/debounce";
 import scrollIntoView from 'scroll-into-view-if-needed';
+const toCssLength = value => typeof value === 'number' ? `${value}px` : value;
+
 /**
  * 滚动到错误位置, 延迟200ms解决ProForm错误还未生成
  */
-export const handleScrollError = dom => {
+export const handleScrollError = (dom, root = document) => {
   setTimeout(() => {
-    const errorDom = dom || document.querySelector('[class*="form-item-has-error"]');
+    const errorDom = dom || root.querySelector('[class*="form-item-has-error"]');
     if (errorDom) {
       scrollIntoView(errorDom, {
         behavior: 'smooth',
@@ -24,10 +25,12 @@ export const handleScrollError = dom => {
  */
 export const handleScroll = (id, options) => {
   const {
-    targetOffset = 0,
-    scrollToError
+    targetOffset,
+    scrollToError,
+    root = document,
+    target
   } = options || {};
-  const dom = document.querySelector(`#${id}`);
+  const dom = target || Array.from(root.querySelectorAll('.pro-step-item')).find(item => item.id === id);
   if (dom) {
     // 查找指定id下的错误表单项
     const errorDom = dom.querySelector('[class*="form-item-has-error"]');
@@ -35,14 +38,35 @@ export const handleScroll = (id, options) => {
       // 如果发现错误表单项，执行handleScrollError函数
       handleScrollError(errorDom);
     } else {
-      // 如果没有错误表单项，则滚动到指定元素位置
-      setTimeout(_debounce(() => {
+      // 目录点击必须重新对齐到 sticky 区域下方，不能因“当前可见”而跳过。
+      const previousScrollMarginTop = dom.style.scrollMarginTop;
+      if (targetOffset !== undefined && targetOffset !== null) {
+        dom.style.scrollMarginTop = toCssLength(targetOffset);
+      }
+      try {
         scrollIntoView(dom, {
-          behavior: 'smooth',
+          // compute-scroll-into-view 已计算 scroll-margin；custom behavior 避免外层库再次扣减。
+          behavior: actions => {
+            actions.forEach(({
+              el,
+              top,
+              left
+            }) => {
+              el.scroll({
+                top,
+                left,
+                behavior: 'smooth'
+              });
+            });
+          },
           block: 'start',
-          scrollMode: 'if-needed'
+          scrollMode: 'always'
         });
-      }, 100), 0);
+      } finally {
+        if (targetOffset !== undefined && targetOffset !== null) {
+          dom.style.scrollMarginTop = previousScrollMarginTop;
+        }
+      }
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zat-design/sisyphus-react",
-  "version": "4.5.8-beta.4",
+  "version": "4.5.8-beta.5",
   "license": "MIT",
   "publishConfig": {
     "access": "public",