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

package/es/form/BaseForm/BaseForm.js

@@ -1,10 +1,10 @@
 import { get, set as namePathSet, omit, set, useControlledState, warning } from '@rc-component/util';
-import { useUrlSearchParams } from '@umijs/use-params';
 import { ConfigProvider, Form, Spin } from 'antd';
 import { clsx } from 'clsx';
-import React, { useCallback, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import React, { useContext, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
 import { ProConfigProvider } from "../../provider";
-import { autoFocusToFirstChild, conversionMomentValue, isDeepEqualReact, nanoid, ProFormContext, runFunction, transformKeySubmitValue, useFetchData, usePrevious, useRefFunction, useStyle } from "../../utils";
+import { autoFocusToFirstChild, conversionMomentValue, isDeepEqualReact, nanoid, ProFormContext, transformKeySubmitValue, useFetchData, usePrevious, useRefFunction, useStyle } from "../../utils";
+import { useUrlSync } from "./useUrlSync";
 import { FormListContext } from "../components/List";
 import FieldContext from "../FieldContext";
 import { GridContext, useGridHelpers } from "../helpers";
@@ -18,13 +18,6 @@ const {
 
 // Define ProFormInstance and ProFormRef
 
-const genParams = (syncUrl, params, type) => {
-  if (syncUrl === true) {
-    return params;
-  }
-  return runFunction(syncUrl, params, type);
-};
-
 /**
  * It takes a name path and converts it to an array.
  * @param {NamePath} name - The name of the form.
@@ -39,6 +32,61 @@ const covertFormName = name => {
   return [name];
 };
 const defaultExtraUrlParams = {};
+
+/**
+ * 构建 ProForm 格式化方法集合，供 formatValues useMemo 与 useImperativeHandle 共用，
+ * 消除两处完全相同的 ~80 行重复实现。
+ */
+function buildFormatValues(getFormInstance, transformKey, omitNil) {
+  return {
+    getFieldsFormatValue: (allData, omitNilParam) => {
+      const instance = getFormInstance();
+      if (!instance) return {};
+      const values = instance.getFieldsValue(allData);
+      return transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
+    },
+    getFieldFormatValue: (paramsNameList = [], omitNilParam) => {
+      const instance = getFormInstance();
+      if (!instance) return undefined;
+      const nameList = covertFormName(paramsNameList);
+      if (!nameList) throw new Error('nameList is require');
+      const value = instance.getFieldValue(nameList);
+      const obj = nameList ? set({}, nameList, value) : value;
+      // transformKey 会将 keys 重新和 nameList 拼接，所以要将 nameList 的首个元素弹出
+      const newNameList = [...nameList];
+      newNameList.shift();
+      const transformed = transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, newNameList);
+      const result = get(transformed, nameList);
+      // 如果结果是对象，返回对象的值
+      if (result && typeof result === 'object' && !Array.isArray(result)) {
+        const objValue = Object.values(result)[0];
+        return objValue;
+      }
+      return result;
+    },
+    getFieldFormatValueObject: (paramsNameList, omitNilParam) => {
+      const instance = getFormInstance();
+      if (!instance) return {};
+      const nameList = covertFormName(paramsNameList);
+      const value = instance.getFieldValue(nameList);
+      const obj = nameList ? set({}, nameList, value) : value;
+      // 与 getFieldFormatValue 一致：弹出 nameList 首段再交给 transformKey，
+      // 否则 conversionMomentValue 会得到重复的 parentPath（如可编辑表格行 key），
+      // fieldsValueType 匹配失败且极端情况下日期字段无法格式化为 string/number。
+      const newNameList = nameList ? [...nameList] : [];
+      newNameList.shift();
+      return transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, newNameList);
+    },
+    validateFieldsReturnFormatValue: async (nameList, omitNilParam) => {
+      const instance = getFormInstance();
+      if (!instance) return {};
+      if (!Array.isArray(nameList) && nameList) throw new Error('nameList must be array');
+      const values = await instance.validateFields(nameList);
+      const transformedKey = transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
+      return transformedKey ?? {};
+    }
+  };
+}
 function BaseFormComponents(props) {
   const {
     children,
@@ -55,7 +103,7 @@ function BaseFormComponents(props) {
     formComponentType,
     extraUrlParams = defaultExtraUrlParams,
     syncToUrl,
-    onUrlSearchChange,
+    onUrlSyncReset,
     onReset,
     omitNil = true,
     isKeyPressSubmit,
@@ -76,8 +124,8 @@ function BaseFormComponents(props) {
     componentSize: 'middle'
   };
 
-  /** 同步 url 上的参数 */
-  const formRef = useRef(form || formInstance);
+  /** 内部持有当前 FormInstance，供 useImperativeHandle 和 submitter 使用 */
+  const formInstanceRef = useRef(form || formInstance);
 
   /**
    * 获取布局
@@ -89,146 +137,38 @@ function BaseFormComponents(props) {
     rowProps
   });
   const getFormInstance = useRefFunction(() => formInstance);
-  const formatValues = useMemo(() => ({
-    /**
-     * 获取被 ProForm 格式化后的所有数据
-     * @param allData boolean
-     * @param omitNilParam boolean
-     * @returns T
-     *
-     * @example  getFieldsFormatValue(true) ->返回所有数据，即使没有被 form 托管的
-     */
-    getFieldsFormatValue: (allData, omitNilParam) => {
-      const formInstance = getFormInstance();
-      if (!formInstance) {
-        return {};
-      }
-      const values = formInstance.getFieldsValue(allData);
-      return transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
-    },
-    /**
-     * 获取被 ProForm 格式化后的单个数据
-     * @param nameList (string|number)[]
-     * @param omitNilParam boolean
-     * @returns T
-     *
-     * @example {a:{b:value}} -> getFieldFormatValue(['a', 'b']) -> value
-     */
-    /** 获取格式化之后的单个数据 */
-    getFieldFormatValue: (paramsNameList = [], omitNilParam) => {
-      const formInstance = getFormInstance();
-      if (!formInstance) {
-        return undefined;
-      }
-      const nameList = covertFormName(paramsNameList);
-      if (!nameList) throw new Error('nameList is require');
-      const value = formInstance.getFieldValue(nameList);
-      const obj = nameList ? set({}, nameList, value) : value;
-      //transformKey会将keys重新和nameList拼接，所以这里要将nameList的首个元素弹出
-      const newNameList = [...nameList];
-      newNameList.shift();
-      const transformed = transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, newNameList);
-      const result = get(transformed, nameList);
-      // 如果结果是对象，返回对象的值
-      if (result && typeof result === 'object' && !Array.isArray(result)) {
-        const objValue = Object.values(result)[0];
-        // 如果对象的值是数组，返回数组
-        if (Array.isArray(objValue)) {
-          return objValue;
-        }
-        return objValue;
-      }
-      return result;
-    },
-    /**
-     * 获取被 ProForm 格式化后的单个数据, 包含他的 name
-     * @param nameList (string|number)[]
-     * @param omitNilParam boolean
-     * @returns T
-     *
-     * @example  {a:{b:value}} -> getFieldFormatValueObject(['a', 'b']) -> {a:{b:value}}
-     */
-    /** 获取格式化之后的单个数据 */
-    getFieldFormatValueObject: (paramsNameList, omitNilParam) => {
-      const formInstance = getFormInstance();
-      if (!formInstance) {
-        return {};
-      }
-      const nameList = covertFormName(paramsNameList);
-      const value = formInstance.getFieldValue(nameList);
-      const obj = nameList ? set({}, nameList, value) : value;
-      return transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, nameList);
-    },
-    /** 
-    /**
-     *验字段后返回格式化之后的所有数据
-     * @param nameList (string|number)[]
-     * @param omitNilParam boolean
-     * @returns T
-     * 
-     * @example validateFieldsReturnFormatValue -> {a:{b:value}}
-     */
-    validateFieldsReturnFormatValue: async (nameList, omitNilParam) => {
-      const formInstance = getFormInstance();
-      if (!formInstance) {
-        return {};
-      }
-      if (!Array.isArray(nameList) && nameList) throw new Error('nameList must be array');
-      const values = await formInstance.validateFields(nameList);
-      const transformedKey = transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
-      return transformedKey ? transformedKey : {};
+
+  // 消除 formatValues useMemo 与 useImperativeHandle 里的重复实现，统一由 buildFormatValues 生成
+  const formatValues = useMemo(() => buildFormatValues(getFormInstance, transformKey, omitNil), [omitNil, transformKey, getFormInstance]);
+  const items = React.Children.toArray(children).map((item, index) => {
+    if (index === 0 && /*#__PURE__*/React.isValidElement(item) && autoFocusFirstInput) {
+      return autoFocusToFirstChild(item, autoFocusFirstInput);
     }
-  }), [omitNil, transformKey, getFormInstance]);
-  const items = useMemo(() => {
-    return React.Children.toArray(children).map((item, index) => {
-      if (index === 0 && /*#__PURE__*/React.isValidElement(item) && autoFocusFirstInput) {
-        return autoFocusToFirstChild(item, autoFocusFirstInput);
-      }
-      return item;
-    });
-  }, [autoFocusFirstInput, children]);
+    return item;
+  });
 
   /** 计算 props 的对象 */
