@qin-ui/element-plus-pro 1.2.4 → 1.3.0

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

@@ -33,14 +33,18 @@ import {
   inject,
   mergeProps,
   ref,
+  toValue,
   useAttrs,
 } from 'vue';
-import { cloneDeep, omit } from '../../../../shared/core';
+import { cloneDeep } from '../../../../shared/core';
 import { useDisabledContext } from '../../../../shared/ui';
 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 { useLocale } from '../../../../locale';
@@ -51,25 +55,36 @@ 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>();
 
 const attrs: any = useAttrs();
 
-function getOldValue() {
-  return cloneDeep(getFormData?.(path));
-}
+// 全局默认配置注入：key = 组件名 + type 修饰段；inject 须在 setup 同步期调用
+const typeVal = attrs.type;
+const injectConfigKey =
+  typeof props.component === 'string'
+    ? [props.component, typeVal].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' &&
@@ -82,14 +97,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);
   },
 });
 
@@ -100,36 +124,38 @@ const parentDisabled = useDisabledContext();
  * 属性分为三类：绑定属性（v-model）、组件属性（传递给组件）、插槽（动态渲染）
  */
 const groupedAttrs = computed(() => {
+  const currentInjectProps = toValue(rawInjectComponentProps) || {};
   const initProps = getInitProps(
     {
-      component: component,
+      component: props.component,
       type: attrs.type,
     } as unknown as Field,
+    currentInjectProps,
     t
   );
   const modelPropName = attrs.modelProp ?? initProps.modelProp ?? 'modelValue';
+  const effectiveDisabled =
+    attrs.disabled !== undefined
+      ? Boolean(attrs.disabled)
+      : Boolean(parentDisabled.value || initProps.disabled);
   const mergedProps = mergeProps(
     initProps,
     attrs,
     { class: attrs.componentClass, style: attrs.componentStyle },
     { class: initProps.componentClass, style: initProps.componentStyle },
-    { disabled: attrs.disabled ?? parentDisabled.value ?? initProps.disabled },
+    { disabled: effectiveDisabled },
     { modelProp: modelPropName }
   ) as Required<Field>;
+
   // prettier-ignore
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, ...rest } = mergedProps
-  const modelBindingProp = modelProp ?? 'modelValue';
-  // 从剩余属性中移除 v-model 绑定属性，避免重复绑定
-  const bindAttrs = omit(rest as Record<string, any>, [
-    modelBindingProp,
-    `onUpdate:${modelBindingProp}`,
-  ]);
+  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, [modelPropName]: _modelVal, [`onUpdate:${modelPropName}`]: _onUpdateModelVal, ...bindAttrs } = mergedProps as any;
+
   return {
     attrs: bindAttrs,
     slots,
     componentContainer,
-    modelProp: modelBindingProp,
+    modelProp: modelPropName,
     valueFormatter,
   };
 });
@@ -147,16 +173,19 @@ 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 =
+      (customComponents as any)[props.component] ||
+      (componentMap as any)[props.component];
+    if (resolved) return resolved;
+    console.warn(
+      `[pro-components] 未识别的组件类型 "${props.component}"，已降级为原生元素渲染。如为自定义组件请在 componentMap 或 ProComponentProvider 中注册。`
     );
+    return props.component;
   }
