From 0936861da18b7096fad92ef2accd0d50aadc4902 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 16 Apr 2025 11:29:01 +0800
Subject: [PATCH] feat:  pass `fieldsChanged`  into the `handleValuesChange`
 callback function (#5968)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fieldsChanged(已被改变值的字段名)将传入handleValuesChange回调函数
---
 docs/src/components/common-ui/vben-form.md    |  8 +++-
 packages/@core/ui-kit/form-ui/src/types.ts    |  5 ++-
 .../ui-kit/form-ui/src/vben-use-form.vue      | 40 ++++++++++++++++---
 playground/src/views/examples/form/basic.vue  |  3 ++
 4 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/docs/src/components/common-ui/vben-form.md b/docs/src/components/common-ui/vben-form.md
index 616d17ce..5c6cf58e 100644
--- a/docs/src/components/common-ui/vben-form.md
+++ b/docs/src/components/common-ui/vben-form.md
@@ -310,7 +310,7 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 | actionWrapperClass | 表单操作区域class | `any` | - |
 | handleReset | 表单重置回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
 | handleSubmit | 表单提交回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
-| handleValuesChange | 表单值变化回调 | `(values: Record<string, any>,) => void` | - |
+| handleValuesChange | 表单值变化回调 | `(values: Record<string, any>, fieldsChanged: string[]) => void` | - |
 | actionButtonsReverse | 调换操作按钮位置 | `boolean` | `false` |
 | resetButtonOptions | 重置按钮组件参数 | `ActionButtonOptions` | - |
 | submitButtonOptions | 提交按钮组件参数 | `ActionButtonOptions` | - |
@@ -325,6 +325,12 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 | submitOnChange | 字段值改变时提交表单(内部防抖，这个属性一般用于表格的搜索表单) | `boolean` | false |
 | compact | 是否紧凑模式(忽略为校验信息所预留的空间) | `boolean` | false |
 
+::: tip handleValuesChange
+
+`handleValuesChange` 回调函数的第一个参数`values`装载了表单改变后的当前值对象，第二个参数`fieldsChanged`是一个数组，包含了所有被改变的字段名。注意：第二个参数仅在v5.5.4(不含)以上版本可用。
+
+:::
+
 ::: tip fieldMappingTime
 
 此属性用于将表单内的数组值映射成 2 个字段，它应当传入一个数组，数组的每一项是一个映射规则，规则的第一个成员是一个字符串，表示需要映射的字段名，第二个成员是一个数组，表示映射后的字段名，第三个成员是一个可选的格式掩码，用于格式化日期时间字段；也可以提供一个格式化函数（参数分别为当前值和当前字段名，返回格式化后的值）。如果明确地将格式掩码设为null，则原值映射而不进行格式化（适用于非日期时间字段）。例如：`[['timeRange', ['startTime', 'endTime'], 'YYYY-MM-DD']]`，`timeRange`应当是一个至少具有2个成员的数组类型的值。Form会将`timeRange`的值前两个值分别按照格式掩码`YYYY-MM-DD`格式化后映射到`startTime`和`endTime`字段上。每一项的第三个参数是一个可选的格式掩码，
diff --git a/packages/@core/ui-kit/form-ui/src/types.ts b/packages/@core/ui-kit/form-ui/src/types.ts
index da706591..34312ae7 100644
--- a/packages/@core/ui-kit/form-ui/src/types.ts
+++ b/packages/@core/ui-kit/form-ui/src/types.ts
@@ -378,7 +378,10 @@ export interface VbenFormProps<
   /**
    * 表单值变化回调
    */
-  handleValuesChange?: (values: Record<string, any>) => void;
+  handleValuesChange?: (
+    values: Record<string, any>,
+    fieldsChanged: string[],
+  ) => void;
   /**
    * 重置按钮参数
    */
diff --git a/packages/@core/ui-kit/form-ui/src/vben-use-form.vue b/packages/@core/ui-kit/form-ui/src/vben-use-form.vue
index f22053cd..4a39c5bd 100644
--- a/packages/@core/ui-kit/form-ui/src/vben-use-form.vue
+++ b/packages/@core/ui-kit/form-ui/src/vben-use-form.vue
@@ -1,12 +1,13 @@
 <script setup lang="ts">
+import type { Recordable } from '@vben-core/typings';
+
 import type { ExtendedFormApi, VbenFormProps } from './types';
 
 // import { toRaw, watch } from 'vue';
 import { nextTick, onMounted, watch } from 'vue';
-// import { isFunction } from '@vben-core/shared/utils';
 
 import { useForwardPriorityValues } from '@vben-core/composables';
-import { cloneDeep } from '@vben-core/shared/utils';
+import { cloneDeep, get, isEqual, set } from '@vben-core/shared/utils';
 
 import { useDebounceFn } from '@vueuse/core';
 
@@ -61,16 +62,43 @@ function handleKeyDownEnter(event: KeyboardEvent) {
 }
 
 const handleValuesChangeDebounced = useDebounceFn(async () => {
-  forward.value.handleValuesChange?.(
-    cloneDeep(await forward.value.formApi.getValues()),
-  );
   state.value.submitOnChange && forward.value.formApi?.validateAndSubmitForm();
 }, 300);
 
+const valuesCache: Recordable<any> = {};
+
 onMounted(async () => {
   // 只在挂载后开始监听，form.values会有一个初始化的过程
   await nextTick();
-  watch(() => form.values, handleValuesChangeDebounced, { deep: true });
+  watch(
+    () => form.values,
+    (newVal) => {
+      if (forward.value.handleValuesChange) {
+        const fields = state.value.schema?.map((item) => {
+          return item.fieldName;
+        });
+
+        if (fields && fields.length > 0) {
+          const changedFields: string[] = [];
+          fields.forEach((field) => {
+            const newFieldValue = get(newVal, field);
+            const oldFieldValue = get(valuesCache, field);
+            if (!isEqual(newFieldValue, oldFieldValue)) {
+              changedFields.push(field);
+              set(valuesCache, field, newFieldValue);
+            }
+          });
+
+          if (changedFields.length > 0) {
+            // 调用handleValuesChange回调，传入所有表单值的深拷贝和变更的字段列表
+            forward.value.handleValuesChange(cloneDeep(newVal), changedFields);
+          }
+        }
+      }
+      handleValuesChangeDebounced();
+    },
+    { deep: true },
+  );
 });
 </script>
 
diff --git a/playground/src/views/examples/form/basic.vue b/playground/src/views/examples/form/basic.vue
index 75e868d8..b98ace26 100644
--- a/playground/src/views/examples/form/basic.vue
+++ b/playground/src/views/examples/form/basic.vue
@@ -42,6 +42,9 @@ const [BaseForm, baseFormApi] = useVbenForm({
   fieldMappingTime: [['rangePicker', ['startTime', 'endTime'], 'YYYY-MM-DD']],
   // 提交函数
   handleSubmit: onSubmit,
+  handleValuesChange(_values, fieldsChanged) {
+    message.info(`表单以下字段发生变化：${fieldsChanged.join('，')}`);
+  },
 
   // 垂直布局，label和input在不同行，值为vertical
   // 水平布局，label和input在同一行