@qin-ui/antd-vue-pro 2.4.4 → 2.5.0

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

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 /**
+ * 表单字段渲染引擎
+ *
  * @component BaseFormItem
- * @description 表单字段渲染引擎
  *
  * 负责将字段配置数组渲染为实际的表单项，支持：
  * - 字段分组（嵌套 fields 递归渲染）
@@ -13,35 +14,40 @@
  * ## 渲染流程
  *
  * 1. 遍历 fields 数组，过滤 hidden 字段
- * 2. 通过 useGroupFieldAttrs Hook 纯计算将 field 配置拆分为 gridItemProps / formItemProps / componentProps / slots
+ * 2. 将字段属性分流为 GridItem / FormItem / 组件 / 插槽四类
  * 3. 递归渲染 BaseFormItem（嵌套表单）或 BaseField（输入组件）
- * 4. 通过 ref 回调收集 FormItem 和 Component 实例，注入到 field 对象上
+ * 4. 渲染后字段对象上可读取 FormItem 与组件实例
  *
- * @param {Fields<D>} [fields] - 字段配置数组
+ * @param {Fields} [fields] - 字段配置数组
  * @param {boolean | GridProps} [grid] - 是否启用网格布局
  * @param {boolean} [disabled] - 是否禁用所有子字段
  *
  * @internal
  */
-import { getObject, toPath } from '../../../../shared/core';
+import { getObject, isObjectItem, toPath } from '../../../../shared/core';
+import type { GridProps } from '../../../../shared/ui';
 import {
   FormItem,
   Grid as AGrid,
   GridItem as AGridItem,
-  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';
 
 defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
 
 type Props = {
+  /** 是否启用网格布局 */
   grid?: Grid;
+  /** 字段配置数组 */
   fields?: Fields;
+  /** 是否禁用所有子字段 */
   disabled?: boolean;
 };
 const props = withDefaults(defineProps<Props>(), {
@@ -51,8 +57,10 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 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)
+  )
 );
 
 // 向下注入表单级禁用上下文，BaseField 经 useInjectDisabled 消费
@@ -75,18 +83,56 @@ 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 等实例访问器挂载失败。'
+      );
+    }
+  }
+};
+
+/*
+ * 字段值变更经 BaseField 的 field-value-change 事件回传，由 FormItem 暴露的 onFieldChange 触发校验；
+ * autoLink 为 false 时保持用户自行校验的语义
+ */
+const onFieldValueChange = (item: any) => {
+  if (item.formItemProps?.autoLink === false) return;
+  const instance = formItemInstanceMap.get(toRaw(item.rawField));
+  instance?.onFieldChange?.();
+};
+
 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;
@@ -99,10 +145,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;
@@ -118,7 +165,7 @@ const groupedFields = useGroupFieldAttrs(validFields);
     :component="enableGrid ? AGrid : undefined"
     v-bind="computedGridProps"
   >
-    <template v-for="(item, index) of groupedFields" :key="item.path || index">
+    <template v-for="item of groupedFields" :key="item.renderKey">
       <ContainerFragment
         :component="enableGrid ? AGridItem : undefined"
         v-bind="item.gridItemProps"
@@ -156,6 +203,7 @@ const groupedFields = useGroupFieldAttrs(validFields);
                 :ref="el => setComponentRef(item.rawField, el)"
                 v-bind="item.componentProps"
                 :path="item.path"
+                @field-value-change="onFieldValueChange(item)"
               />
             </template>
           </FormItem>

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

@@ -1,13 +1,15 @@
 <script lang="ts" setup>
 /**
+ * 容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。
+ *
  * @component ContainerFragment
- * @description 容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。
  *
  * @public
  */
 import type { ContainerComponent } from '../../types';
 
 type Props = {
+  /** 容器组件，未提供时不渲染包裹层 */
   component?: ContainerComponent;
 };
 

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/antd-vue-pro 配置驱动表单组件
  *
  * 架构设计说明 (Architecture Overview)
  *
@@ -25,7 +26,7 @@
  * @template F - 表单实例类型
  *
  * @param {F} [form] - useForm 返回的表单实例
