@qin-ui/element-plus-pro 1.3.5 → 1.4.1

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,22 +13,38 @@
  * 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 {
-  Form as ElForm,
-  FormProps as ElFormProps,
-} from '../../../../shared/ui';
+import type { FormProps as ElFormProps } from '../../../../shared/ui';
+import { Form as ElForm } from '../../../../shared/ui';
 import {
   computed,
   inject,
@@ -37,17 +54,18 @@ import {
   shallowRef,
   toValue,
   triggerRef,
-  useAttrs,
   type Slot,
 } from 'vue';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
 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';
 
@@ -66,13 +84,12 @@ const props = withDefaults(defineProps<Props>(), {
 
 /**
  * 依赖注入中心：
- * 未传 form 实例（含运行期置空）时惰性初始化内部表单实例；
+ * 未传 form 实例（含运行期置空）时回退内部表单实例；
  * 将 Form 实例注入到 Vue Context 中，供深层子组件跨层级直接访问数据和方法。
  */
-let fallbackForm: F | undefined;
-const currentForm = computed(
-  () => props.form ?? (fallbackForm ??= useForm() as unknown as F)
-);
+// 兜底表单实例：setup 同步期创建，未传 :form（含运行期置空）时经 currentForm 生效
+const fallbackForm = useForm() as unknown as F;
+const currentForm = computed(() => props.form ?? fallbackForm);
 
 /**
  * 表单实例代理：操作全部转发至 currentForm 当前实例；
@@ -106,7 +123,7 @@ 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 获取全局配置，响应式派生以支持动态配置变更
@@ -118,7 +135,10 @@ const injectAttrs = computed(() => {
 });
 
 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;
@@ -130,7 +150,7 @@ const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
 
 /*
  * 动态插槽映射中心 (Slot Teleporting)：
- * slots 以 shallowRef 注入，组件每次更新后触发通知，深层 BaseField 可感知父级运行期增删的具名插槽
+ * 向深层 BaseField 提供 ProForm 的具名插槽，父级运行期增删插槽后下游可感知
  */
 const formSlotsRef = shallowRef<Record<string, any>>(slots);
 onUpdated(() => {

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,19 +53,22 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
       if (isPlainObject(field)) {
         // prettier-ignore
-        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;
 
         // 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 };
 
-        // 分组字段默认整行（span 兜底 24），注入断点同样生效
+        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
         gridItemProps = fields
           ? { ...initGridItemProps, span: span ?? 24 }
           : initGridItemProps;
@@ -89,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 {