@qin-ui/element-plus-pro 1.4.2 → 1.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/element-plus-pro",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "基于 element-plus 的二次封装组件",
   "bin": {
     "element-plus-pro": "./bin/init-ai.mjs"

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

@@ -1,205 +1,174 @@
-<script lang="ts" setup>
+<script lang="ts">
 /**
- * 表单字段渲染引擎
+ * 单字段行渲染组件
  *
  * @component BaseFormItem
  *
- * 负责将字段配置数组渲染为实际的表单项，支持：
- * - 字段分组（嵌套 fields 递归渲染，嵌套字段 path 须为完整点分路径）
- * - 网格布局（grid 属性控制）
- * - FormItem 包装（label、rules、校验等）
- * - 组件绑定（通过 BaseField 渲染具体组件）
- * - 插槽透传（label、error 等 FormItem 插槽）
+ * 将单个字段配置渲染为栅格项、FormItem 与控件，支持：
+ * - 字段属性分流（grid / formItem / component / slots）
+ * - 嵌套字段递归渲染（交由 BaseFormItems）
+ * - FormItem / 控件实例登记
  *
- * ## 渲染流程
- *
- * 1. 遍历 fields 数组，过滤 hidden 字段
- * 2. 通过 useGroupFieldAttrs Hook 纯计算将 field 配置拆分为 gridItemProps / formItemProps / componentProps / slots
- * 3. 递归渲染 BaseFormItem（嵌套表单）或 BaseField（输入组件）
- * 4. 通过 ref 回调收集 FormItem 和 Component 实例，注入到 field 对象上
- *
- * @param {Fields} [fields] - 字段配置数组
+ * @param {Field} field - 字段配置
  * @param {boolean | GridProps} [grid] - 是否启用网格布局
- * @param {boolean} [disabled] - 是否禁用所有子字段
+ * @param {boolean} [disabled] - 上层下发的禁用状态
+ * @param {Function} [setFormItemRef] - FormItem 实例登记回调
+ * @param {Function} [setComponentRef] - 控件实例登记回调
  *
  * @internal
  */
 import {
-  getObject,
-  isObjectItem,
-  normalizePathKey,
-} from '../../../../shared/core';
-import type { GridProps } from '../../../../shared/ui';
-import {
-  FormItem,
-  Grid as ElGrid,
-  GridItem as ElGridItem,
-  useProviderDisabled,
-} from '../../../../shared/ui';
-import { computed, inject, toRaw, toValue } from 'vue';
-import type { Fields, Grid } from '../../types';
+  computed,
+  defineComponent,
+  h,
+  toValue,
+  watch,
+  type PropType,
+  type VNode,
+} from 'vue';
+import { normalizePathKey } from '../../../../shared/core';
+import { FormItem, GridItem as ElGridItem } from '../../../../shared/ui';
+import type { Field, Grid } from '../../types';
 import BaseField from '../BaseField/index.vue';
+import BaseFormItems from '../BaseFormItems/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';
+import {
+  useGroupedField,
+  type GroupedField,
+} from '../../hooks/useGroupFieldAttrs';
 
-defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
+export default defineComponent({
+  name: 'BaseFormItem',
+  inheritAttrs: false,
+  props: {
+    /** 字段配置 */
+    field: { type: Object as PropType<Field>, required: true },
+    /** 是否启用网格布局 */
+    grid: {
+      type: [Boolean, Object] as PropType<Grid>,
+      default: undefined,
+    },
+    /** 上层下发的禁用状态 */
+    disabled: { type: Boolean, default: undefined },
+    /** FormItem 实例登记回调 */
+    setFormItemRef: {
+      type: Function as PropType<
+        (field: Field, el: any, getFormItemProps: () => any) => void
+      >,
+      default: undefined,
+    },
+    /** 控件实例登记回调 */
+    setComponentRef: {
+      type: Function as PropType<(field: Field, el: any) => void>,
+      default: undefined,
+    },
+  },
+  setup(props) {
+    const grouped = useGroupedField(() => props.field);
+    const enableGrid = computed(() => !!props.grid);
 
-type Props = {
-  grid?: Grid;
-  fields?: Fields;
-  disabled?: boolean;
-};
-const props = withDefaults(defineProps<Props>(), {
-  grid: undefined,
-  fields: () => [],
-  disabled: undefined,
-});
+    // 控件级配置身份：字符串组件名 + type 段；组件对象无 Provider 配置，使用固定值
+    const componentKey = computed(() => {
+      const field = props.field as any;
+      const component = toValue(field.component);
+      if (typeof component !== 'string') return 'component-object';
+      return `string:${component}:${toValue(field.type) ?? ''}`;
+    });
+    const effectiveDisabled = computed(
+      () => toValue(props.field.disabled) ?? props.disabled
+    );
 
-// 分组字段的禁用状态向下注入，供 BaseField 经禁用上下文消费
-useProviderDisabled(computed(() => props.disabled));
+    const setItemRef = (el: any) => {
+      props.setFormItemRef?.(
+        props.field,
+        el,
+        () => grouped.value.formItemProps
+      );
+    };
 
-const validFields = computed(() =>
-  // hidden 支持 Ref / ComputedRef 响应式形态（统一使用 toValue 取值）
-  (props.fields ?? []).filter(
-    field => isObjectItem(field) && !toValue((field as any).hidden)
-  )
-);
+    const setFieldRef = (el: any) => {
+      props.setComponentRef?.(props.field, el);
+    };
 
-const config = INJECT_CONFIG['pro-form'];
-const injectFormConfig = inject(config.injectionKey, config.default);
-const injectGrid = computed(() => toValue(injectFormConfig)?.grid);
+    // 字段对象变化后，实例访问器归属当前字段
+    watch(
+      () => props.field,
+      (next, prev) => {
+        if (!prev || prev === next) return;
+        props.setFormItemRef?.(prev, null, () => grouped.value.formItemProps);
+        props.setComponentRef?.(prev, null);
+      },
+      { flush: 'pre' }
+    );
 
-const enableGrid = computed(() => !!props.grid);
+    /** 按容器组件逐层包裹当前节点 */
+    const withContainer = (
+      node: VNode,
+      component: any,
+      containerProps: Record<string, any>
+    ): VNode =>
+      component ? h(component, containerProps, { default: () => node }) : node;
 
-const computedGridProps = computed<GridProps>(() => {
-  return enableGrid.value
-    ? { ...getObject(injectGrid.value), ...getObject(props.grid) }
-    : {};
-});
+    /** 组装 FormItem 的动态插槽与默认插槽 */
+    const renderFormItemSlots = (groupedField: GroupedField) => {
+      const slots: Record<string, any> = {};
+      Object.entries(groupedField.formItemSlots).forEach(([name, slot]) => {
+        slots[name] = (scope?: Record<string, any>) =>
+          h(SlotComponent as any, {
+            path: groupedField.path,
+            component: slot,
+            ...(scope || {}),
+          });
+      });
 
-/**
- * 以字段原始对象为 key 登记 FormItem / 控件实例，供 getFormItemRef / getComponentRef 读取；
- * 字段对象被回收后对应条目不再可读。
- */
-const formItemInstanceMap = new WeakMap<object, any>();
-const componentInstanceMap = new WeakMap<object, any>();
+      slots.default = () => {
+        const field = props.field as any;
+        if (field.fields) {
+          return h(BaseFormItems as any, {
+            grid: field.grid ?? props.grid,
+            fields: field.fields,
+            disabled: effectiveDisabled.value,
+          });
+        }
+        return h(BaseField as any, {
+          key: componentKey.value,
+          ref: setFieldRef,
+          ...groupedField.componentProps,
+          path: groupedField.path,
+          disabled: effectiveDisabled.value,
+        });
+      };
+      return slots;
+    };
 
-/** 已告警过的字段对象（不可写场景去重） */
-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,
+    return () => {
+      const groupedField = grouped.value;
+      let node: VNode = h(
+        FormItem as any,
+        {
+          ...groupedField.formItemProps,
+          ref: setItemRef,
+          prop: normalizePathKey(groupedField.path),
+          path: groupedField.path,
+        },
+        renderFormItemSlots(groupedField)
+      );
+      node = withContainer(node, groupedField.container, {
+        path: groupedField.path,
       });
-    }
-  } catch {
-    if (!warnedFrozenFields.has(raw)) {
-      warnedFrozenFields.add(raw);
-      console.warn(
-        '[pro-components] 字段配置对象不可写（如被 Object.freeze），getFormItemRef / getComponentRef 等实例访问器挂载失败。'
+      node = withContainer(
+        node,
+        enableGrid.value ? ElGridItem : undefined,
+        groupedField.gridItemProps
       );
-    }
-  }
-};
-
-const setFormItemRef = (field: any, el: any, formItemProps?: any) => {
-  if (!field || typeof field !== 'object') return;
-  const raw = toRaw(field);
-  if (el) {
-    formItemInstanceMap.set(raw, el);
-    defineFieldAccessors(raw, {
-      getFormItemRef: () => formItemInstanceMap.get(raw),
-      getFormItemComputedProps: () => formItemProps,
-    });
-  } else {
-    formItemInstanceMap.delete(raw);
-    delete raw.getFormItemRef;
-    delete raw.getFormItemComputedProps;
-  }
-};
-
-const setComponentRef = (field: any, el: any) => {
-  if (!field || typeof field !== 'object') return;
-  const raw = toRaw(field);
-  if (el) {
-    componentInstanceMap.set(raw, el);
-    defineFieldAccessors(raw, {
-      getComponentRef: () => componentInstanceMap.get(raw)?.getComponentRef(),
-      getComponentComputedProps: () =>
-        componentInstanceMap.get(raw)?.getComponentComputedProps(),
-    });
-  } else {
-    componentInstanceMap.delete(raw);
-    delete raw.getComponentRef;
-    delete raw.getComponentComputedProps;
-  }
-};
-
-const groupedFields = useGroupFieldAttrs(validFields);
+      return node;
+    };
+  },
+});
 </script>
 