- * @param {boolean | GridProps} [grid=false] - 是否启用网格布局
+ * @param {boolean | GridProps} [grid] - 是否启用网格布局；未提供时回退 Provider 注入的 `grid` 配置
  * @param {...FormProps} ...attrs - Ant Design Vue Form 组件的其他属性
  *
  * @slot default - 默认插槽，可用于添加额外内容
@@ -42,24 +43,29 @@
  * </template>
  * ```
  */
-import { Form as AForm, FormProps as AFormProps } from '../../../../shared/ui';
+import type { FormProps as AFormProps } from '../../../../shared/ui';
+import { Form as AForm } from '../../../../shared/ui';
 import {
   computed,
   inject,
   mergeProps,
+  onUpdated,
   provide,
+  shallowRef,
   toValue,
-  useAttrs,
+  triggerRef,
   type Slot,
 } 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';
 
@@ -69,19 +75,18 @@ type MyFormProps = Partial<Omit<AFormProps, 'model'>>;
 
 type Props = { grid?: Grid; form?: F } & /* @vue-ignore */ MyFormProps;
 const props = withDefaults(defineProps<Props>(), {
-  grid: false,
+  grid: undefined,
   form: undefined,
 });
 
 /**
  * 依赖注入中心：
- * 若外部未传 form 实例，则自动初始化内部表单实例；
+ * 未传 form 实例（含运行期置空）时回退内部表单实例；
  * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
  */
-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 当前实例；
@@ -105,6 +110,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);
   }
@@ -115,20 +121,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;
@@ -138,11 +146,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,27 +1,37 @@
 <script lang="ts" setup>
 /**
+ * 插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数、组件定义对象或静态字符串。
+ *
  * @component SlotComponent
- * @description 插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。
  *
  * @public
  */
-import { isVNode } from 'vue';
-import { SlotComponentType } from '../../types';
+import type { SlotComponentType } from '../../types';
 
 defineOptions({ name: 'SlotComponent', inheritAttrs: false });
 
 type Props = {
+  /** 插槽内容：VNode、渲染函数、组件定义对象或文本 */
   component?: SlotComponentType;
 };
 const props = withDefaults(defineProps<Props>(), {
   component: undefined,
 });
+
+/*
+ * 可组件化渲染判定：VNode / 函数（含函数式组件）/ 组件定义对象
+ * 其余（string/number/boolean/null/undefined）一律按文本渲染，不作为 <component :is> 的标签名解析
+ */
+const isRenderable = (c: Props['component']) =>
+  c !== null &&
+  c !== undefined &&
+  (typeof c === 'function' || typeof c === 'object');
 </script>
 
 <template>
   <component
     :is="props.component"
-    v-if="isVNode(props.component) || typeof props.component === 'function'"
+    v-if="isRenderable(props.component)"
     v-bind="$attrs"
   />
   <template v-else>{{ props.component }}</template>

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 的组件实例类型，用于 `ref` 标注与 `defineExpose` 访问 */
 export type ProFormInstance = ComponentExposed<typeof ProForm>;
+/** ProForm 的组件属性类型 */
 export type ProFormProps = ComponentProps<typeof ProForm>;
 
+/** BaseFormItem 的组件实例类型 */
 export type ProFormItemInstance = ComponentExposed<typeof BaseFormItem>;
+/** BaseFormItem 的组件属性类型 */
 export type ProFormItemProps = ComponentProps<typeof BaseFormItem>;

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

@@ -45,14 +45,13 @@ export const FORM_ITEM_SLOT_KEYS = [
  * }
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface ComponentMap {}
+export interface ComponentMap {} // eslint-disable-line @typescript-eslint/no-empty-object-type
 
+// prettier-ignore
 /**
  * 内置组件映射表
  * @description Ant Design Vue 内置支持的组件类型映射
  */
-// prettier-ignore
 export type BaseComponentMap = {
   'input': typeof Input;
   'textarea': typeof Textarea;
@@ -102,10 +101,10 @@ export type GetComponentType<K extends ComponentName> =
       ? BaseComponentMap[K]
       : never;
 
+// prettier-ignore
 /**
  * 组件名称到 Ant Design Vue 组件的映射
  */
-// prettier-ignore
 export const componentMap: BaseComponentMap = {
   'input': Input,
   'textarea': Textarea,

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

@@ -1,4 +1,4 @@
-import { FormItemInstance } from '../../../shared/ui';
+import type { FormItemInstance } from '../../../shared/ui';
 import {
   useFields as coreUseFields,
   type UseFieldsReturn,
@@ -21,6 +21,8 @@ import type { ComponentName } from '../constants';
  * - 字段的添加、插入、删除
  * - 父级字段查找
  *
+ * 字段标识按 `name`、`path` 的顺序取首个非 `null` / `undefined` 的值。
+ *
  * @template D - 表单数据类型
  * @param {Fields<D>} [initFields] - 初始字段配置数组
  *

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

@@ -1,11 +1,12 @@
 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 type { Base, Field } from '../types';
@@ -14,19 +15,28 @@ const formItemPropKeys = Object.keys(formItemProps()).concat([
   'formItemContainer',
 ]);
 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);
 
+/** 单个字段拆解后的渲染分组 */
 export interface GroupedField {
+  /** 解析后的字段标识（`name` 优先于 `path`） */
   path: string;
+  /** 透传给栅格容器（GridItem）的属性 */
   gridItemProps: GridItemProps;
+  /** 透传给 FormItem 的属性 */
   formItemProps: FormItemProps;
+  /** 归属 FormItem 的插槽 */
   formItemSlots: Record<(typeof FORM_ITEM_SLOT_KEYS)[number], any>;
+  /** 透传给输入组件的属性（含组件插槽） */
   componentProps: Record<string, any>;
+  /** 该字段的外层包裹容器 */
   formItemContainer?: Base['formItemContainer'];
+  /** 字段原始对象，供实例登记与访问器挂载使用 */
   rawField: Field;
+  /** 渲染 key，取自字段对象身份 */
+  renderKey: string | number;
 }
 
 /**
@@ -50,31 +60,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, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, formItemContainer, ...rest } =
+        const { path: _path, name: _name, fields, formItemClass, formItemStyle, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, formItemContainer, ...rest } =
           field as any;
 
-        const {
-          class: injectClassName,
-          style: injectStyle,
-          span: injectSpan,
-          xs,
-          sm,
-          md,
-          lg,
-          xl,
-          xxl,
-          formItemContainer: injectFormItemContainer,
-          ...injectRest
-        } = rawInject;
+        // prettier-ignore
+        const { class: injectClassName, style: injectStyle, span: injectSpan, xs, sm, md, lg, xl, xxl, formItemContainer: injectFormItemContainer, ...injectRest } = rawInject;
 
-        // 字段显式 span 优先，否则回退注入配置的响应式断点
+        /*
+         * 字段显式指定 span 时整体接管栅格，不再叠加注入的响应式断点；
+         * 未指定 span 时使用注入的断点配置
+         */
         const initGridItemProps =
           span || span === 0
             ? { span }
             : { xs, sm, md, lg, xl, xxl, span: injectSpan };
 
-        gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
+        gridItemProps = fields
+          ? { ...initGridItemProps, span: span ?? 24 }
+          : initGridItemProps;
         // 字段级容器优先，回退注入级配置
         const container = formItemContainer ?? injectFormItemContainer;
         formItemProps = mergeProps(
@@ -103,30 +107,33 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
           }
         });
 
-        const raw = (toValue(name) ?? toValue(path)) as
-          | string
-          | number[]
-          | undefined;
+        // label 插槽与字段 label 同时存在时由插槽渲染，剥离 label 属性
+        if (formItemSlots.label && formItemProps.label !== undefined) {
+          delete formItemProps.label;
+        }
+
+        const raw = resolveFieldIdentity(field);
         return {
-          path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+          path: raw,
           gridItemProps: gridItemProps as GridItemProps,
           formItemProps: formItemProps as any,
           formItemSlots,
           componentProps,
           formItemContainer: container,
           rawField: field,
+          renderKey: getFieldKey(field),
         };
       }
 
-      const raw =
-        toValue((field as any)?.name) ?? toValue((field as any)?.path);
+      const raw = resolveFieldIdentity(field);
       return {
-        path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+        path: raw,
         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 {