-  const submitterProps = useMemo(() => typeof submitter === 'boolean' || !submitter ? {} : submitter, [submitter]);
+  const submitterProps = typeof submitter === 'boolean' || !submitter ? {} : submitter;
 
   /** 渲染提交按钮与重置按钮 */
-  const submitterNode = useMemo(() => {
-    if (submitter === false) return undefined;
-    return /*#__PURE__*/_jsx(Submitter, {
-      ...submitterProps,
-      onReset: () => {
-        const finalValues = transformKey(formRef.current?.getFieldsValue(), omitNil);
-        submitterProps?.onReset?.(finalValues);
-        onReset?.(finalValues);
-        // 如果 syncToUrl，清空一下数据
-        if (syncToUrl) {
-          // 把没有的值设置为未定义可以删掉 url 的参数
-          const params = Object.keys(transformKey(formRef.current?.getFieldsValue(), false)).reduce((pre, next) => {
-            return {
-              ...pre,
-              [next]: finalValues[next] || undefined
-            };
-          }, extraUrlParams);
-
-          /** 在同步到 url 上时对参数进行转化 */
-          onUrlSearchChange(genParams(syncToUrl, params || {}, 'set'));
-        }
-      },
-      submitButtonProps: {
-        loading,
-        ...submitterProps.submitButtonProps
-      }
-    }, "submitter");
-  }, [submitter, submitterProps, loading, transformKey, omitNil, onReset, syncToUrl, extraUrlParams, onUrlSearchChange]);
-  const content = useMemo(() => {
-    const wrapItems = grid ? /*#__PURE__*/_jsx(RowWrapper, {
-      children: items
-    }) : items;
-    if (contentRender) {
-      return contentRender(wrapItems, submitterNode, formRef.current);
+  const submitterNode = submitter === false ? undefined : /*#__PURE__*/_jsx(Submitter, {
+    ...submitterProps,
+    onReset: () => {
+      const finalValues = transformKey(formInstanceRef.current?.getFieldsValue(), omitNil);
+      submitterProps?.onReset?.(finalValues);
+      onReset?.(finalValues);
+      // 如果 syncToUrl，清空 URL 上对应的参数
+      onUrlSyncReset(finalValues, extraUrlParams);
+    },
+    submitButtonProps: {
+      loading,
+      ...submitterProps.submitButtonProps
     }
-    return wrapItems;
-  }, [grid, RowWrapper, items, contentRender, submitterNode]);
+  }, "submitter");
+  const wrapItems = grid ? /*#__PURE__*/_jsx(RowWrapper, {
+    children: items
+  }) : items;
+  const content = contentRender ? contentRender(wrapItems, submitterNode, formInstanceRef.current) : wrapItems;
   const preInitialValues = usePrevious(props.initialValues);
 
   // 提示一个 initialValues ，问的人实在是太多了
@@ -239,76 +179,22 @@ function BaseFormComponents(props) {
     noteOnce(isEqual, `The initialValues only take effect when the form is initialized, if you need to load asynchronously recommended request, or the initialValues ? <Form/> : null `);
   }, [props.initialValues]);
 