-<template>
-  <ContainerFragment
-    :component="enableGrid ? ElGrid : undefined"
-    v-bind="computedGridProps"
-    style="width: 100%"
-  >
-    <template v-for="item of groupedFields" :key="item.renderKey">
-      <ContainerFragment
-        :component="enableGrid ? ElGridItem : undefined"
-        v-bind="item.gridItemProps"
-      >
-        <ContainerFragment :component="item.container" :path="item.path">
-          <FormItem
-            v-bind="item.formItemProps"
-            :ref="el => setFormItemRef(item.rawField, el, item.formItemProps)"
-            :prop="normalizePathKey(item.path)"
-            :path="item.path"
-          >
-            <template
-              v-for="(slot, name) in item.formItemSlots"
-              :key="name"
-              #[name]="scoped"
-            >
-              <SlotComponent
-                :path="item.path"
-                :component="slot"
-                v-bind="scoped"
-              />
-            </template>
-            <template v-if="item.rawField.fields">
-              <BaseFormItem
-                :grid="(item.rawField as any).grid ?? props.grid"
-                :fields="item.rawField.fields"
-                :disabled="toValue(item.rawField.disabled) ?? props.disabled"
-              />
-            </template>
-            <template v-else>
-              <BaseField
-                :ref="el => setComponentRef(item.rawField, el)"
-                v-bind="item.componentProps"
-                :path="item.path"
-                :disabled="toValue(item.rawField.disabled) ?? props.disabled"
-              />
-            </template>
-          </FormItem>
-        </ContainerFragment>
-      </ContainerFragment>
-    </template>
-  </ContainerFragment>
-</template>
-
 <style scoped lang="less">
