@ant-design/pro-components 3.1.12-0 → 3.1.13-0

package/es/form/layouts/ModalForm/index.js

@@ -1,10 +1,8 @@
-import { useControlledState, warning } from '@rc-component/util';
+import { warning } from '@rc-component/util';
 import { ConfigProvider, Modal } from 'antd';
-import { merge } from 'lodash-es';
-import React, { useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
-import { createPortal } from 'react-dom';
-import { useRefFunction } from "../../../utils";
+import React, { useContext, useRef } from 'react';
 import { BaseForm } from "../../BaseForm";
+import { useOverlayForm } from "../_shared/useOverlayForm";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Fragment as _Fragment } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
@@ -25,138 +23,34 @@ function ModalForm({
 }) {
   noteOnce(!rest.footer || !modalProps?.footer, 'ModalForm 是一个 ProForm 的特殊布局，如果想自定义按钮，请使用 submit.render 自定义。');
   const context = useContext(ConfigProvider.ConfigContext);
-  const [, forceUpdate] = useState([]);
-  const [loading, setLoading] = useState(false);
-  const [open, setOpenInner] = useControlledState(false, propsOpen);
-
-  /**
-   * 使用 useRefFunction 包装回调，确保引用稳定
-   */
-  const onOpenChangeCallback = useRefFunction(o => {
-    onOpenChange?.(o);
-  });
-
-  /**
-   * 使用 queueMicrotask 延迟回调调用，避免在渲染阶段调用外部回调导致的 React 警告
-   * "Cannot update a component while rendering a different component"
-   */
-  const setOpen = useCallback(updater => {
-    setOpenInner(prev => {
-      const next = typeof updater === 'function' ? updater(prev) : updater;
-      queueMicrotask(() => {
-        onOpenChangeCallback(next);
-      });
-      return next;
-    });
-  }, [onOpenChangeCallback]);
-  const footerRef = useRef(null);
-  const footerDomRef = useCallback(element => {
-    if (footerRef.current === null && element) {
-      forceUpdate([]);
-    }
-    footerRef.current = element;
-  }, []);
   const formRef = useRef();
-  const resetFields = useCallback(() => {
-    const form = rest.form ?? rest.formRef?.current ?? formRef.current;
-    // 重置表单
-    // issue: 8858 form.resetFields is not a function
-    if (form && modalProps?.destroyOnHidden && typeof form.resetFields === 'function') {
-      form.resetFields();
-    }
-  }, [modalProps?.destroyOnHidden, rest.form, rest.formRef]);
-  useImperativeHandle(rest.formRef, () => {
-    return formRef.current;
-  }, [formRef.current]);
-  useEffect(() => {
-    if (propsOpen) {
-      onOpenChange?.(true);
-    }
-  }, [propsOpen]);
-  const triggerDom = useMemo(() => {
-    if (!trigger) {
-      return null;
-    }
-    return /*#__PURE__*/React.cloneElement(trigger, {
-      key: 'trigger',
-      ...trigger.props,
-      onClick: async e => {
-        setOpen(!open);
-        trigger.props?.onClick?.(e);
-      }
-    });
-  }, [setOpen, trigger, open]);
-  const submitterConfig = useMemo(() => {
-    if (rest.submitter === false) {
-      return false;
-    }
-    return merge({
-      searchConfig: {
-        submitText: modalProps?.okText ?? context.locale?.Modal?.okText ?? '确认',
-        resetText: modalProps?.cancelText ?? context.locale?.Modal?.cancelText ?? '取消'
-      },
-      resetButtonProps: {
-        preventDefault: true,
-        disabled: submitTimeout && loading,
-        onClick: e => {
-          setOpen(false);
-          modalProps?.onCancel?.(e);
-        }
-      }
-    }, rest.submitter ?? {});
-  }, [context.locale?.Modal?.cancelText, context.locale?.Modal?.okText, modalProps, rest.submitter, setOpen, loading, submitTimeout]);
-  const contentRender = useCallback((formDom, submitter) => {
-    return /*#__PURE__*/_jsxs(_Fragment, {
-      children: [formDom, footerRef.current && submitter ? /*#__PURE__*/_jsx(React.Fragment, {
-        children: /*#__PURE__*/createPortal(submitter, footerRef.current)
-      }, "submitter") : submitter]
-    });
-  }, []);
-  const onFinishHandle = useCallback(async values => {
-    const response = onFinish?.(values);
-    if (submitTimeout && response instanceof Promise) {
-      setLoading(true);
-      const timer = setTimeout(() => setLoading(false), submitTimeout);
-      try {
-        const result = await response;
-        clearTimeout(timer);
-        setLoading(false);
-        // 返回真值，关闭弹框
-        if (result) {
-          setOpen(false);
-        }
-        return result;
-      } catch (error) {
-        clearTimeout(timer);
-        setLoading(false);
-        throw error;
-      }
-    } else if (submitTimeout) {
-      // 如果 submitTimeout 存在但 response 不是 Promise，也要设置 loading
-      setLoading(true);
-      const timer = setTimeout(() => setLoading(false), submitTimeout);
-      try {
-        const result = await response;
-        clearTimeout(timer);
-        setLoading(false);
-        // 返回真值，关闭弹框
-        if (result) {
-          setOpen(false);
-        }
-        return result;
-      } catch (error) {
-        clearTimeout(timer);
-        setLoading(false);
-        throw error;
-      }
-    }
-    const result = await response;
-    // 返回真值，关闭弹框
-    if (result) {
-      setOpen(false);
-    }
-    return result;
-  }, [onFinish, setOpen, submitTimeout]);
+  const {
+    open,
+    setOpen,
+    loading,
+    footerDomRef,
+    footerRef,
+    triggerDom,
+    submitterConfig,
+    contentRender,
+    onFinishHandle,
+    resetFields
+  } = useOverlayForm({
+    propsOpen,
+    onOpenChange,
+    formRef,
+    propsFormRef: rest.formRef,
+    destroyOnHidden: modalProps?.destroyOnHidden,
+    submitTimeout,
+    onFinish,
+    onCloseExtra: modalProps?.onCancel,
+    submitter: rest.submitter,
+    searchConfig: {
+      submitText: String(modalProps?.okText ?? context.locale?.Modal?.okText ?? '确认'),
+      resetText: String(modalProps?.cancelText ?? context.locale?.Modal?.cancelText ?? '取消')
+    },
+    trigger
+  });
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Modal, {
       title: title,
@@ -164,13 +58,13 @@ function ModalForm({
       ...modalProps,
       open: open,
       onCancel: e => {
-        // 提交表单loading时，阻止弹框关闭
+        // 提交时 loading，阻止关闭
         if (submitTimeout && loading) return;
         setOpen(false);
         modalProps?.onCancel?.(e);
       },
       afterClose: () => {
-        // 确保在关闭时立即重置表单
+        // fix: #6006 destroyOnHidden 时在关闭动画结束后重置，避免在关闭过程中闪烁
         if (modalProps?.destroyOnHidden) {
           resetFields();
         }
@@ -190,6 +84,7 @@ function ModalForm({
         formComponentType: "ModalForm",
         layout: "vertical",
         ...rest,
+        formRef: formRef,
         onInit: (_, form) => {
           if (rest.formRef) {
             rest.formRef.current = form;
@@ -197,12 +92,11 @@ function ModalForm({
           rest?.onInit?.(_, form);
           formRef.current = form;
         },
-        formRef: formRef,
         submitter: submitterConfig,
         onFinish: async values => {
-          const result = await onFinishHandle(values);
-          // fix: #6006 如果 result 为 true,那么必然会触发弹窗关闭，我们无需在 此处重置表单，只需在弹窗关闭时重置即可
-          return result;
+          // fix: #6006 result 为 true 时弹窗关闭由 onFinishHandle 内部处理，
+          // 无需在此重置，等 afterClose 触发时再重置
+          return onFinishHandle(values);
         },
         contentRender: contentRender,
         children: children

package/es/form/layouts/ProForm/index.d.ts

@@ -4,17 +4,17 @@ import type { CommonFormProps } from '../../BaseForm';
 export type ProFormProps<T = Record<string, any>, U = Record<string, any>> = Omit<FormProps<T>, 'onFinish'> & CommonFormProps<T, U>;
 declare function ProForm<T = Record<string, any>>(props: ProFormProps<T> & {
     children?: React.ReactNode | React.ReactNode[];
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 declare namespace ProForm {
     var Group: React.FC<import("src/form").GroupProps>;
     var useForm: typeof import("antd/es/form/Form").useForm;
     var Item: React.FC<import("src/form/components/FormItem").ProFormItemProps>;
-    var useWatch: typeof import("antd/es/form/Form").useWatch;
+    var useWatch: typeof import("@rc-component/form").useWatch;
     var ErrorList: React.FC<import("antd/es/form").ErrorListProps>;
     var Provider: React.FC<import("antd/es/form/context").FormProviderProps>;
     var useFormInstance: typeof import("antd/es/form/hooks/useFormInstance").default;
     var EditOrReadOnlyContext: React.Context<{
-        mode: "update" | "read" | "edit";
+        mode: "read" | "edit" | "update";
     }>;
 }
 export { ProForm };

package/es/form/layouts/ProForm/index.js

@@ -1,5 +1,5 @@
 import { Form } from 'antd';
-import React from 'react';
+import React, { useCallback } from 'react';
 import { BaseForm } from "../../BaseForm";
 import { EditOrReadOnlyContext } from "../../BaseForm/EditOrReadOnlyContext";
 import { Group, ProFormItem } from "../../components";
@@ -7,13 +7,12 @@ import { Fragment as _Fragment } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 import { jsx as _jsx } from "react/jsx-runtime";
 function ProForm(props) {
+  const contentRender = useCallback((items, submitter, _form) => /*#__PURE__*/_jsxs(_Fragment, {
+    children: [items, submitter]
+  }), []);
   return /*#__PURE__*/_jsx(BaseForm, {
     layout: "vertical",
-    contentRender: (items, submitter) => {
-      return /*#__PURE__*/_jsxs(_Fragment, {
-        children: [items, submitter]
-      });
-    },
+    contentRender: contentRender,
     ...props
   });
 }

package/es/form/layouts/QueryFilter/Actions.js

@@ -8,19 +8,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Fragment as _Fragment } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 const defaultCollapseRender = (collapsed, _, intl, hiddenNum) => {
-  if (collapsed) {
-    return /*#__PURE__*/_jsxs(_Fragment, {
-      children: [intl.getMessage('tableForm.collapsed', '展开'), hiddenNum && `(${hiddenNum})`, /*#__PURE__*/_jsx(DownOutlined, {
-        style: {
-          marginInlineStart: '0.5em',
-          transition: '0.3s all',
-          transform: `rotate(${collapsed ? 0 : 0.5}turn)`
-        }
-      })]
-    });
-  }
   return /*#__PURE__*/_jsxs(_Fragment, {
-    children: [intl.getMessage('tableForm.expand', '收起'), /*#__PURE__*/_jsx(DownOutlined, {
+    children: [collapsed ? intl.getMessage('tableForm.collapsed', '展开') : intl.getMessage('tableForm.expand', '收起'), collapsed && hiddenNum && `(${hiddenNum})`, /*#__PURE__*/_jsx(DownOutlined, {
       style: {
         marginInlineStart: '0.5em',
         transition: '0.3s all',

package/es/form/layouts/QueryFilter/index.js

@@ -7,6 +7,7 @@ import { ProProvider, useIntl } from "../../../provider";
 import { isBrowser, useRefFunction } from "../../../utils";
 import { BaseForm } from "../../BaseForm";
 import Actions from "./Actions";
+import { calcSubmitterOffset, processQueryFilterItems } from "./processQueryFilterItems";
 import { useStyle } from "./style";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
@@ -66,23 +67,6 @@ const getSpanConfig = (layout, width, span, breakpointsConfig) => {
     layout: breakPoint?.[2]
   };
 };
-const flatMapItems = (items, ignoreRules) => {
-  return items?.flatMap(item => {
-    if (item?.type?.displayName === 'ProForm-Group' && !item.props?.title) {
-      return item.props.children;
-    }
-    if (ignoreRules && /*#__PURE__*/React.isValidElement(item)) {
-      return /*#__PURE__*/React.cloneElement(item, {
-        ...item.props,
-        formItemProps: {
-          ...item.props?.formItemProps,
-          rules: []
-        }
-      });
-    }
-    return item;
-  });
-};
 const QueryFilterContent = props => {
   const intl = useIntl();
   const {
@@ -140,59 +124,23 @@ const QueryFilterContent = props => {
     });
   }, [props, resetText, searchText, optionRender]);
 
-  // totalSpan 统计控件占的位置，计算 offset 保证查询按钮在最后一列
-  let totalSpan = 0;
-  let itemLength = 0;
-  //首个表单项是否占满第一行
-  let firstRowFull = false;
-  // totalSize 统计控件占的份数
-  let totalSize = 0;
-
-  // for split compute
-  let currentSpan = 0;
-
-  // 处理过，包含是否需要隐藏的 数组
-  const processedList = flatMapItems(items, props.ignoreRules).map((item, index) => {
-    // 如果 formItem 自己配置了 hidden，默认使用它自己的
-    const colSize = /*#__PURE__*/React.isValidElement(item) ? item?.props?.colSize ?? 1 : 1;
-    const colSpan = Math.min(spanSize.span * (colSize || 1), 24);
-    // 计算总的 totalSpan 长度
-    totalSpan += colSpan;
-    // 计算总的 colSize 长度
-    totalSize += colSize;
-    if (index === 0) {
-      firstRowFull = colSpan === 24 && !item?.props?.hidden;
-    }
-    const hidden = item?.props?.hidden ||
-    // 如果收起了
-    collapsed && (firstRowFull ||
-    // 如果 超过显示长度 且 总长度超过了 24
-    totalSize > showLength) && !!index;
-    itemLength += 1;
-    const itemKey = /*#__PURE__*/React.isValidElement(item) && (item.key || `${item.props?.name}`) || index;
-    if ( /*#__PURE__*/React.isValidElement(item) && hidden) {
-      if (!props.preserve) {
-        return {
-          itemDom: null,
-          colSpan: 0,
-          hidden: true
-        };
-      }
-      return {
-        itemDom: /*#__PURE__*/React.cloneElement(item, {
-          hidden: true,
-          key: itemKey || index
-        }),
-        hidden: true,
-        colSpan
-      };
-    }
-    return {
-      itemDom: item,
-      colSpan,
-      hidden: false
-    };
+  // 通过纯函数计算布局信息，消除组件渲染阶段的命令式 let 变量
+  const {
+    processedList,
+    totalSpan,
+    totalSize,
+    lastRowUsedSpan
+  } = processQueryFilterItems({
+    items,
+    spanSize,
+    collapsed,
+    showLength,
+    preserve: props.preserve,
+    ignoreRules: props.ignoreRules
   });
+
+  // 渲染 Col 列表：根据 processedList 生成带 split 线的布局
+  let renderSpan = 0;
   const doms = processedList.map((itemProps, index) => {
     const {
       itemDom,
@@ -200,44 +148,23 @@ const QueryFilterContent = props => {
     } = itemProps;
     const hidden = itemDom?.props?.hidden;
     if (hidden) return itemDom;
-
-    // 每一列的key, 一般是存在的
     const itemKey = /*#__PURE__*/React.isValidElement(itemDom) && (itemDom.key || `${itemDom.props?.name}`) || index;
-    if (24 - currentSpan % 24 < colSpan) {
-      // 如果当前行空余位置放不下，那么折行
-      totalSpan += 24 - currentSpan % 24;
-      currentSpan += 24 - currentSpan % 24;
-    }
-    currentSpan += colSpan;
-    if (split && currentSpan % 24 === 0 && index < itemLength - 1) {
-      return /*#__PURE__*/_jsx(Col, {
-        span: colSpan,
-        className: clsx(`${props.baseClassName}-row-split-line`, `${props.baseClassName}-row-split`, hashId),
-        children: itemDom
-      }, itemKey);
+
+    // 当前行剩余位置放不下时折行
+    if (24 - renderSpan % 24 < colSpan) {
+      renderSpan += 24 - renderSpan % 24;
     }
+    renderSpan += colSpan;
+    const isSplitLine = split && renderSpan % 24 === 0 && index < processedList.length - 1;
     return /*#__PURE__*/_jsx(Col, {
-      className: clsx(`${props.baseClassName}-row-split`, hashId),
       span: colSpan,
+      className: clsx(`${props.baseClassName}-row-split`, isSplitLine && `${props.baseClassName}-row-split-line`, hashId),
       children: itemDom
     }, itemKey);
   });
   const hiddenNum = showHiddenNum && processedList.filter(item => item.hidden).length;
-
-  /** 是否需要展示 collapseRender */
-  const needCollapseRender = useMemo(() => {
-    if (totalSpan < 24 || totalSize <= showLength) {
-      return false;
-    }
-    return true;
-  }, [totalSize, showLength, totalSpan]);
-  const offset = useMemo(() => {
-    const offsetSpan = currentSpan % 24 + (props.submitterColSpanProps?.span ?? spanSize.span);
-    if (offsetSpan > 24) {
-      return 24 - (props.submitterColSpanProps?.span ?? spanSize.span);
-    }
-    return 24 - offsetSpan;
-  }, [currentSpan, currentSpan % 24 + (props.submitterColSpanProps?.span ?? spanSize.span), props.submitterColSpanProps?.span]);
+  const needCollapseRender = totalSpan >= 24 && totalSize > showLength;
+  const offset = calcSubmitterOffset(lastRowUsedSpan, props.submitterColSpanProps?.span ?? spanSize.span);
   const context = useContext(ConfigProvider.ConfigContext);
   const baseClassName = context.getPrefixCls('pro-query-filter');
   return /*#__PURE__*/_jsxs(Row, {

package/es/form/layouts/QueryFilter/processQueryFilterItems.d.ts

@@ -0,0 +1,63 @@
+import type { FormProps } from 'antd';
+import React from 'react';
+export type ProcessedQueryFilterItem = {
+    /** 渲染节点（preserve=false 时隐藏项为 null） */
+    itemDom: React.ReactNode;
+    /** 是否被折叠隐藏 */
+    hidden: boolean;
+    /** 该项占用的 Col span（hidden 时为 0） */
+    colSpan: number;
+};
+export type ProcessQueryFilterItemsOptions = {
+    items: React.ReactNode[];
+    spanSize: {
+        span: number;
+        layout: FormProps['layout'];
+    };
+    /** 当前是否处于折叠状态 */
+    collapsed: boolean;
+    /** 折叠时最多展示几个表单项 */
+    showLength: number;
+    /** 是否保留隐藏项的 DOM（hidden=true 的 clone 而非 null） */
+    preserve?: boolean;
+    /** 是否忽略表单校验规则 */
+    ignoreRules?: boolean;
+};
+export type ProcessQueryFilterItemsResult = {
+    /** 经过处理的表单项列表 */
+    processedList: ProcessedQueryFilterItem[];
+    /**
+     * 统计当前所有项（含换行填充）占用的总 span，用于判断是否需要展示 collapseRender。
+     * 若 totalSpan < 24 且 totalSize <= showLength，则不需要折叠按钮。
+     */
+    totalSpan: number;
+    /** 所有 colSize 之和（用于判断是否超出 showLength） */
+    totalSize: number;
+    /** currentSpan 对 24 取模后的余数，即最后一行已占用的 span */
+    lastRowUsedSpan: number;
+};
+/**
+ * 展开无 title 的 ProForm.Group，可选去除所有 rules
+ */
+export declare const flatMapQueryFilterItems: (items: React.ReactNode[], ignoreRules?: boolean) => React.ReactNode[];
+/**
+ * 纯函数：计算 QueryFilter 的表单项布局信息。
+ *
+ * 将原本散落在 QueryFilterContent 渲染阶段的命令式 `let` 变量计算
+ * 提取为独立的纯函数，便于单独测试和阅读。
+ *
+ * **返回值说明：**
+ * - `processedList`：每个表单项是否隐藏、colSpan 是多少
+ * - `submitterOffset`：提交按钮的 Col offset，使按钮对齐到末尾
+ * - `totalSpan`：所有项累计占用的 span（含换行填充），用于判断是否显示折叠按钮
+ * - `totalSize`：所有项的 colSize 之和，用于判断是否超出 showLength
+ * - `lastRowUsedSpan`：最后一行已占用的 span，用于外部计算 offset
+ */
+export declare function processQueryFilterItems({ items, spanSize, collapsed, showLength, preserve, ignoreRules, }: ProcessQueryFilterItemsOptions): ProcessQueryFilterItemsResult;
+/**
+ * 根据最后一行已占用的 span 和提交按钮自身的 span，计算提交按钮列的 Col offset。
+ *
+ * 规则：lastRowUsedSpan + submitterSpan 若超过 24，则折行，offset = 24 - submitterSpan；
+ * 否则 offset = 24 - lastRowUsedSpan - submitterSpan。
+ */
+export declare function calcSubmitterOffset(lastRowUsedSpan: number, submitterSpan: number): number;

package/es/form/layouts/QueryFilter/processQueryFilterItems.js

@@ -0,0 +1,123 @@
+import React from 'react';
+/**
+ * 展开无 title 的 ProForm.Group，可选去除所有 rules
+ */
+export const flatMapQueryFilterItems = (items, ignoreRules) => {
+  return items?.flatMap(item => {
+    if (item?.type?.displayName === 'ProForm-Group' && !item.props?.title) {
+      return item.props.children;
+    }
+    if (ignoreRules && /*#__PURE__*/React.isValidElement(item)) {
+      return /*#__PURE__*/React.cloneElement(item, {
+        ...item.props,
+        formItemProps: {
+          ...item.props?.formItemProps,
+          rules: []
+        }
+      });
+    }
+    return item;
+  });
+};
+
+/**
+ * 纯函数：计算 QueryFilter 的表单项布局信息。
+ *
+ * 将原本散落在 QueryFilterContent 渲染阶段的命令式 `let` 变量计算
+ * 提取为独立的纯函数，便于单独测试和阅读。
+ *
+ * **返回值说明：**
+ * - `processedList`：每个表单项是否隐藏、colSpan 是多少
+ * - `submitterOffset`：提交按钮的 Col offset，使按钮对齐到末尾
+ * - `totalSpan`：所有项累计占用的 span（含换行填充），用于判断是否显示折叠按钮
+ * - `totalSize`：所有项的 colSize 之和，用于判断是否超出 showLength
+ * - `lastRowUsedSpan`：最后一行已占用的 span，用于外部计算 offset
+ */
+export function processQueryFilterItems({
+  items,
+  spanSize,
+  collapsed,
+  showLength,
+  preserve,
+  ignoreRules
+}) {
+  const flatItems = flatMapQueryFilterItems(items, ignoreRules);
+  let totalSpan = 0;
+  let itemLength = 0;
+  let firstRowFull = false;
+  let totalSize = 0;
+  let currentSpan = 0;
+  const processedList = flatItems.map((item, index) => {
+    const colSize = /*#__PURE__*/React.isValidElement(item) ? item?.props?.colSize ?? 1 : 1;
+    const colSpan = Math.min(spanSize.span * (colSize || 1), 24);
+    totalSpan += colSpan;
+    totalSize += colSize;
+    if (index === 0) {
+      firstRowFull = colSpan === 24 && !item?.props?.hidden;
+    }
+    const hidden = item?.props?.hidden ||
+    // 折叠时，超出 showLength 的项隐藏（第一项始终展示）
+    collapsed && (firstRowFull || totalSize > showLength) && !!index;
+    itemLength += 1;
+    const itemKey = /*#__PURE__*/React.isValidElement(item) && (item.key || `${item.props?.name}`) || index;
+    if ( /*#__PURE__*/React.isValidElement(item) && hidden) {
+      if (!preserve) {
+        return {
+          itemDom: null,
+          colSpan: 0,
+          hidden: true
+        };
+      }
+      return {
+        itemDom: /*#__PURE__*/React.cloneElement(item, {
+          hidden: true,
+          key: itemKey || index
+        }),
+        hidden: true,
+        colSpan
+      };
+    }
+    return {
+      itemDom: item,
+      colSpan,
+      hidden: false
+    };
+  });
+
+  // 第二遍：计算 currentSpan（需要知道换行填充），用于 offset 计算
+  // 这里复用 processedList 的信息，不再需要 doms 阶段的 currentSpan
+  let runningSpan = 0;
+  for (const {
+    itemDom,
+    colSpan
+  } of processedList) {
+    const isHidden = itemDom?.props?.hidden;
+    if (isHidden) continue;
+    if (24 - runningSpan % 24 < colSpan) {
+      // 当前行剩余位置不够，折行：填充剩余 span
+      runningSpan += 24 - runningSpan % 24;
+    }
+    runningSpan += colSpan;
+  }
+  const lastRowUsedSpan = runningSpan % 24;
+  return {
+    processedList,
+    totalSpan,
+    totalSize,
+    lastRowUsedSpan
+  };
+}
+
+/**
+ * 根据最后一行已占用的 span 和提交按钮自身的 span，计算提交按钮列的 Col offset。
+ *
+ * 规则：lastRowUsedSpan + submitterSpan 若超过 24，则折行，offset = 24 - submitterSpan；
+ * 否则 offset = 24 - lastRowUsedSpan - submitterSpan。
+ */
+export function calcSubmitterOffset(lastRowUsedSpan, submitterSpan) {
+  const offsetSpan = lastRowUsedSpan + submitterSpan;
+  if (offsetSpan > 24) {
+    return 24 - submitterSpan;
+  }
+  return 24 - offsetSpan;
+}

package/es/form/layouts/StepsForm/StepForm.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import type { FormProps, StepsProps } from 'antd';
 import type { CommonFormProps } from '../../BaseForm';
 export type StepFormProps<T = Record<string, any>, U = Record<string, any>> = {
@@ -5,5 +6,5 @@ export type StepFormProps<T = Record<string, any>, U = Record<string, any>> = {
     stepProps?: NonNullable<StepsProps['items']>[number];
     index?: number;
 } & Omit<FormProps<T>, 'onFinish' | 'form'> & Omit<CommonFormProps<T, U>, 'submitter' | 'form'>;
-declare function StepForm<T = Record<string, any>>(stepNativeProps: StepFormProps<T>): import("react/jsx-runtime").JSX.Element;
+declare function StepForm<T = Record<string, any>>(stepNativeProps: StepFormProps<T>): import("react").JSX.Element;
 export default StepForm;