@qin-ui/element-plus-pro 1.3.4 → 1.4.0

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

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 /**
+ * 表单字段渲染引擎
+ *
  * @component BaseFormItem
- * @description 表单字段渲染引擎
  *
  * 负责将字段配置数组渲染为实际的表单项，支持：
  * - 字段分组（嵌套 fields 递归渲染，嵌套字段 path 须为完整点分路径）
@@ -17,21 +18,29 @@
  * 3. 递归渲染 BaseFormItem（嵌套表单）或 BaseField（输入组件）
  * 4. 通过 ref 回调收集 FormItem 和 Component 实例，注入到 field 对象上
  *
- * @param {Fields<D>} [fields] - 字段配置数组
+ * @param {Fields} [fields] - 字段配置数组
  * @param {boolean | GridProps} [grid] - 是否启用网格布局
+ * @param {boolean} [disabled] - 是否禁用所有子字段
  *
  * @internal
  */
-import { getObject, normalizePathKey } from '../../../../shared/core';
+import {
+  getObject,
+  isObjectItem,
+  normalizePathKey,
+} from '../../../../shared/core';
+import type { GridProps } from '../../../../shared/ui';
 import {
   FormItem,
   Grid as ElGrid,
   GridItem as ElGridItem,
-  GridProps,
+  useProviderDisabled,
 } from '../../../../shared/ui';
 import { computed, inject, toRaw, toValue } from 'vue';
 import type { Fields, Grid } from '../../types';
-import { BaseField, SlotComponent, ContainerFragment } from '..';
+import BaseField from '../BaseField/index.vue';
+import SlotComponent from '../SlotComponent/index.vue';
+import ContainerFragment from '../ContainerFragment/index.vue';
 import { useGroupFieldAttrs } from '../../hooks/useGroupFieldAttrs';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
 
@@ -40,15 +49,22 @@ defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
 type Props = {
   grid?: Grid;
   fields?: Fields;
+  disabled?: boolean;
 };
 const props = withDefaults(defineProps<Props>(), {
   grid: undefined,
   fields: () => [],
+  disabled: undefined,
 });
 
+// 分组字段的禁用状态向下注入，供 BaseField 经禁用上下文消费
+useProviderDisabled(computed(() => props.disabled));
+
 const validFields = computed(() =>
-  // hidden 支持 Ref/ComputedRef/getter 等响应式形态（统一使用 toValue 取值）
-  (props.fields ?? []).filter(field => !toValue(field.hidden))
+  // hidden 支持 Ref / ComputedRef 响应式形态（统一使用 toValue 取值）
+  (props.fields ?? []).filter(
+    field => isObjectItem(field) && !toValue((field as any).hidden)
+  )
 );
 
 const config = INJECT_CONFIG['pro-form'];
