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

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';
@@ -105,7 +105,14 @@ const fields = computed(() => {
   return (Array.isArray(f) ? f : f?.value) ?? [];
 });
 const formData = computed(() => currentForm.value?.formData);
-const setFormRef = (el: any) => currentForm.value?.setFormRef?.(el);
+/*
+ * ref 回调按渲染期实例路由：卸载回调（null）写回该子树所属表单，
+ * 运行期替换 :form 后旧实例的 formRef 同步清空
+ */
+const formRefSetter = computed(() => {
+  const form = currentForm.value;
+  return (el: any) => form?.setFormRef?.(el);
+});
 
 /*
  * formKey 子树重挂载契约：以 WeakMap 为每个 form 实例生成自增 key，绑定到原生 Form 的 :key
@@ -172,13 +179,13 @@ provide(InjectionFormSlotsKey, formSlotsRef);
   <!-- el-form 渲染原生 form 元素，拦截回车触发的默认提交 -->
   <ElForm
     :key="formKey"
-    :ref="setFormRef"
+    :ref="formRefSetter"
     :model="formData"
     v-bind="formAttrs"
     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>;

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

@@ -1,5 +1,11 @@
-import { computed, inject, mergeProps, toValue, type ComputedRef } from 'vue';
-import { getFieldKey } from '../utils/fieldKey';
+import {
+  computed,
+  inject,
+  mergeProps,
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from 'vue';
 import {
   formItemProps,
   gridItemProps,
@@ -26,9 +32,87 @@ export interface GroupedField {
   componentProps: Record<string, any>;
   container?: Base['formItemContainer'];
   rawField: Field;
-  renderKey: string | number;
 }
 
+/** 将单个字段配置拆分为 grid / formItem / component / slots 分组 */
+const groupField = (
+  field: Field,
+  rawInjectProps: Record<string, any>
+): GroupedField => {
+  let gridItemProps: Record<string, any> = {};
+  let formItemProps: Record<string, any> = {};
+  const componentProps: Record<string, any> = { slots: {} };
+  const formItemSlots: Record<string, any> = {};
+
+  if (isPlainObject(field)) {
+    // prettier-ignore
+    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 时使用注入的断点配置
+     */
+    const initGridItemProps =
+      span || span === 0 ? { span } : { xs, sm, md, lg, xl, span: injectSpan };
+
+    // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
+    gridItemProps = fields
+      ? { ...initGridItemProps, span: span ?? 24 }
+      : initGridItemProps;
+    formItemProps = mergeProps(
+      injectRest as any,
+      { class: injectClassName, style: injectStyle },
+      { class: toValue(formItemClass), style: toValue(formItemStyle) },
+      formItemDataAttrs
+    );
+    // 字段级容器优先，回退注入级配置
+    const container = formItemContainer ?? injectFormItemContainer;
+
+    Object.keys(rest).forEach(k => {
+      if (gridItemPropKeySet.has(k)) {
+        gridItemProps[k] = rest[k];
+      } else if (formItemPropKeySet.has(k)) {
+        (formItemProps as any)[k] = rest[k];
+      } else {
+        componentProps[k] = rest[k];
+      }
+    });
+
+    Object.assign(componentProps, componentDataAttrs);
+    Object.keys(slots).forEach(k => {
+      if (formItemSlotKeySet.has(k)) {
+        formItemSlots[k] = slots[k];
+      } else {
+        componentProps.slots[k] = slots[k];
+      }
+    });
+
+    // 字段标识经统一解析（prop 优先，path 兜底）；name 作为控件自身属性经 rest 透传
+    return {
+      path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
+      gridItemProps: gridItemProps as GridItemProps,
+      formItemProps: formItemProps as any,
+      formItemSlots,
+      componentProps,
+      container,
+      rawField: field,
+    };
+  }
+
+  return {
+    path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
+    gridItemProps: gridItemProps as GridItemProps,
+    formItemProps: formItemProps as any,
+    formItemSlots,
+    componentProps,
+    rawField: field,
+  };
+};
+
 /**
  * 将 fields 配置数组逐个拆分为 grid / formItem / component / slots 分组。
  *
@@ -45,82 +129,23 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
   return computed<GroupedField[]>(() => {
     const rawInjectProps = toValue(injectFormItemProps) || {};
-    return validFields.value.map(field => {
-      let gridItemProps: Record<string, any> = {};
-      let formItemProps: Record<string, any> = {};
-      const componentProps: Record<string, any> = { slots: {} };
-      const formItemSlots: Record<string, any> = {};
-
-      if (isPlainObject(field)) {
-        // prettier-ignore
-        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 时使用注入的断点配置
-         */
-        const initGridItemProps =
-          span || span === 0
-            ? { span }
-            : { xs, sm, md, lg, xl, span: injectSpan };
-
-        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
-        gridItemProps = fields
-          ? { ...initGridItemProps, span: span ?? 24 }
-          : initGridItemProps;
-        formItemProps = mergeProps(
-          injectRest as any,
-          { class: injectClassName, style: injectStyle },
-          { class: toValue(formItemClass), style: toValue(formItemStyle) },
-          formItemDataAttrs
-        );
-        const container = formItemContainer ?? injectFormItemContainer;
-
-        Object.keys(rest).forEach(k => {
-          if (gridItemPropKeySet.has(k)) {
-            gridItemProps[k] = rest[k];
-          } else if (formItemPropKeySet.has(k)) {
-            (formItemProps as any)[k] = rest[k];
-          } else {
-            componentProps[k] = rest[k];
-          }
-        });
-
-        Object.assign(componentProps, componentDataAttrs);
-        Object.keys(slots).forEach(k => {
-          if (formItemSlotKeySet.has(k)) {
-            formItemSlots[k] = slots[k];
-          } else {
-            componentProps.slots[k] = slots[k];
-          }
-        });
+    return validFields.value.map(field => groupField(field, rawInjectProps));
+  });
+}
 
