@qin-ui/antd-vue-pro 2.4.5 → 2.5.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/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,7 +43,8 @@
  * </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,
@@ -52,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';
 
@@ -78,13 +81,12 @@ const props = withDefaults(defineProps<Props>(), {
 
 /**
  * 依赖注入中心：
- * 未传 form 实例（含运行期置空）时惰性初始化内部表单实例；
+ * 未传 form 实例（含运行期置空）时回退内部表单实例；
  * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
  */
-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 当前实例；
@@ -119,7 +121,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 获取全局配置，响应式派生以支持动态配置变更
@@ -131,7 +133,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;
@@ -143,7 +148,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,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,19 +60,22 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
       if (isPlainObject(field)) {
         // prettier-ignore
-        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;
 
         // 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 };
 
-        // 分组字段默认整行（span 兜底 24），注入断点同样生效
+        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
         gridItemProps = fields
           ? { ...initGridItemProps, span: span ?? 24 }
           : initGridItemProps;
@@ -94,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 {

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

@@ -4,27 +4,31 @@ import type {
   FormInstance,
   FormItemProps,
 } from '../../../shared/ui';
-import { FormItem } from '../../../shared/ui';
+import type { FormItem } from '../../../shared/ui';
 import type {
   ComponentProps,
   ComponentSlots,
 } from 'vue-component-type-helpers';
+import type { VNode, VNodeProps } from 'vue';
 import {
-  type CSSProperties,
+  type ClassValue,
   type Component,
   type Raw,
   type MaybeRef,
   type ComputedRef,
-  VNode,
-  VNodeProps,
+  type StyleValue,
 } from 'vue';
-import { ComponentName, GetComponentType } from '../constants';
+import type { ComponentName, GetComponentType } from '../constants';
 import type { Data, Path } from '../../../shared/core';
+import type { AdditionalMethods } from '../../../shared/core';
+import type { FormItemInstance } from '../../../shared/ui';
 
 export type { FormInstance };
 
+/** 带 `path` 的组件属性：容器与插槽组件按该路径关联字段 */
 export type PathProps = { path?: string } & Data;
 
+/** `value` / `onUpdate:value` 形态的 v-model 属性 */
 export type VModelProps<T = any> = {
   value?: T;
   'onUpdate:value'?: (val: T) => void;
@@ -59,13 +63,14 @@ export type ValueFormatter =
   | { get?: (val: any) => any; set?: (val: any, oldVal?: any) => any };
 
 /**
- * @description 自定义组件
+ * 自定义组件
+ *
  * @example (p, ctx) => h('div', ctx.attrs)
  */
 export type RenderComponentType = Component<VModelProps & PathProps>;
 
 /**
- * @description 插槽组件类型
+ * 插槽组件类型
  */
 export type SlotComponentType =
   | Component<PathProps>
@@ -78,45 +83,55 @@ export type SlotComponentType =
   | ((...args: any[]) => SlotComponentType);
 
 /**
- * @description 容器组件类型
+ * 容器组件类型
  */
 export type ContainerComponent = Component<PathProps>;
 
 /**
- * @description 插槽对象类型
+ * 插槽对象类型
  */
 export type Slots = {
   [name: string]: SlotComponentType;
 };
 
+/** 选项项：`label` 展示文案与 `value` 取值，其余键透传控件 */
 export type Option = { label: string; value: any; [x: string]: any };
+/** 选项数组 */
 export type Options = Array<Option>;
 
+/** 表单栅格开关：`true` 启用默认栅格，或传 `GridProps` 自定义 */
 export type Grid = boolean | (GridProps & {});
 
+/** FormItem 自身的插槽集合（label / extra / help / tooltip 等） */
 export type FormItemSlots = ComponentSlots<typeof FormItem>;
 
 type BaseCommon<D extends Data = Data> = {
   /**
-   * @description 字段标识namePath, 同name
+   * 字段标识namePath, 同name
+   *
+   * 字段标识按 `name`、`path` 的顺序取首个非 `null` / `undefined` 的值（`name` 优先），
+   * 结果经 `normalizePathKey` 归一化，供渲染标识与 core 字段查找 API（`getField` / `setField` 等）共用；
+   * `name` 仅参与标识解析，不落入控件属性透传。与 `element-plus-pro` 口径不同（该包宿主标识键为 `prop`，`name` 仅透传控件）。
+   * 嵌套字段的 `path` 使用各自独立的完整路径（不与父级路径拼接），重复路径需自行保证唯一。
+   *
    * @example 'name' | 'age' | 'sex' | ...
    */
   path?: Path<D>;
-  /**
-   * @description 字段是否隐藏
-   */
+  /** 字段是否隐藏；支持布尔、Ref 与 ComputedRef 形式，渲染期统一按 `toValue` 取值 */
   hidden?: boolean;
   /**
-   * @description 字段是否禁用
+   * 字段是否禁用；字段级取值优先，未显式指定时继承上层（表单或宿主 Provider）的禁用上下文。
    */
   disabled?: boolean;
   /**
-   * @description 字段中文名称，支持字符串或组件
+   * 字段中文名称，支持字符串或组件
+   *
    * @example '姓名' | '年龄' | '性别' | () => h('span', '自定义标签')
    */
   label?: SlotComponentType;
   /**
-   * @description 字段插槽配置，可包含formItem插槽和component插槽
+   * 字段插槽配置，可包含formItem插槽和component插槽
+   *
    * @example
    * ```js
    * slots: {
@@ -128,27 +143,32 @@ type BaseCommon<D extends Data = Data> = {
    */
   slots?: Partial<FormItemSlots>;
   /**
-   * @description 字段formItem样式属性
+   * 字段formItem样式属性
+   *
    * @example { marginBottom: '8px', padding: '12px' }
    */
-  formItemStyle?: CSSProperties;
+  formItemStyle?: StyleValue;
   /**
-   * @description 字段formItem样式类名
+   * 字段formItem样式类名
+   *
    * @example 'custom-form-item' | 'required-field'
    */
-  formItemClass?: string;
+  formItemClass?: ClassValue;
   /**
-   * @description 字段formItem容器包裹组件
+   * 字段formItem容器包裹组件
+   *
    * @example (props, ctx) => h('div', { class: 'custom-container' }, ctx.slots.default?.())
    */
   formItemContainer?: ContainerComponent;
   /**
-   * @description 将属性附加到 FormItem 的 DOM 节点
+   * 将属性附加到 FormItem 的 DOM 节点
+   *
    * @example { 'data-form-item-test': 'test-value', 'aria-label': 'name' }
    */
   formItemDataAttrs?: Record<string, string>;
   /**
-   * @description 额外的自定义属性，不会被当作组件参数，仅用做给字段添加标识属性等功能
+   * 额外的自定义属性，不会被当作组件参数，仅用做给字段添加标识属性等功能
+   *
    * @example { group: 'group-1' }
    */
   extraProps?: Record<string, any>;
@@ -156,12 +176,14 @@ type BaseCommon<D extends Data = Data> = {
 
 type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
   /**
-   * @description 嵌套子字段配置
+   * 嵌套子字段配置
+   *
    * @example [{ key: 'firstName', label: '名' }, { key: 'lastName', label: '姓' }]
    */
   fields: Fields<D>;
   /**
-   * @description 网格布局属性，true表示使用默认网格布局，针对具有嵌套字段的字段
+   * 网格布局属性，true表示使用默认网格布局，针对具有嵌套字段的字段
+   *
    * @example boolean | { gutter: 24 }
    */
   grid?: Grid;
@@ -178,46 +200,47 @@ type BaseWithoutFields<D extends Data = Data> = BaseCommon<D> & {
   fields?: undefined;
   grid?: never;
   /**
-   * @description 字段component样式属性
+   * 字段component样式属性
+   *
    * @example { width: '100%', borderColor: '#d9d9d9' }
    */
-  componentStyle?: CSSProperties;
+  componentStyle?: StyleValue;
   /**
-   * @description 字段component样式类名
+   * 字段component样式类名
+   *
    * @example 'custom-input' | 'error-input'
    */
-  componentClass?: string;
+  componentClass?: ClassValue;
   /**
-   * @description 字段component容器包裹组件
+   * 字段component容器包裹组件
+   *
    * @example (props, ctx) => h('div', { class: 'input-wrapper' }, ctx.slots.default?.())
    */
   componentContainer?: ContainerComponent;
   /**
-   * @description 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   * 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   *
    * @example (val) => val?.trim()
    */
   valueFormatter?: ValueFormatter;
   /**
-   * @description 组件v-model双向绑定更新属性名，默认'value'
+   * 组件v-model双向绑定更新属性名，默认'value'
    */
   modelProp?: string;
   /**
-   * @description 将属性附加到表单组件的 DOM 节点
+   * 将属性附加到表单组件的 DOM 节点
+   *
    * @example { 'data-test': 'input-value', 'aria-label': 'name' }
    */
   componentDataAttrs?: Record<string, string>;
 };
 
-/**
- * @type {Object} Base - 基础公共字段类型
- */
+/** 基础公共字段类型 */
 export type Base<D extends Data = Data> =
   | BaseWithFields<D>
   | BaseWithoutFields<D>;
 
-/**
- * @type {FieldTypeMap} 字段类型集合
- */
+/** 字段类型集合 */
 export type FieldTypeMap<D extends Data = Data> = {
   [K in ComponentName]: K extends 'custom'
     ? WithCommon<{ slots?: Slots; [x: string]: any }, D> & {
@@ -227,7 +250,7 @@ export type FieldTypeMap<D extends Data = Data> = {
 };
 
 /**
- * @description 不支持响应式的属性名
+ * 不支持响应式的属性名
  */
 type NotSupportedRefOrGetterProps =
   | 'component'
@@ -241,7 +264,8 @@ type NotSupportedRefOrGetterProps =
 type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
 /**
- * @description 为对象属性添加响应式支持的类型
+ * 为对象属性添加响应式支持的类型
+ *
  * @template T - 原始类型
  */
 export type WithRef<T> = {
@@ -252,6 +276,12 @@ export type WithRef<T> = {
       : MaybeRefOrComputedRef<T[P]>;
 };
 
+/**
+ * 公共字段属性集合：FormItem 透传属性与 GridItem 栅格属性
+ *
+ * 栅格行为边界：字段显式指定 `span` 时整体接管栅格，不再叠加 Provider 注入的响应式断点；
+ * 未指定 `span` 时使用注入的断点配置。
+ */
 type WithCommonBase<T = unknown> = T &
   Omit<FormItemProps, 'label'> &
   GridItemProps;
@@ -265,7 +295,7 @@ type WithFields<D extends Data = Data> = WithRef<
 >;
 
 /**
- * @description 合并 FormItem 插槽与组件插槽
+ * 合并 FormItem 插槽与组件插槽
  */
 export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
   [K in keyof FormItemSlots | keyof CS]: K extends keyof FormItemSlots
@@ -276,7 +306,8 @@ export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
 }>;
 
 /**
- * @description 自动从 Vue 组件提取 Props 和 Slots，并加上公共表单字段属性
+ * 自动从 Vue 组件提取 Props 和 Slots，并加上公共表单字段属性
+ *
  * @template T - Vue 组件类型
  * @template D - 数据对象类型
  */
@@ -288,17 +319,19 @@ type WithComponent<T, D extends Data = Data> = Omit<
 };
 
 /**
- * @description 字段配置类型，包含所有字段属性和响应式支持
+ * 字段配置类型，包含所有字段属性和响应式支持
+ *
  * @template D - 数据对象类型
  * @public
  */
 export type Field<
   C extends ComponentName = ComponentName,
   D extends Data = Data,
-> = FieldTypeMap<D>[C] | WithFields<D>;
+> = (FieldTypeMap<D>[C] | WithFields<D>) & AdditionalMethods<FormItemInstance>;
 
 /**
- * @description 字段数组类型
+ * 字段数组类型
+ *
  * @template D - 数据对象类型
  * @public
  */

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

@@ -0,0 +1,27 @@
+import { toRaw } from 'vue';
+
+const fieldKeyMap = new WeakMap<object, number>();
+let fieldKeySeed = 0;
+
+/**
+ * 字段渲染 key
+ *
+ * @description 以 `toRaw(field)` 为键在模块级 WeakMap 中缓存自增编号，同一字段对象恒得同一 key：
+ * key 与字段在数组中的位置解耦，字段插入 / 删除 / 重排 / 过滤后仍与对象绑定；同 `path` 的兄弟字段各得其唯一 key。
+ * 非对象项无对象身份，按字面量生成稳定 key；渲染路径传入的字段项已由调用方过滤为非 null 对象，
+ * 该分支供本模块的直接调用者使用
+ *
+ * @param field - 字段配置项
+ * @returns 字段渲染 key
+ */
+export const getFieldKey = (field: unknown): string | number => {
+  if (field === null || typeof field !== 'object')
+    return `raw_${String(field)}`;
+  const raw = toRaw(field);
+  let key = fieldKeyMap.get(raw);
+  if (key === undefined) {
+    key = ++fieldKeySeed;
+    fieldKeyMap.set(raw, key);
+  }
+  return key;
+};