@qin-ui/antd-vue-pro 2.3.4 → 2.4.1

package/src/components/form/components/BaseField/index.vue

@@ -33,9 +33,10 @@ import {
   inject,
   mergeProps,
   ref,
+  toValue,
   useAttrs,
 } from 'vue';
-import { cloneDeep, omit } from '../../../../shared/core';
+import { cloneDeep } from '../../../../shared/core';
 import {
   useInjectDisabled,
   useInjectFormItemContext,
@@ -43,9 +44,12 @@ import {
 import type { Field } from '../../types';
 import { ContainerFragment, SlotComponent } from '..';
 import { componentMap, InjectionFormSlotsKey } from '../../constants';
-import { INJECT_COMPONENTS } from '../../../component-provider/constants';
+import {
+  INJECT_COMPONENTS,
+  getInjectConfig,
+} from '../../../component-provider/constants';
 import { useForm } from '../../hooks/useForm';
-import { getInitProps } from './utils';
+import { getInitProps, warnUnknownComponent } from './utils';
 import { useLocale } from '../../../../locale';
 
 defineOptions({ name: 'BaseField', inheritAttrs: false });
@@ -54,12 +58,14 @@ type Props = {
   component?: string | Component;
   path?: string;
 };
-const { component = undefined, path = '' } = defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  component: undefined,
+  path: '',
+});
 
 const { t } = useLocale();
 
 const form = useForm(false);
-const { getFormData, setFormData } = form;
 
 const componentRef = ref<any>();
 
