@tmagic/form 1.8.0-beta.1 → 1.8.0-beta.3

package/src/Form.vue

@@ -22,7 +22,11 @@
         :step-active="stepActive"
         :size="size"
         @change="changeHandler"
-      ></Container>
+      >
+        <template v-if="$slots.label" #label="labelProps">
+          <slot name="label" v-bind="labelProps"></slot>
+        </template>
+      </Container>
     </template>
   </TMagicForm>
 </template>
@@ -37,12 +41,23 @@ import { setValueByKeyPath } from '@tmagic/utils';
 import Container from './containers/Container.vue';
 import { getConfig } from './utils/config';
 import { initValue } from './utils/form';
-import type { ChangeRecord, ContainerChangeEventData, FormConfig, FormState, FormValue, ValidateError } from './schema';
+import type {
+  ChangeRecord,
+  ContainerChangeEventData,
+  FormConfig,
+  FormSlots,
+  FormState,
+  FormValue,
+  ValidateError,
+} from './schema';
+import { FORM_DIFF_CONFIG_KEY } from './schema';
 
 defineOptions({
   name: 'MForm',
 });
 
+defineSlots<FormSlots>();
+
 const props = withDefaults(
   defineProps<{
     /** 表单配置 */
@@ -65,6 +80,33 @@ const props = withDefaults(
     popperClass?: string;
     preventSubmitDefault?: boolean;
     extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * 自定义"是否展示对比内容"的判断函数（仅在 `isCompare === true` 时生效）。
+     *
+     * - 不传：使用默认逻辑 `!isEqual(curValue, lastValue)`；
+     * - 传函数：完全以函数返回值为准，返回 `true` 才展示前后两份对比内容。
+     *
+     * 通过 provide 下发给所有层级的 Container（含嵌套在容器组件内部的 Container），
+     * 调用方只需在 MForm 这一层传一次即可对整棵表单生效。
+     *
+     * 典型场景：某些字段语义上相等但结构不同（例如 `code-select` 字段中 `''` 与
+     * `{ hookType: 'code', hookData: [] }` 应视为相等），调用方在此处显式声明，
+     * 避免被 lodash `isEqual` 误判为差异。
+     */
+    showDiff?: (_data: { curValue: any; lastValue: any; config: any }) => boolean;
+    /**
+     * 自定义「自接管对比」的字段类型（仅在对比模式下生效）。
+     *
+     * 自接管对比的字段不会渲染前后两份独立组件，而是只渲染一次并由字段组件内部展示前后差异
+     * （如 vs-code 使用 monaco diff 编辑器；event-select / code-select-col 等复合字段逐项展示差异）。
+     *
+     * 支持两种形式：
+     * - 传数组：在内置类型基础上「追加」这些类型；
+     * - 传函数：入参为内置类型数组，返回值作为「最终」完整列表（可完全替换内置项）。
+     *
+     * 通过 provide 下发，对整棵表单的所有层级 Container 生效，只需在 MForm 这一层传一次。
+     */
+    selfDiffFieldTypes?: string[] | ((_defaultTypes: string[]) => string[]);
   }>(),
   {
     config: () => [],
@@ -201,6 +243,17 @@ watchEffect(async (onCleanup) => {
 
 provide('mForm', formState);
 
+// 对比相关配置单独通过 provide 下发，所有层级的 Container 通过 inject 获取，无需逐层透传 prop。
+// 用 getter 对象保证读取时回到最新的 props 值，维持响应式。
+provide(FORM_DIFF_CONFIG_KEY, {
+  get showDiff() {
+    return props.showDiff;
+  },
+  get selfDiffFieldTypes() {
+    return props.selfDiffFieldTypes;
+  },
+});
+
 const changeRecords = shallowRef<ChangeRecord[]>([]);
 
 watch(

package/src/containers/Container.vue

@@ -25,13 +25,15 @@
     <template v-else-if="type && display && !showDiff">
       <TMagicFormItem v-bind="formItemProps" :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text }">
         <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
+          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <FormLabel
+              :tip="config.tip"
+              :type="type"
+              :use-label="(config as CheckboxConfig).useLabel"
+              :label-title="config.labelTitle"
+              :text="text"
+            ></FormLabel>
+          </slot>
         </template>
 
         <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
@@ -71,68 +73,126 @@
 
     <!-- 对比 -->
     <template v-else-if="type && display && showDiff">
-      <!-- 上次内容 -->
+      <!-- 自接管对比的字段类型（如 vs-code）：只渲染一次组件，由字段内部用 diff 编辑器/视图自行展示前后差异 -->
       <TMagicFormItem
+        v-if="isSelfDiffField"
         v-bind="formItemProps"
-        :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-diff': true }"
+        :class="{
+          'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text,
+          'self-diff': true,
+        }"
       >
         <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
+          <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+            <FormLabel
+              :tip="config.tip"
+              :type="type"
+              :use-label="(config as CheckboxConfig).useLabel"
+              :label-title="config.labelTitle"
+              :text="text"
+            ></FormLabel>
+          </slot>
         </template>
         <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
-          <component v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
+          <component
+            v-bind="fieldsProps"
+            :is="tagName"
+            :model="model"
+            :last-values="lastValues"
+            :is-compare="isCompare"
+            @change="onChangeHandler"
+          ></component>
           <template #content>
             <div v-html="tooltip.text"></div>
           </template>
         </TMagicTooltip>
 
-        <component v-else v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
+        <component
+          v-else
+          v-bind="fieldsProps"
+          :is="tagName"
+          :model="model"
+          :last-values="lastValues"
+          :is-compare="isCompare"
+          @change="onChangeHandler"
+        ></component>
       </TMagicFormItem>
 
-      <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
-        <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
-        <template #content>
-          <div v-html="config.tip"></div>
-        </template>
-      </TMagicTooltip>
+      <!-- 普通字段：渲染前后两份独立的组件用于对比 -->
+      <template v-else>
+        <!-- 上次内容 -->
+        <TMagicFormItem
+          v-bind="formItemProps"
+          :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-before-diff': true }"
+        >
+          <template #label>
+            <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+              <FormLabel
+                :tip="config.tip"
+                :type="type"
+                :use-label="(config as CheckboxConfig).useLabel"
+                :label-title="config.labelTitle"
+                :text="text"
+              ></FormLabel>
+            </slot>
+          </template>
+          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+            <component v-bind="fieldsProps" :is="tagName" :model="lastValues" @change="onChangeHandler"></component>
+            <template #content>
+              <div v-html="tooltip.text"></div>
+            </template>
+          </TMagicTooltip>
 
-      <!-- 当前内容 -->
-      <TMagicFormItem
-        v-bind="formItemProps"
-        :style="config.tip ? 'flex: 1' : ''"
-        :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-diff': true }"
-      >
-        <template #label>
-          <FormLabel
-            :tip="config.tip"
-            :type="type"
-            :use-label="(config as CheckboxConfig).useLabel"
-            :label-title="config.labelTitle"
-            :text="text"
-          ></FormLabel>
-        </template>
-        <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
-          <component v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+          <component
+            v-else
+            v-bind="fieldsProps"
+            :is="tagName"
+            :model="lastValues"
+            @change="onChangeHandler"
+          ></component>
+        </TMagicFormItem>
+
+        <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
+          <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
           <template #content>
-            <div v-html="tooltip.text"></div>
+            <div v-html="config.tip"></div>
           </template>
         </TMagicTooltip>
 
-        <component v-else v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
-      </TMagicFormItem>
-
-      <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
-        <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
-        <template #content>
-          <div v-html="config.tip"></div>
-        </template>
-      </TMagicTooltip>
+        <!-- 当前内容 -->
+        <TMagicFormItem
+          v-bind="formItemProps"
+          :style="config.tip ? 'flex: 1' : ''"
+          :class="{ 'tmagic-form-hidden': `${itemLabelWidth}` === '0' || !text, 'show-after-diff': true }"
+        >
+          <template #label>
+            <slot name="label" :config="config" :type="type" :text="text" :prop="itemProp" :disabled="disabled">
+              <FormLabel
+                :tip="config.tip"
+                :type="type"
+                :use-label="(config as CheckboxConfig).useLabel"
+                :label-title="config.labelTitle"
+                :text="text"
+              ></FormLabel>
+            </slot>
+          </template>
+          <TMagicTooltip v-if="tooltip.text" :placement="tooltip.placement">
+            <component v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+            <template #content>
+              <div v-html="tooltip.text"></div>
+            </template>
+          </TMagicTooltip>
+
+          <component v-else v-bind="fieldsProps" :is="tagName" :model="model" @change="onChangeHandler"></component>
+        </TMagicFormItem>
+
+        <TMagicTooltip v-if="config.tip && type === 'checkbox' && !(config as CheckboxConfig).useLabel" placement="top">
+          <TMagicIcon style="line-height: 40px; margin-left: 5px"><warning-filled /></TMagicIcon>
+          <template #content>
+            <div v-html="config.tip"></div>
+          </template>
+        </TMagicTooltip>
+      </template>
     </template>
 
     <template v-else-if="items && display">
@@ -152,7 +212,11 @@
           :prop="itemProp"
           @change="onChangeHandler"
           @addDiffCount="onAddDiffCount"
-        ></Container>
+        >
+          <template v-if="$slots.label" #label="labelProps">
+            <slot name="label" v-bind="labelProps"></slot>
+          </template>
+        </Container>
       </template>
     </template>
 
@@ -178,11 +242,14 @@ import type {
   ComponentConfig,
   ContainerChangeEventData,
   ContainerCommonConfig,
+  FormDiffConfig,
   FormItemConfig,
+  FormSlots,
   FormState,
   FormValue,
   ToolTipConfigType,
 } from '../schema';
+import { FORM_DIFF_CONFIG_KEY } from '../schema';
 import { getField } from '../utils/config';
 import { createObjectProp, display as displayFunction, filterFunction, getRules } from '../utils/form';
 
@@ -192,6 +259,8 @@ defineOptions({
   name: 'MFormContainer',
 });
 
+defineSlots<FormSlots>();
+
 const props = withDefaults(
   defineProps<{
     /** 表单值 */
@@ -224,14 +293,30 @@ const emit = defineEmits<{
 
 const mForm = inject<FormState | undefined>('mForm');
 
+// 对比相关配置由 MForm 通过 provide 下发，这里直接 inject，无需逐层透传 prop。
+const diffConfig = inject<FormDiffConfig>(FORM_DIFF_CONFIG_KEY, {});
+
 const expand = ref(false);
 
 const name = computed(() => props.config.name || '');
+
 // 是否展示两个版本的对比内容
+//
+// 默认逻辑：在对比模式下用 lodash isEqual 比较当前值与历史值，不相等则展示对比。
+// 若调用方通过 MForm 的 `showDiff` 注入了自定义判断函数，则完全以其返回值为准，
+// 便于业务侧自定义"语义上相等"的特殊场景（例如空字符串与空 hook 结构）。
 const showDiff = computed(() => {
   if (!props.isCompare) return false;
-  const curValue = name.value ? props.model[name.value] : props.model;
-  const lastValue = name.value ? props.lastValues[name.value] : props.lastValues;
+  if (!name.value) return false;
+
+  const curValue = props.model[name.value];
+  const lastValue = props.lastValues[name.value];
+
+  const customShowDiff = diffConfig.showDiff;
+  if (typeof customShowDiff === 'function') {
+    return Boolean(customShowDiff({ curValue, lastValue, config: props.config }));
+  }
+
   return !isEqual(curValue, lastValue);
 });
 
@@ -268,6 +353,45 @@ const tagName = computed(() => {
   return getField(type.value || 'container') || `m-${items.value ? 'form' : 'fields'}-${type.value}`;
 });
 
+/**
+ * 自接管对比的字段类型白名单。
+ *
+ * 这类字段在 `isCompare === true` 且存在差异时，不再由 Container 渲染前后两份独立组件来对比，
+ * 而是只渲染一次组件，将 `model` / `lastValues` / `isCompare` 一并传给字段组件，
+ * 由字段组件内部自行展示前后差异（典型场景：vs-code 字段使用 monaco 自带的 diff 编辑器）。
+ *
+ * 这样做的好处：
+ * 1. 避免重型字段（如 monaco 编辑器）在对比模式下被实例化两次，节省资源；
+ * 2. 提供更专业的对比视觉效果（如 monaco diff 的行级高亮、左右滚动同步等）。
+ *
+ * 注意：像 `event-select` / `code-select-col` 这类内部由列表 / 嵌套子表单组成的复合字段，若按默认逻辑
+ * 渲染前后两份独立组件，会出现两套下拉框 + 两份参数表单（或两套「添加事件」按钮、两份完整面板），
+ * 体验很差。这类字段在内部把 `is-compare`/`lastValues` 透传给子级容器，由子级逐项展示差异，
+ * 因此同样归类为自接管对比字段。
+ */
+const DEFAULT_SELF_DIFF_FIELD_TYPES = ['vs-code', 'event-select', 'code-select-col', 'code-select'];
+
+// 最终生效的自接管对比字段类型集合。
+//
+// - 未自定义：使用内置默认类型；
+// - 自定义传数组：在内置类型基础上「追加」；
+// - 自定义传函数：以函数返回值为「最终」完整列表（可完全替换内置项）。
+const effectiveSelfDiffFieldTypes = computed<Set<string>>(() => {
+  const custom = diffConfig.selfDiffFieldTypes;
+
+  if (typeof custom === 'function') {
+    return new Set(custom([...DEFAULT_SELF_DIFF_FIELD_TYPES]));
+  }
+
+  if (Array.isArray(custom)) {
+    return new Set([...DEFAULT_SELF_DIFF_FIELD_TYPES, ...custom]);
+  }
+
+  return new Set(DEFAULT_SELF_DIFF_FIELD_TYPES);
+});
+
+const isSelfDiffField = computed(() => effectiveSelfDiffFieldTypes.value.has(type.value));
+
 const disabled = computed(() => props.disabled || filterFunction(mForm, props.config.disabled, props));
 
 const text = computed(() => filterFunction(mForm, props.config.text, props));

package/src/containers/Fieldset.vue

@@ -7,11 +7,11 @@
         :true-value="checkboxTrueValue"
         :false-value="checkboxFalseValue"
         @update:modelValue="valueChangeHandler"
-        ><span v-html="config.legend"></span><span v-if="config.extra" v-html="config.extra" class="m-form-tip"></span
+        ><span v-html="legend"></span><span v-if="config.extra" v-html="config.extra" class="m-form-tip"></span
       ></TMagicCheckbox>
     </component>
     <legend v-else>
-      <span v-html="config.legend"></span>
+      <span v-html="legend"></span>
       <span v-if="config.extra" v-html="config.extra" class="m-form-tip"></span>
     </legend>
 
@@ -63,6 +63,7 @@ import { computed, inject } from 'vue';
 import { TMagicCheckbox } from '@tmagic/design';
 
 import { ContainerChangeEventData, FieldsetConfig, FormState } from '../schema';
+import { filterFunction } from '../utils/form';
 
 import Container from './Container.vue';
 
@@ -99,6 +100,8 @@ const mForm = inject<FormState | undefined>('mForm');
 
 const name = computed(() => props.config.name || '');
 
+const legend = computed(() => filterFunction<string>(mForm, props.config.legend, props));
+
 const checkboxName = computed(() => {
   if (typeof props.config.checkbox === 'object' && typeof props.config.checkbox.name === 'string') {
     return props.config.checkbox.name;

package/src/containers/GroupList.vue

@@ -26,7 +26,7 @@
       @addDiffCount="onAddDiffCount()"
     ></MFieldsGroupListItem>
 
-    <div class="m-fields-group-list-footer">
+    <div class="m-fields-group-list-footer" v-if="!isCompare">
       <slot name="toggle-button"></slot>
       <div style="display: flex; justify-content: flex-end; flex: 1">
         <slot name="add-button"></slot>

package/src/containers/GroupListItem.vue

@@ -7,6 +7,7 @@
         </TMagicButton>
 
         <TMagicButton
+          v-if="!isCompare"
           v-show="showDelete"
           type="danger"
           size="small"
@@ -17,7 +18,7 @@
         ></TMagicButton>
 
         <TMagicButton
-          v-if="copyable"
+          v-if="copyable && !isCompare"
           link
           size="small"
           type="primary"
@@ -27,7 +28,7 @@
           >复制</TMagicButton
         >
 
-        <template v-if="movable">
+        <template v-if="movable && !isCompare">
           <TMagicButton
             v-show="index !== 0"
             link
@@ -49,7 +50,7 @@
         </template>
 
         <TMagicPopover
-          v-if="config.moveSpecifyLocation"
+          v-if="config.moveSpecifyLocation && !isCompare"
           trigger="click"
           placement="top"
           width="200"

package/src/containers/Tabs.vue

@@ -19,7 +19,10 @@
       :is="tabPaneComponent?.component || 'el-tab-pane'"
       :key="tab[mForm?.keyProp || '__key'] ?? tabIndex"
       v-bind="
-        tabPaneComponent?.props({ name: filter(tab.status) || tabIndex.toString(), lazy: tab.lazy || false }) || {}
+        tabPaneComponent?.props({
+          name: filter(tab.status) || tabIndex.toString(),
+          lazy: isCompare ? false : tab.lazy || false,
+        }) || {}
       "
     >
       <template #label>
@@ -76,7 +79,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, inject, ref, watchEffect } from 'vue';
+import { computed, inject, ref, watch, watchEffect } from 'vue';
 import { isEmpty } from 'lodash-es';
 
 import { getDesignConfig, TMagicBadge } from '@tmagic/design';
@@ -172,6 +175,11 @@ watchEffect(() => {
   }
 });
 
+// model 或 lastValues 变化时，重置差异数
+watch([() => props.model, () => props.lastValues], () => {
+  diffCount.value = {};
+});
+
 const tabItems = (tab: TabPaneConfig) => (props.config.dynamic ? props.config.items : tab.items);
 
 const tabClickHandler = (tab: any) => {

package/src/containers/table/Table.vue

@@ -44,7 +44,7 @@
               {{ isFullscreen ? '退出全屏' : '全屏编辑' }}
             </TMagicButton>
             <TMagicUpload
-              v-if="importable"
+              v-if="importable && !isCompare"
               style="display: inline-block"
               ref="excelBtn"
               action="/noop"
@@ -54,11 +54,17 @@
             >
               <TMagicButton size="small" type="success" :disabled="disabled" plain>导入EXCEL</TMagicButton>
             </TMagicUpload>
-            <TMagicButton v-if="importable" size="small" type="warning" :disabled="disabled" plain @click="clearHandler"
+            <TMagicButton
+              v-if="importable && !isCompare"
+              size="small"
+              type="warning"
+              :disabled="disabled"
+              plain
+              @click="clearHandler"
               >清空</TMagicButton
             >
           </div>
-          <slot name="add-button"></slot>
+          <slot name="add-button" v-if="!isCompare"></slot>
         </div>
 
         <div class="bottom" style="text-align: right" v-if="config.pagination">

package/src/schema.ts

@@ -1,5 +1,33 @@
+import type { InjectionKey } from 'vue';
+
+import type { FormItemConfig } from '@tmagic/form-schema';
+
 export * from '@tmagic/form-schema';
 
+/**
+ * 对比模式相关配置，由 `MForm` 通过 `provide` 注入，
+ * 所有层级的 Container（含嵌套在 fieldset / panel 等容器组件内部的 Container）通过 `inject` 获取，
+ * 无需逐层透传 prop。
+ */
+export interface FormDiffConfig {
+  /**
+   * 自定义"是否展示对比内容"的判断函数（仅在对比模式下生效）。
+   *
+   * - 不传：使用默认逻辑 `!isEqual(curValue, lastValue)`；
+   * - 传函数：完全以函数返回值为准，返回 `true` 才展示前后两份对比内容。
+   */
+  showDiff?: (_data: { curValue: any; lastValue: any; config: FormItemConfig }) => boolean;
+  /**
+   * 自定义「自接管对比」的字段类型（仅在对比模式下生效）。
+   *
+   * - 传数组：在内置类型基础上「追加」这些类型；
+   * - 传函数：入参为内置类型数组，返回值作为「最终」完整类型列表（可完全替换内置项）。
+   */
+  selfDiffFieldTypes?: string[] | ((_defaultTypes: string[]) => string[]);
+}
+
+export const FORM_DIFF_CONFIG_KEY: InjectionKey<FormDiffConfig> = Symbol('mFormDiffConfig');
+
 export interface ValidateError {
   message: string;
   field: string;
@@ -14,3 +42,22 @@ export interface ContainerChangeEventData {
   modifyKey?: string;
   changeRecords?: ChangeRecord[];
 }
+
+/** 自定义 label slot 的作用域参数 */
+export interface FormLabelSlotProps {
+  /** 当前表单项配置 */
+  config: FormItemConfig;
+  /** 经处理后的类型 */
+  type: string;
+  /** 经 filterFunction 处理后的 label 文案 */
+  text?: string;
+  /** 完整字段路径（包含父级前缀） */
+  prop: string;
+  /** 经 filterFunction 处理后的最终禁用状态 */
+  disabled?: boolean;
+}
+
+/** Form / Container 暴露的具名 slot 定义 */
+export interface FormSlots {
+  label(_props: FormLabelSlotProps): any;
+}

package/src/submitForm.ts

@@ -19,7 +19,7 @@
 import { type AppContext, type Component, createApp, defineComponent, h, nextTick, ref, watch } from 'vue';
 
 import Form from './Form.vue';
-import type { FormConfig, FormState } from './schema';
+import type { ChangeRecord, FormConfig, FormState } from './schema';
 
 // #region SubmitFormOptions
 /**
@@ -48,6 +48,11 @@ export interface SubmitFormOptions {
   extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
   /** 透传给 Form.submitForm 的参数：是否直接返回原始响应式 values */
   native?: boolean;
+  /**
+   * 是否在 resolve 结果中携带 changeRecords（变更记录）。
+   * 开启后 resolve 的结果为 `{ values, changeRecords }`，否则仅 resolve values。
+   */
+  returnChangeRecords?: boolean;
   /**
    * 父级应用上下文，用于继承全局组件、指令、provide 等。
    * 通常通过 `app._context` 或 `getCurrentInstance()?.appContext` 获取。
@@ -58,6 +63,18 @@ export interface SubmitFormOptions {
 }
 // #endregion SubmitFormOptions
 
+// #region SubmitFormResult
+/**
+ * 开启 `returnChangeRecords` 时 submitForm 的返回结果
+ */
+export interface SubmitFormResult {
+  /** 校验通过后的表单值 */
+  values: any;
+  /** 表单变更记录 */
+  changeRecords: ChangeRecord[];
+}
+// #endregion SubmitFormResult
+
 /**
  * 以命令式方式调用 Form.vue 完成一次表单校验/提交。
  *
@@ -78,10 +95,17 @@ export interface SubmitFormOptions {
  * } catch (e) {
  *   console.error(e);
  * }
+ *
+ * // 需要同时获取变更记录时：
+ * const { values, changeRecords } = await submitForm({
+ *   config: [...],
+ *   initValues: { name: 'foo' },
+ *   returnChangeRecords: true,
+ * });
  * ```
  */
 export const submitForm = (options: SubmitFormOptions): Promise<any> => {
-  const { native, appContext, timeout = 10000, ...formProps } = options;
+  const { native, appContext, timeout = 10000, returnChangeRecords, ...formProps } = options;
 
   return new Promise((resolve, reject) => {
     const container = document.createElement('div');
@@ -105,8 +129,10 @@ export const submitForm = (options: SubmitFormOptions): Promise<any> => {
             try {
               // 等待子组件（FormItem 等）完成首次渲染，确保 validate 能拿到所有字段
               await nextTick();
+              // submitForm 校验通过后会清空 changeRecords，需在调用前先做快照
+              const changeRecords: ChangeRecord[] = [...(formRef.value.changeRecords ?? [])];
               const result = await formRef.value.submitForm(native);
-              resolve(result);
+              resolve(returnChangeRecords ? { values: result, changeRecords } : result);
             } catch (err) {
               reject(err);
             } finally {