-  return component;
+  return props.component;
 });
 
 defineExpose({
@@ -166,21 +195,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,
@@ -38,11 +36,7 @@ const RANGE_PLACEHOLDER_KEYS: Record<string, [string, string]> = {
   'date-picker.datetimerange': ['date-picker.startTime', 'date-picker.endTime'],
 };
 
-/**
- * 根据组件 key 兜底生成 locale 占位符
- *
- * @description 用户通过 componentVars 或字段属性显式设置了占位符时不再兜底。
- */
+/** 根据组件 key 兜底生成 locale 占位符；已显式设置占位符（componentVars 或字段属性）时不兜底 */
 const getPlaceholderProps = (
   key: string,
   injectProps: Record<string, any>,
@@ -65,13 +59,14 @@ 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, type } = field as any;
   if (typeof component === 'string') {
     const k = [component, type].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 {};

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

@@ -4,7 +4,7 @@
  * @description 表单字段渲染引擎
  *
  * 负责将字段配置数组渲染为实际的表单项，支持：
- * - 字段分组（嵌套 fields 递归渲染）
+ * - 字段分组（嵌套 fields 递归渲染，嵌套字段 path 须为完整点分路径）
  * - 网格布局（grid 属性控制）
  * - FormItem 包装（label、rules、校验等）
  * - 组件绑定（通过 BaseField 渲染具体组件）
@@ -19,19 +19,17 @@
  *
  * @param {Fields<D>} [fields] - 字段配置数组
  * @param {boolean | GridProps} [grid] - 是否启用网格布局
- * @param {boolean} [disabled] - 是否禁用所有子字段
  *
  * @internal
  */
-import { getObject, toPath } from '../../../../shared/core';
+import { getObject, normalizePathKey } from '../../../../shared/core';
 import {
   FormItem,
   Grid as ElGrid,
   GridItem as ElGridItem,
   GridProps,
-  useDisabledContextProvider,
 } 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';
@@ -42,51 +40,62 @@ defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
 type Props = {
   grid?: Grid;
   fields?: Fields;
-  disabled?: boolean;
 };
-const {
-  grid = undefined,
-  fields = [],
-  disabled = undefined,
-} = defineProps<Props>();
-
-const validFields = computed(() => fields.filter?.(field => !field.hidden));
+const props = withDefaults(defineProps<Props>(), {
+  grid: undefined,
+  fields: () => [],
+});
 
-useDisabledContextProvider(computed(() => disabled) as any);
+const validFields = computed(() =>
+  (props.fields ?? []).filter(field => !field.hidden)
+);
 
 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);
@@ -106,10 +115,9 @@ const groupedFields = useGroupFieldAttrs(validFields);
         <ContainerFragment :component="item.container" :path="item.path">
           <FormItem
             v-bind="item.formItemProps"
-            :ref="el => (formItemRefs[index] = el)"
-            :prop="toPath(item.path).join('.')"
+            :ref="el => setFormItemRef(item.rawField, el, item.formItemProps)"
+            :prop="normalizePathKey(item.path)"
             :path="item.path"
-            @vue:mounted="onFormItemMounted(index, item.formItemProps)"
           >
             <template
               v-for="(slot, name) in item.formItemSlots"
@@ -124,17 +132,15 @@ 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/ProForm/index.vue

@@ -32,7 +32,7 @@ import {
   inject,
   mergeProps,
   provide,
-  reactive,
+  toValue,
   type Slot,
   computed,
   useAttrs,
@@ -42,34 +42,87 @@ 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 { useForm, type Form } from '../../hooks/useForm';
 
 defineOptions({ name: 'ProForm', inheritAttrs: false });
 
 type FormProps = Partial<Omit<ElFormProps, '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 */ FormProps;
+const props = withDefaults(defineProps<Props>(), {
+  grid: false,
+  form: undefined,
+});
 
 /**
  * 依赖注入中心：
- * 将 Core 包生成的 Form 实例注入到 Vue 的 Context 中。
- * 供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
+ * 若外部未传 form 实例，则自动初始化内部表单实例；
+ * 将 Form 实例注入到 Vue Context 中，供深层子组件跨层级直接访问数据和方法。
  */
-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 = new Proxy({} as F, {
+  get(_, prop) {
+    const target = currentForm.value as any;
+    const val = target?.[prop];
+    if (typeof val === 'function') {
+      return (...args: any[]) => (currentForm.value as any)?.[prop]?.(...args);
+    }
+    return val;
+  },
+  set(_, prop, value) {
+    if (currentForm.value) {
+      (currentForm.value as any)[prop] = value;
+    }
+    return true;
+  },
+  has(_, prop) {
+    return Boolean(currentForm.value && prop in currentForm.value);
+  },
+});
+
+provide(InjectionFormKey, formProxy);
 
-const { formData, fields, setFormRef } = form as F;
-const _fields = computed(() => fields.value);
+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);
+
+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);
 const attrs = useAttrs();
 
-// 从 ProComponentProvider 获取全局配置，与传入的 props 合并
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const { grid: _injectGrid, ...injectAttrs } = inject(
-  config.injectionKey,
-  config.default
-);
+/**
+ * 从 ProComponentProvider 获取全局配置，响应式派生以支持动态配置变更
+ */
+const injectAttrs = computed(() => {
+  const raw = toValue(injectFormConfig);
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { grid: _injectGrid, ...rest } = raw || {};
+  return rest;
+});
 
 type ExtractPath<T> = T extends Form<infer D> ? Path<D> : string;
 type FieldSlotProps = VModelProps &
@@ -82,18 +135,19 @@ const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
  * 动态插槽映射中心 (Slot Teleporting)：
  * 在 setup 同步期直接提供响应式 slots 上下文容器，供深层 BaseField 按需动态获取插槽
  */
-provide(InjectionFormSlotsKey, reactive(slots) as any);
+provide(InjectionFormSlotsKey, slots);
 </script>
 
 <template>
   <ElForm
-    :ref="(el: any) => setFormRef?.(el)"
+    :key="formKey"
+    :ref="setFormRef"
     :model="formData"
     v-bind="mergeProps(injectAttrs, camelizeProperties(attrs))"
     class="pro-form"
     @submit.prevent
   >
-    <BaseFormItem :fields="_fields" :grid="grid" />
+    <BaseFormItem :fields="fields" :grid="props.grid" />
     <slot />
   </ElForm>
 </template>

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

@@ -10,7 +10,9 @@ import { INJECT_CONFIG } from '../../component-provider/constants';
 import { FORM_ITEM_SLOT_KEYS } from '../constants';
 import type { Base, Field } from '../types';
 
-const formItemPropKeys = Object.keys(formItemProps());
+const formItemPropKeys = Object.keys(formItemProps()).filter(
+  k => k !== 'disabled'
+);
 const gridItemPropKeys = Object.keys(gridItemProps());
 
 export interface GroupedField {
@@ -31,6 +33,7 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
   const injectFormItemProps = inject(config.injectionKey, config.default);
 
   return computed<GroupedField[]>(() => {
+    const rawInjectProps = toValue(injectFormItemProps) || {};
     return validFields.value.map(field => {
       let gridItemProps: Record<string, any> = {};
       let formItemProps: Record<string, any> = {};
@@ -54,8 +57,9 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           lg,
           xl,
           ...injectRest
-        } = injectFormItemProps;
+        } = rawInjectProps;
 
+        // 字段显式 span 优先，否则回退注入配置的响应式断点
         const initGridItemProps =
           span || span === 0
             ? { span }
@@ -89,7 +93,7 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           }
         });
 
-        const raw = (toValue(path) ?? toValue(name)) as
+        const raw = (toValue(name) ?? toValue(path)) as
           | string
           | number[]
           | undefined;
@@ -105,7 +109,7 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
       }
 
       const raw =
-        toValue((field as any)?.path) ?? toValue((field as any)?.name);
+        toValue((field as any)?.name) ?? toValue((field as any)?.path);
       return {
         path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
         gridItemProps: gridItemProps as GridItemProps,

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

@@ -30,9 +30,33 @@ export type VModelProps<T = any> = {
   'onUpdate:modelValue'?: (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 自定义组件