@@ -70,14 +76,23 @@ const triggerFormItemChange = () => {
 
 const attrs: any = useAttrs();
 
-function getOldValue() {
-  return cloneDeep(getFormData?.(path));
-}
+// 全局默认配置注入：key = 组件名 + picker 修饰段；inject 须在 setup 同步期调用
+const pickerVal = attrs.picker;
+const injectConfigKey =
+  typeof props.component === 'string'
+    ? [props.component, pickerVal].filter(Boolean).join('.')
+    : '';
+const componentInjectConfig = injectConfigKey
+  ? getInjectConfig(injectConfigKey)
+  : undefined;
+const rawInjectComponentProps = componentInjectConfig
+  ? inject(componentInjectConfig.injectionKey, componentInjectConfig.default)
+  : undefined;
 
 // setter: 向 formData 写入值，支持 valueFormatter / valueFormatter.set 转换
 const value = computed({
   get() {
-    let val = getFormData?.(path);
+    let val = form.getFormData?.(props.path);
     const { valueFormatter } = groupedAttrs.value;
     if (
       typeof valueFormatter === 'object' &&
@@ -90,14 +105,23 @@ const value = computed({
   set(val) {
     let newVal = val;
     const { valueFormatter } = groupedAttrs.value;
-    if (valueFormatter) {
-      if (typeof valueFormatter === 'function') {
-        newVal = valueFormatter(val, getOldValue());
-      } else if (typeof valueFormatter.set === 'function') {
-        newVal = valueFormatter.set(val, getOldValue());
-      }
+    const setFormatter =
+      typeof valueFormatter === 'function'
+        ? valueFormatter
+        : typeof valueFormatter === 'object' &&
+            typeof valueFormatter?.set === 'function'
+          ? valueFormatter.set
+          : undefined;
+
+    if (setFormatter) {
+      // 仅当 set 转换函数需要旧值参数时，才获取旧值上下文
+      const oldVal =
+        setFormatter.length > 1
+          ? cloneDeep(form.getFormData?.(props.path))
+          : undefined;
+      newVal = setFormatter(val, oldVal);
     }
-    setFormData?.(path, newVal);
+    form.setFormData?.(props.path, newVal);
     triggerFormItemChange();
   },
 });
@@ -109,28 +133,24 @@ const parentDisabled = useInjectDisabled();
  * 属性分为三类：绑定属性（v-model）、组件属性（传递给组件）、插槽（动态渲染）
  */
 const groupedAttrs = computed(() => {
+  const currentInjectProps = toValue(rawInjectComponentProps) || {};
   const initProps = getInitProps(
-    {
-      component: component,
-      picker: attrs.picker,
-    } as Field,
+    { component: props.component, picker: attrs.picker } as Field,
+    currentInjectProps,
     t
   );
+  const effectiveModelProp = attrs.modelProp ?? initProps.modelProp ?? 'value';
   const mergedProps = mergeProps(
     initProps,
     attrs,
     { class: attrs.componentClass, style: attrs.componentStyle },
-    { class: initProps.componentClass, style: initProps.componentStyle },
     { disabled: attrs.disabled ?? parentDisabled.value ?? initProps.disabled },
-    { modelProp: attrs.modelProp ?? initProps.modelProp ?? 'value' }
+    { modelProp: effectiveModelProp }
   ) as Required<Field>;
 
   // prettier-ignore
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, ...rest } = mergedProps
-
-  // 从剩余属性中移除 v-model 绑定属性，避免重复绑定
-  const bindAttrs = omit(rest, [modelProp, `onUpdate:${modelProp}`]);
+  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, [effectiveModelProp]: _modelVal, [`onUpdate:${effectiveModelProp}`]: _onUpdateModelVal, ...bindAttrs } = mergedProps as any;
 
   return {
     attrs: bindAttrs,
@@ -154,16 +174,17 @@ const customComponents = inject(INJECT_COMPONENTS, {});
  * ProForm 插槽 → 自定义组件映射 → 内置组件映射 → 原始 component 值
  */
 const is = computed(() => {
-  const teleportSlot = path && formSlots?.[path];
+  const teleportSlot = props.path && formSlots?.[props.path];
   if (teleportSlot) return teleportSlot;
-  if (typeof component === 'string') {
-    return (
-      (customComponents as any)[component] ||
-      (componentMap as any)[component] ||
-      component
-    );
+  if (typeof props.component === 'string') {
+    const resolved =
+      toValue(customComponents as any)?.[props.component] ||
+      (componentMap as any)[props.component];
+    if (resolved) return resolved;
+    warnUnknownComponent(props.component);
+    return props.component;
   }
-  return component;
+  return props.component;
 });
 
 defineExpose({
@@ -173,21 +194,24 @@ defineExpose({
 </script>
 
 <template>
-  <ContainerFragment :component="groupedAttrs.componentContainer" :path="path">
+  <ContainerFragment
+    :component="groupedAttrs.componentContainer"
+    :path="props.path"
+  >
     <component
       :is="is"
       v-if="is"
       v-bind="groupedAttrs.attrs"
       ref="componentRef"
       v-model:[`${groupedAttrs.modelProp}`]="value"
-      :path="path"
+      :path="props.path"
     >
       <template
         v-for="(slot, name) in groupedAttrs.slots"
         :key="name"
         #[name]="scoped"
       >
-        <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+        <SlotComponent :path="props.path" v-bind="scoped" :component="slot" />
       </template>
     </component>
   </ContainerFragment>

package/src/components/form/components/BaseField/utils/index.ts

@@ -1,6 +1,4 @@
 import { Field } from '../../../types';
-import { getInjectConfig } from '../../../../component-provider/constants';
-import { inject } from 'vue';
 
 type LocaleT = (
   key: string,
@@ -17,11 +15,7 @@ const PLACEHOLDER_KEYS: Record<string, string> = {
   cascader: 'select.placeholder',
 };
 
-/**
- * 根据组件 key 兜底生成 locale 占位符
- *
- * @description 用户通过 componentVars 或字段属性显式设置了占位符时不再兜底。
- */
+/** 根据组件 key 兜底生成 locale 占位符；已显式设置占位符（componentVars 或字段属性）时不兜底 */
 const getPlaceholderProps = (
   key: string,
   injectProps: Record<string, any>,
@@ -32,15 +26,27 @@ const getPlaceholderProps = (
   return { placeholder: t(placeholderKey) };
 };
 
-export const getInitProps = (field: Field, t: LocaleT): Record<string, any> => {
+export const getInitProps = (
+  field: Field,
+  injectProps: Record<string, any> = {},
+  t: LocaleT
+): Record<string, any> => {
   const { component } = field as any;
   const picker = component === 'date-picker' ? '' : (field as any).picker;
   if (typeof component === 'string') {
     const k = [component, picker].filter(Boolean).join('.');
-    const config = getInjectConfig(k);
-    if (!config) return getPlaceholderProps(k, {}, t);
-    const injectProps = inject(config.injectionKey, config.default);
     return { ...injectProps, ...getPlaceholderProps(k, injectProps, t) };
   }
   return {};
 };
+
+/** 已告警过的未知组件名（模块级去重，避免 computed 重算导致刷屏） */
+const warnedUnknownComponents = new Set<string>();
+
+export function warnUnknownComponent(name: string) {
+  if (warnedUnknownComponents.has(name)) return;
+  warnedUnknownComponents.add(name);
+  console.warn(
+    `[pro-components] 未识别的组件类型 "${name}"，已降级为原生元素渲染。如为自定义组件请在 componentMap 或 ProComponentProvider 中注册。`
+  );
+}

package/src/components/form/components/BaseFormItem/index.vue

@@ -31,7 +31,7 @@ import {
   GridProps,
   useProviderDisabled,
 } from '../../../../shared/ui';
-import { computed, inject, toValue } from 'vue';
+import { computed, inject, toRaw, toValue } from 'vue';
 import type { Fields, Grid } from '../../types';
 import { BaseField, SlotComponent, ContainerFragment } from '..';
 import { useGroupFieldAttrs } from '../../hooks/useGroupFieldAttrs';
@@ -44,49 +44,65 @@ type Props = {
   fields?: Fields;
   disabled?: boolean;
 };
-const {
-  grid = undefined,
-  fields = [],
-  disabled = undefined,
-} = defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  grid: undefined,
+  fields: () => [],
+  disabled: undefined,
+});
 
-const validFields = computed(() => fields.filter?.(field => !field.hidden));
+const validFields = computed(() =>
+  // hidden 支持 Ref/ComputedRef/getter 等响应式形态（统一使用 toValue 取值）
+  (props.fields ?? []).filter(field => !toValue(field.hidden))
+);
 
-useProviderDisabled(computed(() => disabled));
+useProviderDisabled(computed(() => props.disabled));
 
 const config = INJECT_CONFIG['pro-form'];
-
-const { grid: injectGrid } = inject(config.injectionKey, config.default);
+const injectFormConfig = inject(config.injectionKey, config.default);
+const injectGrid = computed(() => toValue(injectFormConfig)?.grid);
 
 const enableGrid = computed(() => {
-  if (grid !== undefined) return !!grid;
-  return !!injectGrid;
+  if (props.grid !== undefined) return !!props.grid;
+  return !!injectGrid.value;
 });
 
 const computedGridProps = computed<GridProps>(() => {
   return enableGrid.value
-    ? { ...getObject(injectGrid), ...getObject(grid) }
+    ? { ...getObject(injectGrid.value), ...getObject(props.grid) }
     : {};
 });
 
-const formItemRefs: any[] = [];
-const componentRefs: any[] = [];
+/**
+ * 以字段原始对象为 key 登记 FormItem / 控件实例，供 getFormItemRef / getComponentRef 读取；
+ * WeakMap 不参与响应式追踪，条目随字段对象回收自动释放。
+ */
+const formItemInstanceMap = new WeakMap<object, any>();
+const componentInstanceMap = new WeakMap<object, any>();
 
-const onFormItemMounted = (index: number, formItemProps?: any) => {
-  const field = validFields.value[index];
-  Object.assign(field, {
-    getFormItemRef: () => formItemRefs[index],
-    getFormItemComputedProps: () => formItemProps,
-  });
+const setFormItemRef = (field: any, el: any, formItemProps?: any) => {
+  if (!field || typeof field !== 'object') return;
+  const raw = toRaw(field);
+  if (el) {
+    formItemInstanceMap.set(raw, el);
+    raw.getFormItemRef = () => formItemInstanceMap.get(raw);
+    raw.getFormItemComputedProps = () => formItemProps;
+  } else {
+    formItemInstanceMap.delete(raw);
+  }
 };
 
-const onComponentMounted = (index: number) => {
-  const field = validFields.value[index];
-  Object.assign(field, {
-    getComponentRef: () => componentRefs[index]?.getComponentRef(),
-    getComponentComputedProps: () =>
-      componentRefs[index]?.getComponentComputedProps(),
-  });
+const setComponentRef = (field: any, el: any) => {
+  if (!field || typeof field !== 'object') return;
+  const raw = toRaw(field);
+  if (el) {
+    componentInstanceMap.set(raw, el);
+    raw.getComponentRef = () =>
+      componentInstanceMap.get(raw)?.getComponentRef();
+    raw.getComponentComputedProps = () =>
+      componentInstanceMap.get(raw)?.getComponentComputedProps();
+  } else {
+    componentInstanceMap.delete(raw);
+  }
 };
 
 const groupedFields = useGroupFieldAttrs(validFields);
@@ -108,10 +124,9 @@ const groupedFields = useGroupFieldAttrs(validFields);
         >
           <FormItem
             v-bind="item.formItemProps"
-            :ref="el => (formItemRefs[index] = el)"
+            :ref="el => setFormItemRef(item.rawField, el, item.formItemProps)"
             :name="toPath(item.path)"
             :path="item.path"
-            @vue:mounted="onFormItemMounted(index, item.formItemProps)"
           >
             <template
               v-for="(slot, name) in item.formItemSlots"
@@ -126,17 +141,16 @@ const groupedFields = useGroupFieldAttrs(validFields);
             </template>
             <template v-if="item.rawField.fields">
               <BaseFormItem
-                :grid="(item.rawField as any).grid ?? grid"
+                :grid="(item.rawField as any).grid ?? props.grid"
                 :fields="item.rawField.fields"
                 :disabled="toValue(item.rawField.disabled)"
               />
             </template>
             <template v-else>
               <BaseField
-                :ref="el => (componentRefs[index] = el)"
+                :ref="el => setComponentRef(item.rawField, el)"
                 v-bind="item.componentProps"
                 :path="item.path"
-                @vue:mounted="onComponentMounted(index)"
               />
             </template>
           </FormItem>

package/src/components/form/components/ContainerFragment/index.vue

@@ -11,13 +11,15 @@ type Props = {
   component?: ContainerComponent;
 };
 
-defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  component: undefined,
+});
 
 defineOptions({ name: 'ContainerFragment', inheritAttrs: false });
 </script>
 
 <template>
-  <component :is="component" v-if="component" v-bind="$attrs">
+  <component :is="props.component" v-if="props.component" v-bind="$attrs">
     <slot />
   </component>
   <slot v-else />

package/src/components/form/components/ProForm/index.vue

@@ -43,38 +43,89 @@
  * ```
  */
 import { Form as AForm, FormProps as AFormProps } from '../../../../shared/ui';
-import { inject, mergeProps, provide, reactive, type Slot } from 'vue';
+import {
+  computed,
+  inject,
+  mergeProps,
+  provide,
+  toValue,
+  useAttrs,
+  type Slot,
+} from 'vue';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
 import { BaseFormItem } from '..';
 import { InjectionFormKey, InjectionFormSlotsKey } from '../../constants';
 import type { Grid, VModelProps, PathProps } from '../../types';
-import { Path, camelizeProperties } from '../../../../shared/core';
-import type { Form } from '../../hooks/useForm';
+import {
+  Path,
+  camelizeProperties,
+  createFormProxy,
+} from '../../../../shared/core';
+import { useForm, type Form } from '../../hooks/useForm';
 
 defineOptions({ name: 'ProForm', inheritAttrs: false });
 
-type FormProps = Partial<Omit<AFormProps, 'model'>>;
+type MyFormProps = Partial<Omit<AFormProps, 'model'>>;
 
-type Props = { grid?: Grid; form?: F } & /* @vue-ignore */ FormProps;
-const { grid = false, form = {} as F } = defineProps<Props>();
+type Props = { grid?: Grid; form?: F } & /* @vue-ignore */ MyFormProps;
+const props = withDefaults(defineProps<Props>(), {
+  grid: false,
+  form: undefined,
+});
 
 /**
  * 依赖注入中心：
- * 将 Core 包生成的 Form 实例注入到 Vue 的 Context 中。
- * 供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
+ * 若外部未传 form 实例，则自动初始化内部表单实例；
+ * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
  */
-provide(InjectionFormKey, form as F);
+const fallbackForm = props.form ? undefined : useForm();
+const currentForm = computed(
+  () => props.form ?? (fallbackForm as unknown as F)
+);
+
+/**
+ * 表单实例代理：操作全部转发至 currentForm 当前实例；
+ * 下游持有本代理即可，:form 运行期替换无需重绑；方法具有引用记忆化。
+ */
+const formProxy = createFormProxy(() => currentForm.value);
+
+provide(InjectionFormKey, formProxy);
+
+const fields = computed(() => {
+  const f = currentForm.value?.fields;
+  return (Array.isArray(f) ? f : f?.value) ?? [];
+});
+const formData = computed(() => currentForm.value?.formData);
+const setFormRef = (el: any) => currentForm.value?.setFormRef?.(el);
 
-const { formData, fields, setFormRef } = form as F;
+let formInstanceCounter = 0;
+const formInstanceKeyMap = new WeakMap<object, number>();
+const getFormKey = (f: object) => {
+  if (!formInstanceKeyMap.has(f)) {
+    formInstanceKeyMap.set(f, ++formInstanceCounter);
+  }
+  return formInstanceKeyMap.get(f)!;
+};
+const formKey = computed(() => getFormKey(currentForm.value as any));
 
 const config = INJECT_CONFIG['pro-form'];
+const injectFormConfig = inject(config.injectionKey, config.default);
 
-// 从 ProComponentProvider 获取全局配置，与传入的 props 合并
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const { grid: _injectGrid, ...injectAttrs } = inject(
-  config.injectionKey,
-  config.default
-);
+const attrs = useAttrs();
+
+/**
+ * 从 ProComponentProvider 获取全局配置，响应式派生以支持动态配置变更
+ */
+const injectAttrs = computed(() => {
+  const raw = toValue(injectFormConfig);
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { grid: _injectGrid, ...rest } = raw || {};
+  return rest;
+});
+
+const formAttrs = computed(() => {
+  return mergeProps(injectAttrs.value, camelizeProperties(attrs));
+});
 
 type ExtractPath<T> = T extends Form<infer D> ? Path<D> : string;
 type FieldSlotProps = VModelProps &
@@ -87,17 +138,18 @@ const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
  * 动态插槽映射中心 (Slot Teleporting)：
  * 在 setup 同步期直接提供响应式 slots 上下文容器，供深层 BaseField 按需动态获取插槽
  */
-provide(InjectionFormSlotsKey, reactive(slots) as any);
+provide(InjectionFormSlotsKey, slots);
 </script>
 
 <template>
   <AForm
-    :ref="(el: any) => setFormRef?.(el)"
+    :key="formKey"
+    :ref="setFormRef"
     :model="formData"
-    v-bind="mergeProps(injectAttrs, camelizeProperties($attrs))"
+    v-bind="formAttrs"
     class="pro-form"
   >
-    <BaseFormItem :fields="fields" :grid="grid" />
+    <BaseFormItem :fields="fields" :grid="props.grid" />
     <slot />
   </AForm>
 </template>

package/src/components/form/components/SlotComponent/index.vue

@@ -13,14 +13,16 @@ defineOptions({ name: 'SlotComponent', inheritAttrs: false });
 type Props = {
   component?: SlotComponentType;
 };
-defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  component: undefined,
+});
 </script>
 
 <template>
   <component
-    :is="component"
-    v-if="isVNode(component) || typeof component === 'function'"
+    :is="props.component"
+    v-if="isVNode(props.component) || typeof props.component === 'function'"
     v-bind="$attrs"
   />
-  <template v-else>{{ component }}</template>
+  <template v-else>{{ props.component }}</template>
 </template>

package/src/components/form/hooks/useGroupFieldAttrs.ts

@@ -14,6 +14,9 @@ const formItemPropKeys = Object.keys(formItemProps()).concat([
   'formItemContainer',
 ]);
 const gridItemPropKeys = Object.keys(gridItemProps());
+// 模块级 Set：字段循环内 O(1) 命中，替代数组 includes 线性扫描
+const gridItemPropKeySet = new Set<string>(gridItemPropKeys);
+const formItemPropKeySet = new Set<string>(formItemPropKeys);
 
 export interface GroupedField {
   path: string;
@@ -27,12 +30,17 @@ export interface GroupedField {
 
 /**
  * 将 fields 配置数组逐个拆分为 grid / formItem / component / slots 分组。
+ *
+ * @description
+ * 1. 响应式集成 ProComponentProvider 的 `pro-form-item` 全局变量配置；
+ * 2. 剥离 `extraProps`（用户自定义字段标识袋）：保留在字段原始对象上供业务层存取，渲染层经解构剥离，避免落入 componentProps 透传为无效 DOM 属性。
  */
 export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
   const config = INJECT_CONFIG['pro-form-item'];
   const injectFormItemProps = inject(config.injectionKey, config.default);
 
   return computed<GroupedField[]>(() => {
+    const rawInject = toValue(injectFormItemProps) || {};
     return validFields.value.map(field => {
       let gridItemProps: Record<string, any> = {};
       let formItemProps: Record<string, any> = {};
@@ -55,15 +63,19 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           lg,
           xl,
           xxl,
+          formItemContainer: injectFormItemContainer,
           ...injectRest
-        } = injectFormItemProps;
+        } = rawInject;
 
+        // 字段显式 span 优先，否则回退注入配置的响应式断点
         const initGridItemProps =
           span || span === 0
             ? { span }
             : { xs, sm, md, lg, xl, xxl, span: injectSpan };
 
         gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+        // 字段级容器优先，回退注入级配置
+        const container = formItemContainer ?? injectFormItemContainer;
         formItemProps = mergeProps(
           injectRest,
           { class: injectClassName, style: injectStyle },
@@ -72,9 +84,9 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
         );
 
         Object.keys(rest).forEach(k => {
-          if (gridItemPropKeys.includes(k)) {
+          if (gridItemPropKeySet.has(k)) {
             gridItemProps[k] = rest[k];
-          } else if (formItemPropKeys.includes(k)) {
+          } else if (formItemPropKeySet.has(k)) {
             formItemProps[k] = rest[k];
           } else {
             componentProps[k] = rest[k];
@@ -100,7 +112,7 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           formItemProps: formItemProps as any,
           formItemSlots,
           componentProps,
-          formItemContainer,
+          formItemContainer: container,
           rawField: field,
         };
       }

package/src/components/form/types/index.ts

@@ -30,9 +30,33 @@ export type VModelProps<T = any> = {
   'onUpdate:value'?: (val: T) => void;
 };
 
+/**
+ * 字段值格式化/转换处理器
+ *
+ * @description 支持函数形态或包含 get/set 方法的对象形态。
+ *
+ * ### 行为与契约说明
+ * 1. **旧值参数按需注入**：底层基于函数的形参声明个数（`fn.length > 1`）决定是否读取旧值。若转换逻辑需要使用旧值，请显式声明两个形参 `(val, oldVal) => ...`（请勿使用默认参数或 `...args` 剩余参数，否则 `fn.length` 无法正确识别）；
+ * 2. **只读快照副本**：传入的 `oldVal` 为只读快照副本，不得依赖原地修改写回；仅当 formatter 声明双形参时才克隆旧值，单参转换零开销。
+ *
+ * @example
+ * ```ts
+ * // 1. 单参数转换（常见）：无需旧值，零多余开销
+ * valueFormatter: (val) => val?.trim()
+ *
+ * // 2. 双参数转换：需要基于旧值做对比或回退
+ * valueFormatter: (val, oldVal) => (isValid(val) ? val : oldVal)
+ *
+ * // 3. 对象形态：分别定义读（展示）与写（存储）转换
+ * valueFormatter: {
+ *   get: (val) => (val ? dayjs(val).format('YYYY-MM-DD') : ''),
+ *   set: (val, oldVal) => (val ? dayjs(val).valueOf() : undefined),
+ * }
+ * ```
+ */
 export type ValueFormatter =
-  | { (val: any, oldVal: any): any }
-  | { get?: (val: any) => any; set?: (val: any, oldVal: any) => any };
+  | { (val: any, oldVal?: any): any }
+  | { get?: (val: any) => any; set?: (val: any, oldVal?: any) => any };
 
 /**
  * @description 自定义组件