+/* 分组字段的嵌套 FormItem 间距 */
 [class*='-form-item'] [class*='-form-item'] {
   margin-bottom: 18px;
 }

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

@@ -0,0 +1,183 @@
+<script lang="ts" setup>
+/**
+ * 表单字段渲染引擎
+ *
+ * @component BaseFormItems
+ *
+ * 负责将字段配置数组渲染为实际的表单项，支持：
+ * - 字段分组（嵌套 fields 递归渲染，嵌套字段 path 须为完整点分路径）
+ * - 网格布局（grid 属性控制）
+ * - FormItem 包装（label、rules、校验等）
+ * - 组件绑定（通过 BaseField 渲染具体组件）
+ * - 插槽透传（label、error 等 FormItem 插槽）
+ *
+ * ## 渲染流程
+ *
+ * 1. 遍历 fields 数组，过滤 hidden 字段
+ * 2. 每个字段交由 BaseFormItem 拆分为 GridItem / FormItem / 组件 / 插槽并渲染
+ * 3. 嵌套 fields 递归渲染下一层 BaseFormItems
+ * 4. 渲染后字段对象上可读取 FormItem 与组件实例
+ *
+ * @param {Fields} [fields] - 字段配置数组
+ * @param {boolean | GridProps} [grid] - 是否启用网格布局
+ * @param {boolean} [disabled] - 是否禁用所有子字段
+ *
+ * @internal
+ */
+import {
+  InjectionFormKey,
+  getObject,
+  isObjectItem,
+} from '../../../../shared/core';
+import type { GridProps } from '../../../../shared/ui';
+import { Grid as ElGrid, useProviderDisabled } from '../../../../shared/ui';
+import { computed, inject, toRaw, toValue } from 'vue';
+import type { Fields, Grid } from '../../types';
+import BaseFormItem from '../BaseFormItem/index.vue';
+import { getFieldDataKey } from '../../utils/fieldKey';
+import { INJECT_CONFIG } from '../../../component-provider/constants';
+
+defineOptions({ name: 'BaseFormItems', 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 响应式形态（统一使用 toValue 取值）
+  (props.fields ?? []).filter(
+    field => isObjectItem(field) && !toValue((field as any).hidden)
+  )
+);
+
+// 数组行按数据对象身份派生 key，字段配置重建后行实例保持复用
+const injectedForm = inject(InjectionFormKey, undefined) as any;
+const renderedFields = computed(() => {
+  const rawFormData = injectedForm?.formData
+    ? toRaw(injectedForm.formData)
+    : undefined;
+  const seen = new Map<string | number, number>();
+  return validFields.value.map(field => {
+    const baseKey = getFieldDataKey(field, rawFormData);
+    const count = seen.get(baseKey) ?? 0;
+    seen.set(baseKey, count + 1);
+    return {
+      field,
+      key: count === 0 ? baseKey : `${String(baseKey)}#${count}`,
+    };
+  });
+});
+
+const config = INJECT_CONFIG['pro-form'];
+const injectFormConfig = inject(config.injectionKey, config.default);
+const injectGrid = computed(() => toValue(injectFormConfig)?.grid);
+
+const enableGrid = computed(() => !!props.grid);
+
+const computedGridProps = computed<GridProps>(() => {
+  return enableGrid.value
+    ? { ...getObject(injectGrid.value), ...getObject(props.grid) }
+    : {};
+});
+
+/**
+ * 以字段原始对象为 key 登记 FormItem / 控件实例，供 getFormItemRef / getComponentRef 读取；
+ * 字段对象被回收后对应条目不再可读。
+ */
+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, getFormItemProps: () => any) => {
+  if (!field || typeof field !== 'object') return;
+  const raw = toRaw(field);
+  if (el) {
+    formItemInstanceMap.set(raw, el);
+    defineFieldAccessors(raw, {
+      getFormItemRef: () => formItemInstanceMap.get(raw),
+      getFormItemComputedProps: getFormItemProps,
+    });
+  } else {
+    formItemInstanceMap.delete(raw);
+    delete raw.getFormItemRef;
+    delete raw.getFormItemComputedProps;
+  }
+};
+
+const setComponentRef = (field: any, el: any) => {
+  if (!field || typeof field !== 'object') return;
+  const raw = toRaw(field);
+  if (el) {
+    componentInstanceMap.set(raw, el);
+    defineFieldAccessors(raw, {
+      getComponentRef: () => componentInstanceMap.get(raw)?.getComponentRef(),
+      getComponentComputedProps: () =>
+        componentInstanceMap.get(raw)?.getComponentComputedProps(),
+    });
+  } else {
+    componentInstanceMap.delete(raw);
+    delete raw.getComponentRef;
+    delete raw.getComponentComputedProps;
+  }
+};
+</script>
+
+<template>
+  <ElGrid v-if="enableGrid" v-bind="computedGridProps" style="width: 100%">
+    <BaseFormItem
+      v-for="item of renderedFields"
+      :key="item.key"
+      :field="item.field"
+      :grid="props.grid"
+      :disabled="props.disabled"
+      :set-form-item-ref="setFormItemRef"
+      :set-component-ref="setComponentRef"
+    />
+  </ElGrid>
+  <template v-else>
+    <BaseFormItem
+      v-for="item of renderedFields"
+      :key="item.key"
+      :field="item.field"
+      :grid="props.grid"
+      :disabled="props.disabled"
+      :set-form-item-ref="setFormItemRef"
+      :set-component-ref="setComponentRef"
+    />
+  </template>
+</template>

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