-        // 字段标识经统一解析（prop 优先，path 兜底）；name 作为控件自身属性经 rest 透传
-        return {
-          path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
-          gridItemProps: gridItemProps as GridItemProps,
-          formItemProps: formItemProps as any,
-          formItemSlots,
-          componentProps,
-          container,
-          rawField: field,
-          renderKey: getFieldKey(field),
-        };
-      }
+/**
+ * 将单个字段配置拆分为 grid / formItem / component / slots 分组
+ *
+ * @description 拆分规则与 `useGroupFieldAttrs` 一致，结果依赖该字段自身配置与 Provider 的 `pro-form-item` 默认值。
+ *
+ * @param {MaybeRefOrGetter<Field>} field - 待拆分的字段配置
+ * @returns {ComputedRef<GroupedField>} 单字段渲染分组
+ */
+export function useGroupedField(field: MaybeRefOrGetter<Field>) {
+  const config = INJECT_CONFIG['pro-form-item'];
+  const injectFormItemProps = inject(config.injectionKey, config.default);
 
-      return {
-        path: resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS),
-        gridItemProps: gridItemProps as GridItemProps,
-        formItemProps: formItemProps as any,
-        formItemSlots,
-        componentProps,
-        rawField: field,
-        renderKey: getFieldKey(field),
-      };
-    });
-  });
+  return computed<GroupedField>(() =>
+    groupField(toValue(field), toValue(injectFormItemProps) || {})
+  );
 }

package/src/components/form/utils/fieldKey.ts

@@ -1,4 +1,6 @@
 import { toRaw } from 'vue';
+import { resolveFieldIdentity, toPath } from '../../../shared/core';
+import { ELEMENT_FIELD_IDENTITY_KEYS } from '../constants';
 
 const fieldKeyMap = new WeakMap<object, number>();
 let fieldKeySeed = 0;
@@ -25,3 +27,65 @@ export const getFieldKey = (field: unknown): string | number => {
   }
   return key;
 };