-  // 初始化给一个默认的 form
-  useImperativeHandle(propsFormRef, () => {
-    return {
-      ...formRef.current,
-      getFieldsFormatValue: (allData, omitNilParam) => {
-        const formInstance = formRef.current;
-        if (!formInstance) {
-          return {};
-        }
-        const values = formInstance.getFieldsValue(allData);
-        return transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
-      },
-      getFieldFormatValue: (paramsNameList = [], omitNilParam) => {
-        const formInstance = formRef.current;
-        if (!formInstance) {
-          return undefined;
-        }
-        const nameList = covertFormName(paramsNameList);
-        if (!nameList) throw new Error('nameList is require');
-        const value = formInstance.getFieldValue(nameList);
-        const obj = nameList ? set({}, nameList, value) : value;
-        //transformKey会将keys重新和nameList拼接，所以这里要将nameList的首个元素弹出
-        const newNameList = [...nameList];
-        newNameList.shift();
-        const transformed = transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, newNameList);
-        const result = get(transformed, nameList);
-        // 如果结果是对象，返回对象的值
-        if (result && typeof result === 'object' && !Array.isArray(result)) {
-          const objValue = Object.values(result)[0];
-          // 如果对象的值是数组，返回数组
-          if (Array.isArray(objValue)) {
-            return objValue;
-          }
-          return objValue;
-        }
-        return result;
-      },
-      getFieldFormatValueObject: (paramsNameList, omitNilParam) => {
-        const formInstance = formRef.current;
-        if (!formInstance) {
-          return {};
-        }
-        const nameList = covertFormName(paramsNameList);
-        const value = formInstance.getFieldValue(nameList);
-        const obj = nameList ? set({}, nameList, value) : value;
-        return transformKey(obj, omitNilParam !== undefined ? omitNilParam : omitNil, nameList);
-      },
-      validateFieldsReturnFormatValue: async (nameList, omitNilParam) => {
-        const formInstance = formRef.current;
-        if (!formInstance) {
-          return {};
-        }
-        if (!Array.isArray(nameList) && nameList) throw new Error('nameList must be array');
-        const values = await formInstance.validateFields(nameList);
-        const transformedKey = transformKey(values, omitNilParam !== undefined ? omitNilParam : omitNil);
-        return transformedKey ? transformedKey : {};
-      }
-    };
-  }, [omitNil, transformKey, formRef.current]);
+  // 初始化给一个默认的 form；直接复用 buildFormatValues，消除重复实现
+  useImperativeHandle(propsFormRef, () => ({
+    ...formInstanceRef.current,
+    ...buildFormatValues(() => formInstanceRef.current, transformKey, omitNil)
+  }), [omitNil, transformKey, propsFormRef]);
   useEffect(() => {
-    const finalValues = transformKey(formRef.current?.getFieldsValue?.(true), omitNil);
+    const finalValues = transformKey(formInstanceRef.current?.getFieldsValue?.(true), omitNil);
     onInit?.(finalValues, {
-      ...formRef.current,
+      ...formInstanceRef.current,
       ...formatValues
     });
   }, []);
   return /*#__PURE__*/_jsx(ProFormContext.Provider, {
     value: {
       ...formatValues,
-      formRef
+      formRef: formInstanceRef
     },
     children: /*#__PURE__*/_jsx(ConfigProvider, {
       componentSize: rest.size || componentSize,
@@ -377,7 +263,7 @@ export function BaseForm(props) {
    * 包装 setLoading，使用 queueMicrotask 延迟回调调用
    * 避免在渲染阶段调用外部回调导致的 React 警告
    */
-  const setLoading = useCallback(updater => {
+  const setLoading = useRefFunction(updater => {
     setLoadingInner(prev => {
       const next = typeof updater === 'function' ? updater(prev) : updater;
       queueMicrotask(() => {
@@ -385,13 +271,19 @@ export function BaseForm(props) {
       });
       return next;
     });
-  }, [onLoadingChangeCallback]);
-  const [urlSearch, setUrlSearch] = useUrlSearchParams({}, {
-    disabled: !syncToUrl
+  });
+  const {
+    urlParamsMergeInitialValues,
+    onUrlSyncReset,
+    onUrlSyncFinish
+  } = useUrlSync({
+    syncToUrl,
+    syncToInitialValues,
+    extraUrlParams
   });
   const curFormKey = useRef(nanoid());
   useEffect(() => {
-    requestFormCacheId += 0;
+    requestFormCacheId += 1;
   }, []);
   const [initialData, initialDataLoading] = useFetchData({
     request,
@@ -451,14 +343,6 @@ export function BaseForm(props) {
     };
   });
 
-  // 如果为 false，不需要触发设置进去
-  const [urlParamsMergeInitialValues, setUrlParamsMergeInitialValues] = useState(() => {
-    if (!syncToUrl) {
-      return {};
-    }
-    return genParams(syncToUrl, urlSearch, 'get');
-  });
-
   /** 保存 transformKeyRef，用于对表单key transform */
   const transformKeyRef = useRef({});
   const fieldsValueType = useRef({});
@@ -470,20 +354,6 @@ export function BaseForm(props) {
     }
     return transformKeySubmitValue(conversionMomentValue(values, dateFormatter, fieldsValueType.current, paramsOmitNil, parentKey), transformKeyRef.current);
   });
-  useEffect(() => {
-    if (syncToInitialValues) return;
-    setUrlParamsMergeInitialValues({});
-  }, [syncToInitialValues]);
-  const getGenParams = useRefFunction(() => {
-    return {
-      ...urlSearch,
-      ...extraUrlParams
-    };
-  });
-  useEffect(() => {
-    if (!syncToUrl) return;
-    setUrlSearch(genParams(syncToUrl, getGenParams(), 'set'));
-  }, [extraUrlParams, getGenParams, syncToUrl]);
   const getPopupContainer = useMemo(() => {
     if (typeof window === 'undefined') return undefined;
     // 如果在 drawerForm 和  modalForm 里就渲染dom到父节点里
@@ -502,35 +372,24 @@ export function BaseForm(props) {
       setLoading(true);
       const finalValues = formRef?.current?.getFieldsFormatValue?.() || {};
       const response = propRest.onFinish(finalValues);
+      let responseResult;
       if (response && typeof response === 'object' && typeof response.then === 'function') {
         try {
-          await response;
+          responseResult = await response;
         } catch (error) {
-          // 确保在 Promise 被拒绝时也重置 loading 状态
+          // Promise 被拒绝时重置 loading 并向上抛出，不同步 URL
           setLoading(false);
           throw error;
         }
-        // 只有在 Promise 成功完成时才重置 loading 状态
         setLoading(false);
       } else {
+        responseResult = response;
         setLoading(false);
       }
-      if (syncToUrl) {
-        // 把没有的值设置为未定义可以删掉 url 的参数
-        const syncToUrlParams = Object.keys(formRef?.current?.getFieldsFormatValue?.(true, false) || {}).reduce((pre, next) => {
-          return {
-            ...pre,
-            [next]: finalValues[next] ?? undefined
-          };
-        }, extraUrlParams);
-        // fix #3547: 当原先在url中存在的字段被删除时，应该将 params 中的该字段设置为 undefined,以便触发url同步删除
-        Object.keys(urlSearch).forEach(key => {
-          if (syncToUrlParams[key] !== false && syncToUrlParams[key] !== 0 && !syncToUrlParams[key]) {
-            syncToUrlParams[key] = undefined;
-          }
-        });
-        /** 在同步到 url 上时对参数进行转化 */
-        setUrlSearch(genParams(syncToUrl, syncToUrlParams, 'set'));
+      // 仅在 onFinish 返回 truthy 时才同步 URL，失败时不更新
+      if (responseResult) {
+        const allFieldKeys = Object.keys(formRef?.current?.getFieldsFormatValue?.(true, false) || {});
+        onUrlSyncFinish(finalValues, allFieldKeys, extraUrlParams);
       }
     } catch (error) {
       setLoading(false);
@@ -605,7 +464,7 @@ export function BaseForm(props) {
                 firstInput?.focus();
               };
             }
-            // 组合 urlSearch 和 initialValues
+            // 组合 urlParamsMergeInitialValues 和 initialValues
             ,
             initialValues: syncToUrlAsImportant ? {
               ...initialValues,
@@ -626,7 +485,7 @@ export function BaseForm(props) {
               transformKey: transformKey,
               autoComplete: "off",
               loading: loading || !!(request && !initialData && initialDataLoading),
-              onUrlSearchChange: setUrlSearch,
+              onUrlSyncReset: onUrlSyncReset,
               ...props,
               formRef: formRef,
               initialValues: {

package/es/form/BaseForm/Submitter/index.d.ts

@@ -7,6 +7,9 @@ export type SearchConfig = {
     /** @name 提交按钮的文本 */
     submitText?: React.ReactNode;
 };
+type ActionButtonProps = ButtonProps & {
+    preventDefault?: boolean;
+};
 export type SubmitterProps<T = Record<string, any>> = {
     /** @name 提交方法 */
     onSubmit?: (value?: T) => void;
@@ -15,13 +18,9 @@ export type SubmitterProps<T = Record<string, any>> = {
     /** @name 搜索的配置，一般用来配置文本 */
     searchConfig?: SearchConfig;
     /** @name 提交按钮的 props */
-    submitButtonProps?: false | (ButtonProps & {
-        preventDefault?: boolean;
-    });
+    submitButtonProps?: false | ActionButtonProps;
     /** @name 重置按钮的 props */
-    resetButtonProps?: false | (ButtonProps & {
-        preventDefault?: boolean;
-    });
+    resetButtonProps?: false | ActionButtonProps;
     /** @name 自定义操作的渲染 */
     render?: ((props: SubmitterProps & T & {
         submit: () => void;

package/es/form/BaseForm/Submitter/index.js

@@ -1,4 +1,3 @@
-import { omit } from '@rc-component/util';
 import { Button, Form } from 'antd';
 import React from 'react';
 import { proTheme, useIntl } from "../../../provider";
@@ -6,12 +5,31 @@ import { proTheme, useIntl } from "../../../provider";
 /** @name 用于配置操作栏 */
 import { createElement as _createElement } from "react";
 import { jsx as _jsx } from "react/jsx-runtime";
+/** 渲染单个操作按钮，消除 reset/submit 两个按钮 90% 的重复 */
+function renderActionButton(buttonProps, key, text, onAction, extraProps) {
+  // 剥离非原生 ButtonProps 的扩展字段，避免透传给 antd Button 导致警告
+  const {
+    preventDefault,
+    onClick,
+    fieldProps: _fieldProps,
+    ...restButtonProps
+  } = buttonProps;
+  return /*#__PURE__*/_createElement(Button, {
+    ...extraProps,
+    ...restButtonProps,
+    key: key,
+    onClick: e => {
+      if (!preventDefault) onAction();
+      onClick?.(e);
+    }
+  }, text);
+}
+
 /**
  * FormFooter 的组件，可以自动进行一些配置
  *
  * @param props
  */
-
 const Submitter = props => {
   const intl = useIntl();
   const form = Form.useFormInstance();
@@ -41,28 +59,14 @@ const Submitter = props => {
     submitText = intl.getMessage('tableForm.submit', '提交'),
     resetText = intl.getMessage('tableForm.reset', '重置')
   } = searchConfig;
-  /** 默认的操作的逻辑 */
   const dom = [];
   if (resetButtonProps !== false) {
-    dom.push( /*#__PURE__*/_createElement(Button, {
-      ...omit(resetButtonProps ?? {}, ['preventDefault', 'fieldProps']),
-      key: "rest",
-      onClick: e => {
-        if (!resetButtonProps?.preventDefault) reset();
-        resetButtonProps?.onClick?.(e);
-      }
-    }, resetText));
+    dom.push(renderActionButton(resetButtonProps ?? {}, 'rest', resetText, reset));
   }
   if (submitButtonProps !== false) {
-    dom.push( /*#__PURE__*/_createElement(Button, {
-      type: "primary",
-      ...omit(submitButtonProps || {}, ['preventDefault', 'fieldProps']),
-      key: "submit",
-      onClick: e => {
-        if (!submitButtonProps?.preventDefault) submit();
-        submitButtonProps?.onClick?.(e);
-      }
-    }, submitText));
+    dom.push(renderActionButton(submitButtonProps ?? {}, 'submit', submitText, submit, {
+      type: 'primary'
+    }));
   }
   const renderDom = render ? render({
     ...props,
@@ -70,16 +74,10 @@ const Submitter = props => {
     submit,
     reset
   }, dom) : dom;
-  if (!renderDom) {
-    return null;
-  }
+  if (!renderDom) return null;
   if (Array.isArray(renderDom)) {
-    if (renderDom?.length < 1) {
-      return null;
-    }
-    if (renderDom?.length === 1) {
-      return renderDom[0];
-    }
+    if (renderDom.length < 1) return null;
+    if (renderDom.length === 1) return renderDom[0];
     return /*#__PURE__*/_jsx("div", {
       style: {
         display: 'flex',

package/es/form/BaseForm/index.d.ts

@@ -1,3 +1,2 @@
 export * from '../components/FormItem/warpField';
 export * from './BaseForm';
-export * from './LightWrapper';

package/es/form/BaseForm/index.js

@@ -1,3 +1,2 @@
 export * from "../components/FormItem/warpField";
-export * from "./BaseForm";
-export * from "./LightWrapper";
+export * from "./BaseForm";

package/es/form/BaseForm/useUrlSync.d.ts

@@ -0,0 +1,42 @@
+import type { BaseFormProps } from './BaseForm';
+/**
+ * 将 syncToUrl 的 boolean | function 形式统一转为实际参数对象。
+ * 纯函数，方便单独测试。
+ */
+export declare const genUrlSyncParams: (syncUrl: BaseFormProps<any>['syncToUrl'], params: Record<string, any>, type: 'get' | 'set') => Record<string, any>;
+export type UseUrlSyncOptions<T> = {
+    syncToUrl?: boolean | ((values: T, type: 'get' | 'set') => T);
+    syncToInitialValues?: boolean;
+    extraUrlParams?: Record<string, any>;
+};
+export type UseUrlSyncResult = {
+    /** URL 参数解析后要合并到 initialValues 的值 */
+    urlParamsMergeInitialValues: Record<string, any>;
+    /**
+     * 在 Submitter.onReset 中调用，清空 URL 上的参数
+     * @param finalValues 已经经过 transformKey 处理的当前表单值
+     * @param extraUrlParams 当前的 extraUrlParams（需透传，避免闭包过期）
+     */
+    onUrlSyncReset: (finalValues: Record<string, any>, extraUrlParams?: Record<string, any>) => void;
+    /**
+     * 在 onFinish 中调用，将提交值同步写入 URL
+     * @param finalValues 已经经过 transformKey 处理的最终提交值
+     * @param allFieldKeys 表单所有字段的 key（用于补全需要置空的 key）
+     * @param extraUrlParams 当前的 extraUrlParams
+     */
+    onUrlSyncFinish: (finalValues: Record<string, any>, allFieldKeys: string[], extraUrlParams?: Record<string, any>) => void;
+};
+/**
+ * 管理 QueryFilter 等场景下 URL 参数与表单值之间的双向同步。
+ *
+ * 提取自 BaseForm，让 BaseForm 本身不需要关心 URL 同步细节。
+ *
+ * 职责：
+ * - 管理 `urlSearch` 状态（通过 `useUrlSearchParams`）
+ * - 初始化时从 URL 读取参数合并到 `initialValues`
+ * - 重置时清空 URL 参数
+ * - 提交时将表单值写入 URL
+ * - `syncToInitialValues=false` 时清空已合并的 URL 参数
+ * - `extraUrlParams` 变化时同步更新 URL
+ */
+export declare function useUrlSync<T = Record<string, any>>({ syncToUrl, syncToInitialValues, extraUrlParams, }: UseUrlSyncOptions<T>): UseUrlSyncResult;