@@ -6,12 +6,12 @@
  *
  * 架构设计说明 (Architecture Overview)
  *
- * [ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]
+ * [ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItems / BaseFormItem / BaseField) ]
  *
  * 1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）
  *    均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。
  * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件。
- * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成。
+ * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItems>` 递归完成。
  *
  * @public
  *
@@ -57,7 +57,7 @@ import {
   type Slot,
 } from 'vue';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
-import BaseFormItem from '../BaseFormItem/index.vue';
+import BaseFormItems from '../BaseFormItems/index.vue';
 import { InjectionFormKey, InjectionFormSlotsKey } from '../../constants';
 import type { Grid, VModelProps, PathProps } from '../../types';
 import type { Path } from '../../../../shared/core';
@@ -178,7 +178,7 @@ provide(InjectionFormSlotsKey, formSlotsRef);
     class="pro-form"
     @submit.prevent
   >
-    <BaseFormItem
+    <BaseFormItems
       :fields="fields"
       :grid="props.grid"
       :disabled="formDisabled"

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

@@ -3,12 +3,12 @@ import type {
   ComponentExposed,
 } from 'vue-component-type-helpers';
 import ProForm from './ProForm/index.vue';
-import BaseFormItem from './BaseFormItem/index.vue';
+import BaseFormItems from './BaseFormItems/index.vue';
 
 export { default as BaseField } from './BaseField/index.vue';
 export { default as ContainerFragment } from './ContainerFragment/index.vue';
 export { default as SlotComponent } from './SlotComponent/index.vue';
-export { ProForm, BaseFormItem };
+export { ProForm, BaseFormItems };
 
 // instance
 /** ProForm 组件实例 */
@@ -16,7 +16,7 @@ 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>;
+/** BaseFormItems 组件实例（字段级 FormItem） */
+export type ProFormItemsInstance = ComponentExposed<typeof BaseFormItems>;
+/** BaseFormItems 组件属性（字段级 FormItem） */
+export type ProFormItemsProps = ComponentProps<typeof BaseFormItems>;