@@ -68,18 +84,46 @@ const computedGridProps = computed<GridProps>(() => {
 
 /**
  * 以字段原始对象为 key 登记 FormItem / 控件实例，供 getFormItemRef / getComponentRef 读取；
- * WeakMap 不参与响应式追踪，条目随字段对象回收自动释放。
+ * 字段对象被回收后对应条目不再可读。
  */
 const formItemInstanceMap = new WeakMap<object, any>();
 const componentInstanceMap = new WeakMap<object, any>();
 
+/** 已告警过的字段对象（不可写场景去重） */
+const warnedFrozenFields = new WeakSet<object>();
+const defineFieldAccessors = (
+  raw: object,
+  accessors: Record<string, () => any>
+) => {
+  try {
+    for (const [key, getter] of Object.entries(accessors)) {
+      // 访问器仅用于字段对象读取，不参与属性遍历与字段配置透传
+      Object.defineProperty(raw, key, {
+        value: getter,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+      });
+    }
+  } catch {
+    if (!warnedFrozenFields.has(raw)) {
+      warnedFrozenFields.add(raw);
+      console.warn(
+        '[pro-components] 字段配置对象不可写（如被 Object.freeze），getFormItemRef / getComponentRef 等实例访问器挂载失败。'
+      );
+    }
+  }
+};
+
 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;
+    defineFieldAccessors(raw, {
+      getFormItemRef: () => formItemInstanceMap.get(raw),
+      getFormItemComputedProps: () => formItemProps,
+    });
   } else {
     formItemInstanceMap.delete(raw);
     delete raw.getFormItemRef;
@@ -92,10 +136,11 @@ const setComponentRef = (field: any, el: any) => {
   const raw = toRaw(field);
   if (el) {
     componentInstanceMap.set(raw, el);
-    raw.getComponentRef = () =>
-      componentInstanceMap.get(raw)?.getComponentRef();
-    raw.getComponentComputedProps = () =>
-      componentInstanceMap.get(raw)?.getComponentComputedProps();
+    defineFieldAccessors(raw, {
+      getComponentRef: () => componentInstanceMap.get(raw)?.getComponentRef(),
+      getComponentComputedProps: () =>
+        componentInstanceMap.get(raw)?.getComponentComputedProps(),
+    });
   } else {
     componentInstanceMap.delete(raw);
     delete raw.getComponentRef;
@@ -112,7 +157,7 @@ const groupedFields = useGroupFieldAttrs(validFields);
     v-bind="computedGridProps"
     style="width: 100%"
   >
-    <template v-for="(item, index) of groupedFields" :key="item.path || index">
+    <template v-for="item of groupedFields" :key="item.renderKey">
       <ContainerFragment
         :component="enableGrid ? ElGridItem : undefined"
         v-bind="item.gridItemProps"
@@ -139,6 +184,7 @@ const groupedFields = useGroupFieldAttrs(validFields);
               <BaseFormItem
                 :grid="(item.rawField as any).grid ?? props.grid"
                 :fields="item.rawField.fields"
+                :disabled="toValue(item.rawField.disabled)"
               />
             </template>
             <template v-else>

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

@@ -1,7 +1,9 @@
 <script lang="ts" setup>
 /**
+ * 容器分片渲染组件
+ *
  * @component ContainerFragment
- * @description 容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。
+ * @description 用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）
  *
  * @public
  */

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

@@ -1,7 +1,8 @@
 <script lang="ts" setup generic="F extends Form<any> = Form">
 /**
+ * 配置驱动表单组件
+ *
  * @component ProForm
- * @description @qin-ui/element-plus-pro 配置驱动表单组件
  *
  * 架构设计说明 (Architecture Overview)
  *
@@ -12,39 +13,59 @@
  * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件。
  * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成。
  *
+ * @public
+ *
  * 通过配置驱动的方式快速构建表单，支持：
- * - 字段联动、嵌套字段、自定义组件、网格布局
+ * - 字段联动（通过 setField、watch 等实现）
+ * - 嵌套字段（通过 fields 递归配置）
+ * - 自定义组件（通过 component 属性和 custom 类型）
+ * - 网格布局（通过 grid 属性）
+ * - 动态插槽（以字段 path 命名的插槽）
+ * - 全局配置注入（通过 ProComponentProvider）
  *
  * @template F - 表单实例类型
+ *
  * @param {F} [form] - useForm 返回的表单实例
- * @param {boolean | GridProps} [grid=false] - 是否启用网格布局
+ * @param {boolean | GridProps} [grid] - 是否启用网格布局；未提供时回退 Provider 注入的 `grid` 配置
+ * @param {...FormProps} ...attrs - Element Plus Form 组件的其他属性
  *
- * @slot default - 默认插槽
- * @slot [path] - 以字段 path 命名的动态插槽
- 
- * @public
+ * @slot default - 默认插槽，可用于添加额外内容
+ * @slot [path] - 以字段 path 命名的动态插槽，可用于自定义字段渲染
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <ProForm :form="form" @submit="handleSubmit">
+ *     <template #name="{ value, disabled }">
+ *       <el-input :model-value="value" :disabled="disabled" />
+ *     </template>
+ *   </ProForm>
+ * </template>
+ * ```
  */
+import type { FormProps as ElFormProps } from '../../../../shared/ui';
+import { Form as ElForm } from '../../../../shared/ui';
 import {
-  Form as ElForm,
-  FormProps as ElFormProps,
-} from '../../../../shared/ui';
-import {
+  computed,
   inject,
   mergeProps,
+  onUpdated,
   provide,
+  shallowRef,
   toValue,
+  triggerRef,
   type Slot,
-  computed,
-  useAttrs,
 } from 'vue';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
-import { BaseFormItem } from '..';
+import BaseFormItem from '../BaseFormItem/index.vue';
 import { InjectionFormKey, InjectionFormSlotsKey } from '../../constants';
 import type { Grid, VModelProps, PathProps } from '../../types';
+import type { Path } from '../../../../shared/core';
 import {
-  Path,
   camelizeProperties,
   createFormProxy,
+  omitBy,
+  useReactiveAttrs,
 } from '../../../../shared/core';
 import { useForm, type Form } from '../../hooks/useForm';
 
@@ -57,19 +78,18 @@ type Props = {
   form?: F;
 } & /* @vue-ignore */ FormProps;
 const props = withDefaults(defineProps<Props>(), {
-  grid: false,
+  grid: undefined,
   form: undefined,
 });
 
 /**
  * 依赖注入中心：
- * 若外部未传 form 实例，则自动初始化内部表单实例；
+ * 未传 form 实例（含运行期置空）时回退内部表单实例；
  * 将 Form 实例注入到 Vue Context 中，供深层子组件跨层级直接访问数据和方法。
  */
-const fallbackForm = props.form ? undefined : useForm();
-const currentForm = computed(
-  () => props.form ?? (fallbackForm as unknown as F)
-);
+// 兜底表单实例：setup 同步期创建，未传 :form（含运行期置空）时经 currentForm 生效
+const fallbackForm = useForm() as unknown as F;
+const currentForm = computed(() => props.form ?? fallbackForm);
 
 /**
  * 表单实例代理：操作全部转发至 currentForm 当前实例；
@@ -93,6 +113,7 @@ const setFormRef = (el: any) => currentForm.value?.setFormRef?.(el);
 let formInstanceCounter = 0;
 const formInstanceKeyMap = new WeakMap<object, number>();
 const getFormKey = (f: object) => {
+  if (f == null) return 0;
   if (!formInstanceKeyMap.has(f)) {
     formInstanceKeyMap.set(f, ++formInstanceCounter);
   }
@@ -102,20 +123,22 @@ const formKey = computed(() => getFormKey(currentForm.value as any));
 
 const config = INJECT_CONFIG['pro-form'];
 const injectFormConfig = inject(config.injectionKey, config.default);
-const attrs = useAttrs();
+const attrs = useReactiveAttrs();
 
 /**
  * 从 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));
+  return mergeProps(
+    injectAttrs.value,
+    omitBy(camelizeProperties(attrs), value => value === undefined)
+  );
 });
 
 type ExtractPath<T> = T extends Form<infer D> ? Path<D> : string;
@@ -125,11 +148,15 @@ type FieldSlots = Record<ExtractPath<F>, Slot<FieldSlotProps>>;
 
 const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
 
-/**
+/*
  * 动态插槽映射中心 (Slot Teleporting)：
- * 在 setup 同步期直接提供响应式 slots 上下文容器，供深层 BaseField 按需动态获取插槽
+ * 向深层 BaseField 提供 ProForm 的具名插槽，父级运行期增删插槽后下游可感知
  */
-provide(InjectionFormSlotsKey, slots);
+const formSlotsRef = shallowRef<Record<string, any>>(slots);
+onUpdated(() => {
+  triggerRef(formSlotsRef);
+});
+provide(InjectionFormSlotsKey, formSlotsRef);
 </script>
 
 <template>

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

@@ -1,11 +1,13 @@
 <script lang="ts" setup>
 /**
+ * 插槽渲染辅助组件
+ *
  * @component SlotComponent
- * @description 插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。
+ * @description 用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数、组件定义对象或静态字符串
  *
  * @public
  */
-import { SlotComponentType } from '../../types';
+import type { SlotComponentType } from '../../types';
 
 defineOptions({ name: 'SlotComponent', inheritAttrs: false });
 

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

@@ -1,4 +1,7 @@
-import { ComponentProps, ComponentExposed } from 'vue-component-type-helpers';
+import type {
+  ComponentProps,
+  ComponentExposed,
+} from 'vue-component-type-helpers';
 import ProForm from './ProForm/index.vue';
 import BaseFormItem from './BaseFormItem/index.vue';
 
@@ -8,8 +11,12 @@ export { default as SlotComponent } from './SlotComponent/index.vue';
 export { ProForm, BaseFormItem };
 
 // instance
+/** ProForm 组件实例 */
 export type ProFormInstance = ComponentExposed<typeof ProForm>;
+/** ProForm 组件属性 */
 export type ProFormProps = ComponentProps<typeof ProForm>;
 
+/** BaseFormItem 组件实例（字段级 FormItem） */
 export type ProFormItemInstance = ComponentExposed<typeof BaseFormItem>;
+/** BaseFormItem 组件属性（字段级 FormItem） */
 export type ProFormItemProps = ComponentProps<typeof BaseFormItem>;

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

@@ -57,7 +57,7 @@ export type BaseComponentMap = {
  *   }
  * }
  * ```
- 
+ *
  * @public
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
@@ -66,7 +66,7 @@ export interface ComponentMap {}
 /**
  * 组件名称联合类型
  * @description 所有支持的组件名称
- 
+ *
  * @public
  */
 export type ComponentName =
@@ -106,5 +106,12 @@ export const componentMap: BaseComponentMap = {
   'transfer': Transfer,
 }
 
+/**
+ * 字段标识键序：el-form-item 的 prop 优先，path 兜底
+ *
+ * 与字段读写绑定、表单域标识、字段查找 API 共用同一解析入口
+ */
+export const ELEMENT_FIELD_IDENTITY_KEYS = ['prop', 'path'] as const;
+
 // inject keys
 export { InjectionFormKey, InjectionFormSlotsKey } from '../../../shared/core';

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

@@ -1,10 +1,11 @@
-import { FormItemInstance } from '../../../shared/ui';
+import type { FormItemInstance } from '../../../shared/ui';
 import {
   useFields as coreUseFields,
   type UseFieldsReturn,
 } from '../../../shared/core';
 import type { Data } from '../../../shared/core';
 import type { Field, Fields } from '../types';
+import { ELEMENT_FIELD_IDENTITY_KEYS } from '../constants';
 import type { ComponentName } from '../constants';
 
 /**
@@ -58,7 +59,9 @@ export function useFields<D extends Data = Data>(
   initFields?: Fields<D>
 ): UseFieldsReturn<D, Field<ComponentName, D>, FormItemInstance>;
 export function useFields(initFields?: any) {
-  return coreUseFields(initFields);
+  return coreUseFields(initFields, {
+    fieldIdentityKeys: ELEMENT_FIELD_IDENTITY_KEYS,
+  });
 }
 
 /** useFields 返回值类型

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

@@ -4,6 +4,7 @@ import {
 } from '../../../shared/core';
 import type { Data, ExtendWithAny, DeepPartial } from '../../../shared/core';
 import type { Field } from '../types';
+import { ELEMENT_FIELD_IDENTITY_KEYS } from '../constants';
 import type { ComponentName } from '../constants';
 import type { FormInstance } from '../../../shared/ui';
 
@@ -107,5 +108,11 @@ export function useForm<D extends Data = Data>(
   root?: boolean
 ): Form<D, Field<ComponentName, D>>;
 export function useForm(...args: any[]) {
-  return coreUseForm(...(args as any));
+  // root 单参重载不承载字段配置，标识键无适用对象
+  if (args.length === 1 && typeof args[0] === 'boolean') {
+    return coreUseForm(args[0]);
+  }
+  return coreUseForm(args[0], args[1], args[2], {
+    fieldIdentityKeys: ELEMENT_FIELD_IDENTITY_KEYS,
+  });
 }

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

@@ -1,24 +1,23 @@
 import { computed, inject, mergeProps, toValue, type ComputedRef } from 'vue';
+import { getFieldKey } from '../utils/fieldKey';
 import {
   formItemProps,
   gridItemProps,
   type FormItemProps,
   type GridItemProps,
 } from '../../../shared/ui';
-import { isPlainObject } from '../../../shared/core';
+import { isPlainObject, resolveFieldIdentity } from '../../../shared/core';
 import { INJECT_CONFIG } from '../../component-provider/constants';
-import { FORM_ITEM_SLOT_KEYS } from '../constants';
+import { ELEMENT_FIELD_IDENTITY_KEYS, FORM_ITEM_SLOT_KEYS } from '../constants';
 import type { Base, Field } from '../types';
 
-const formItemPropKeys = Object.keys(formItemProps()).filter(
-  k => k !== 'disabled'
-);
+const formItemPropKeys = Object.keys(formItemProps());
 const gridItemPropKeys = Object.keys(gridItemProps());
-// 模块级 Set：字段循环内 O(1) 命中，替代数组 includes 线性扫描
 const gridItemPropKeySet = new Set<string>(gridItemPropKeys);
 const formItemPropKeySet = new Set<string>(formItemPropKeys);
 const formItemSlotKeySet = new Set<string>(FORM_ITEM_SLOT_KEYS);
 
+/** 单个字段的分组结果：栅格 / FormItem / 组件属性与插槽 */
 export interface GroupedField {
   path: string;
   gridItemProps: GridItemProps;
@@ -27,10 +26,18 @@ export interface GroupedField {
   componentProps: Record<string, any>;
   container?: Base['formItemContainer'];
   rawField: Field;
+  renderKey: string | number;
 }
 
 /**
  * 将 fields 配置数组逐个拆分为 grid / formItem / component / slots 分组。
+ *
+ * @description
+ * 1. 响应式集成 ProComponentProvider 的 `pro-form-item` 全局变量配置；
+ * 2. 剥离 `extraProps`（用户自定义字段标识袋）：保留在字段原始对象上供业务层存取，渲染层经解构剥离，不落入 componentProps 透传。
+ *
+ * @param {ComputedRef<Field[]>} validFields - 已过滤的字段配置数组
+ * @returns {ComputedRef<GroupedField[]>} 分组后的字段属性数组
  */
 export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
   const config = INJECT_CONFIG['pro-form-item'];
@@ -46,30 +53,25 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
       if (isPlainObject(field)) {
         // prettier-ignore
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { path, name, fields, formItemClass, formItemStyle, formItemContainer, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, ...rest } =
+        const { path: _path, prop: _prop, fields, formItemClass, formItemStyle, formItemContainer, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, ...rest } =
           field as any;
 
-        const {
-          class: injectClassName,
-          style: injectStyle,
-          span: injectSpan,
-          formItemContainer: injectFormItemContainer,
-          xs,
-          sm,
-          md,
-          lg,
-          xl,
-          ...injectRest
-        } = rawInjectProps;
+        // prettier-ignore
+        const { class: injectClassName, style: injectStyle, span: injectSpan, formItemContainer: injectFormItemContainer, xs, sm, md, lg, xl, ...injectRest } = rawInjectProps;
 
-        // 字段显式 span 优先，否则回退注入配置的响应式断点
+        /*
+         * 字段显式指定 span 时整体接管栅格，不再叠加注入的响应式断点；
+         * 未指定 span 时使用注入的断点配置
+         */
         const initGridItemProps =
           span || span === 0
             ? { span }
             : { xs, sm, md, lg, xl, span: injectSpan };
 
-        gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
+        gridItemProps = fields
+          ? { ...initGridItemProps, span: span ?? 24 }
+          : initGridItemProps;
         formItemProps = mergeProps(
           injectRest as any,
           { class: injectClassName, style: injectStyle },
@@ -97,30 +99,27 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           }
         });
 
-        const raw = (toValue(name) ?? toValue(path)) as
-          | string
-          | number[]
-          | undefined;
+        // 字段标识经统一解析（prop 优先，path 兜底）；name 作为控件自身属性经 rest 透传
         return {
-          path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+          path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
           gridItemProps: gridItemProps as GridItemProps,
           formItemProps: formItemProps as any,
           formItemSlots,
           componentProps,
           container,
           rawField: field,
+          renderKey: getFieldKey(field),
         };
       }
 
-      const raw =
-        toValue((field as any)?.name) ?? toValue((field as any)?.path);
       return {
-        path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+        path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
         gridItemProps: gridItemProps as GridItemProps,
         formItemProps: formItemProps as any,
         formItemSlots,
         componentProps,
         rawField: field,
+        renderKey: getFieldKey(field),
       };
     });
   });

package/src/components/form/index.ts

@@ -6,15 +6,13 @@ export {
   SlotComponent,
   type ProFormProps,
   type ProFormInstance,
-  type ProFormItemProps,
-  type ProFormItemInstance,
 } from './components';
 
 // 2. 仅导出允许模块合并扩展的 ComponentMap 以及组件名类型
 export { type ComponentMap, type ComponentName } from './constants';
 
 // 3. 仅导出核心表单配置 Schema 类型
-export { type Field, type Fields } from './types';
+export { type Field, type Fields, type ValueFormatter } from './types';
 
 // 4. 仅导出核心业务 Hooks
 export {