+
+/** 数据行对象身份编号 */
+const rowKeyMap = new WeakMap<object, number>();
+let rowKeySeed = 0;
+
+const getRowKey = (row: object) => {
+  const raw = toRaw(row);
+  let key = rowKeyMap.get(raw);
+  if (key === undefined) {
+    key = ++rowKeySeed;
+    rowKeyMap.set(raw, key);
+  }
+  return key;
+};
+
+/** 数组下标段判定：仅十进制非负整数段按数组下标处理 */
+const isIndexSegment = (segment: string) => /^(?:0|[1-9]\d*)$/.test(segment);
+
+/**
+ * 字段的数据行渲染 key
+ *
+ * @description 沿字段路径逐段解析原始表单数据，取路径经过的对象数组行元素身份与行内剩余路径组成 key；
+ * 同一数据行对象在数组增删 / 重排后恒得同一 key。路径不经过对象数组行、行元素为原始值或数据缺失时，
+ * 回退到 {@link getFieldKey} 的字段对象身份。同 key 的去重由调用方按兄弟列表收敛。
+ *
+ * @param field - 字段配置项
+ * @param rawFormData - 原始表单数据（非响应式对象）
+ * @returns 数据行 key；无法定位数据行时返回字段对象身份 key
+ */
+export const getFieldDataKey = (
+  field: unknown,
+  rawFormData: unknown
+): string | number => {
+  const path = resolveFieldIdentity(field, ELEMENT_FIELD_IDENTITY_KEYS);
+  if (!path || rawFormData === null || rawFormData === undefined) {
+    return getFieldKey(field);
+  }
+
+  const segments = toPath(path);
+  let node: any = rawFormData;
+  const rowIds: number[] = [];
+  let lastRowIndex = -1;
+
+  for (let i = 0; i < segments.length; i++) {
+    if (Array.isArray(node)) {
+      const segment = segments[i];
+      if (!isIndexSegment(segment)) break;
+      const element = node[Number(segment)];
+      if (element === null || typeof element !== 'object') break;
+      rowIds.push(getRowKey(toRaw(element) as object));
+      lastRowIndex = i;
+      node = element;
+      continue;
+    }
+    if (node === null || typeof node !== 'object') break;
+    node = node[segments[i]];
+  }
+
+  if (lastRowIndex === -1) return getFieldKey(field);
+  const rest = segments.slice(lastRowIndex + 1).join('.');
+  return `data:${rowIds.join('/')}:${rest}`;
+};

package/src/components/table/components/ProTable.vue

@@ -87,6 +87,7 @@ import { useLocale } from '../../../locale';
 import type { Path } from '../../../shared/core';
 import {
   camelizeProperties,
+  callListeners,
   getObject,
   isObjectItem,
   isPlainObject,
@@ -243,16 +244,21 @@ const _search = async () => {
   if (props.search && attrs.onSearch) {
     warnSearchConfig('duplicate');
   }
-  if (!search) return;
-  const searchPromise = search();
-  if (!isPromise(searchPromise)) {
+  const results = callListeners(search);
+  if (!results.length) return;
+  const promises = results.filter(isPromise);
+  if (!promises.length) {
     warnSearchConfig('not-promise');
     return;
   }
   const seq = ++searchSequence;
   loading.value = true;
   try {
-    await searchPromise;
+    const settled = await Promise.allSettled(promises);
+    const rejected = settled.find(item => item.status === 'rejected') as
+      | PromiseRejectedResult
+      | undefined;
+    if (rejected) throw rejected.reason;
   } finally {
     if (seq === searchSequence) {
       loading.value = false;
@@ -472,7 +478,7 @@ const onSizeChange = (pageSize: number) => {
 
 const onPaginationChange = (currentPage: number, pageSize: number) => {
   // 透传 el-pagination change 回调
-  attrs.onChange?.(currentPage, pageSize);
+  callListeners(attrs.onChange, currentPage, pageSize);
 };
 
 const searchFormVisible = computed(() => {

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

@@ -59,6 +59,7 @@ export type Column<D extends Data = Data> = Partial<
    * 列是否隐藏；支持布尔、Ref 与 ComputedRef 形式，渲染期按 `toValue` 取值
    *
    * 分组列的子列同样参与过滤（递归生效）。
+   * 只读 ref（如 `computed`）经 `setColumn` 写入时会被普通值替换，可写 ref 保持绑定。
    */
   hidden?: MaybeRefOrComputedRef<boolean>;
   /** 自定义渲染函数 */

package/src/shared/core/index.ts

@@ -23,6 +23,7 @@ export {
   InjectionFormSlotsKey,
   // utils
   getObject,
+  mergeComponentVars,
   omitBy,
   get,
   set,
@@ -35,6 +36,7 @@ export {
   isPlainObject,
   isObjectItem,
   isPromise,
+  callListeners,
   // locale
   zhCN,
   zhTW,