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

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.3",
+  "version": "4.5.8-beta.5",
   "license": "MIT",
   "publishConfig": {
     "access": "public",