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

package/es/locale/index.d.ts

@@ -1,6 +1,8 @@
 import { InjectionKey, MaybeRef } from 'vue';
 import { zhCN, zhTW, enUS, ProLocale, ProLocaleName } from '../shared/core';
+/** 内置语言包：简体中文 / 繁体中文 / 英文 */
 export { zhCN, zhTW, enUS };
+/** 文案表类型：键为内置文案 key，值为任意字符串 */
 export type { ProLocale };
 /** ProComponentProvider 通过该 key 注入局部覆盖文案 */
 export declare const LOCALE_INJECT_KEY: InjectionKey<MaybeRef<Partial<ProLocale> | undefined>>;

package/es/locale/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locale/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,KAAK,CAAC;AACb,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,IAAI,EAGJ,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAE5B,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAC1C,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,CAClB,CAAC;AAEzB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS;aAWJ,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,MAAM;;CAQ1E,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locale/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,KAAK,CAAC;AACb,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,IAAI,EAGJ,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAGxB,6BAA6B;AAC7B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAE5B,+BAA+B;AAC/B,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAC1C,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,CAClB,CAAC;AAEzB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS;aAWJ,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,MAAM;;CAQ1E,CAAC"}

package/es/shared/core/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * 统一 re-export @qin-ui/pro-components-core，包内所有文件通过此文件引入 core 内容。
  */
-export { useForm, createFormProxy, useTable, useSearchFormExpand, useFields, useFormData, useFormRef, InjectionFormKey, InjectionFormSlotsKey, getObject, get, set, normalizePathKey, toPath, camelizeProperties, cloneDeep, pick, isPlainObject, isPromise, zhCN, zhTW, enUS, format, resolveLocaleName, type ProLocale, type ProLocaleName, type ProLocaleKey, type Data, type Path, type Paths, type KeyExpandString, type ExtendWithAny, type DeepPartial, type PageParam, type Fields, type Form, type Table, type UseFieldsReturn, type UseFormDataReturn, type UseFormRefReturn, } from '@qin-ui/pro-components-core';
+export { type AdditionalMethods, localePacks, normalizeColumn, normalizeColumns, useForm, createFormProxy, useTable, useSearchFormExpand, useFields, resolveFieldIdentity, DEFAULT_FIELD_IDENTITY_KEYS, useFormData, useFormRef, useReactiveAttrs, InjectionFormKey, InjectionFormSlotsKey, getObject, omitBy, get, set, normalizePathKey, toPath, camelizeProperties, cloneDeep, pick, omit, isPlainObject, isObjectItem, isPromise, zhCN, zhTW, enUS, format, resolveLocaleName, type ProLocale, type ProLocaleName, type ProLocaleKey, type Data, type Path, type Paths, type KeyExpandString, type ExtendWithAny, type DeepPartial, type PageParam, type Fields, type Form, type Table, type UseFieldsReturn, type UseFormDataReturn, type UseFormRefReturn, } from '@qin-ui/pro-components-core';
 //# sourceMappingURL=index.d.ts.map

package/es/shared/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAEL,OAAO,EACP,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,SAAS,EACT,WAAW,EACX,UAAU,EAEV,gBAAgB,EAChB,qBAAqB,EAErB,SAAS,EACT,GAAG,EACH,GAAG,EACH,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,SAAS,EACT,IAAI,EACJ,aAAa,EACb,SAAS,EAET,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,IAAI,EACT,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACtB,WAAW,EACX,eAAe,EACf,gBAAgB,EAEhB,OAAO,EACP,eAAe,EACf,QAAQ,EACR,mBAAmB,EACnB,SAAS,EACT,oBAAoB,EACpB,2BAA2B,EAC3B,WAAW,EACX,UAAU,EACV,gBAAgB,EAEhB,gBAAgB,EAChB,qBAAqB,EAErB,SAAS,EACT,MAAM,EACN,GAAG,EACH,GAAG,EACH,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,aAAa,EACb,YAAY,EACZ,SAAS,EAET,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,iBAAiB,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,IAAI,EACT,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,6BAA6B,CAAC"}

package/es/shared/ui/index.d.ts

@@ -1,15 +1,27 @@
-import { FormProps as _FormProps } from 'ant-design-vue';
+import { FormProps as _FormProps, Table, TableProps as _TableProps } from 'ant-design-vue';
+import { ComponentProps } from 'vue-component-type-helpers';
 import { Options } from 'scroll-into-view-if-needed';
-export { theme, Form, FormItem, Row as Grid, Col as GridItem, Table, Space, MenuDivider, Dropdown, Menu, MenuItem, Checkbox, Button, Cascader, CheckboxGroup, DatePicker, Input, InputNumber, InputPassword, InputSearch, RadioGroup, Select, Slider, Switch, Textarea, TimePicker, Transfer, TreeSelect, RangePicker, type FormItemInstance, type FormInstance, type RowProps as GridProps, type ColProps as GridItemProps, type FormItemProps, type TableProps, type PaginationProps, } from 'ant-design-vue';
+export { theme, Form, FormItem, Row as Grid, Col as GridItem, Table, Space, MenuDivider, Dropdown, Menu, MenuItem, Checkbox, Button, Cascader, CheckboxGroup, DatePicker, Input, InputNumber, InputPassword, InputSearch, RadioGroup, Select, Slider, Switch, Textarea, TimePicker, Transfer, TreeSelect, RangePicker, type FormItemInstance, type FormInstance, type RowProps as GridProps, type ColProps as GridItemProps, type FormItemProps, type PaginationProps, } from 'ant-design-vue';
 export { type ColumnType, tableProps } from 'ant-design-vue/es/table';
 export { type RangePickerProps } from 'ant-design-vue/es/date-picker';
 export { useConfigContextInject } from 'ant-design-vue/es/config-provider/context';
 export { useInjectDisabled, useProviderDisabled, } from 'ant-design-vue/es/config-provider/DisabledContext';
 export { colProps as gridItemProps } from 'ant-design-vue/es/grid/Col';
-export { formItemProps, useInjectFormItemContext, } from 'ant-design-vue/es/form';
+export { formItemProps } from 'ant-design-vue/es/form';
+export { useInjectFormItemContext, useProvideFormItemContext, } from 'ant-design-vue/es/form/FormItemContext';
 export { type NamePath } from 'ant-design-vue/es/form/interface';
 export { type MenuItemType } from 'ant-design-vue/es/menu/src/interface';
+/** 宿主 Form 属性面；`scrollToFirstError` 放宽为布尔或滚动配置对象 */
 export type FormProps = Omit<_FormProps, 'scrollToFirstError'> & {
     scrollToFirstError?: boolean | Options<any>;
 };
+/**
+ * 表格完整属性面
+ *
+ * @description 由宿主 `TableProps` 与其未声明的 emit 型属性键组成；
+ * ant-design-vue 的 Table 未暴露 `scroll` 事件面，故不提供 `@scroll` 入口。
+ */
+export interface TableProps extends _TableProps {
+    'onUpdate:expandedRowKeys'?: ComponentProps<typeof Table>['onUpdate:expandedRowKeys'];
+}
 //# sourceMappingURL=index.d.ts.map

package/es/shared/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EACL,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,IAAI,IAAI,EACX,GAAG,IAAI,QAAQ,EACf,KAAK,EACL,KAAK,EACL,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,aAAa,EACb,UAAU,EACV,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,MAAM,EACN,MAAM,EACN,MAAM,EACN,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,QAAQ,IAAI,SAAS,EAC1B,KAAK,QAAQ,IAAI,aAAa,EAC9B,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EACL,aAAa,EACb,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,GAAG;IAC/D,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,IAAI,UAAU,EACvB,KAAK,EACL,UAAU,IAAI,WAAW,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EACL,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,IAAI,IAAI,EACX,GAAG,IAAI,QAAQ,EACf,KAAK,EACL,KAAK,EACL,WAAW,EACX,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,aAAa,EACb,UAAU,EACV,KAAK,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,UAAU,EACV,MAAM,EACN,MAAM,EACN,MAAM,EACN,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,QAAQ,IAAI,SAAS,EAC1B,KAAK,QAAQ,IAAI,aAAa,EAC9B,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,GAAG;IAC/D,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,0BAA0B,CAAC,EAAE,cAAc,CACzC,OAAO,KAAK,CACb,CAAC,0BAA0B,CAAC,CAAC;CAC/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/antd-vue-pro",
-  "version": "2.4.5",
+  "version": "2.5.0",
   "description": "二次封装antd vue组件",
   "bin": {
     "antd-vue-pro": "./bin/init-ai.mjs"
@@ -14,7 +14,8 @@
       "types": "./es/index.d.ts",
       "import": "./es/index.js"
     },
-    "./antd-vue-pro.css": "./es/antd-vue-pro.css"
+    "./antd-vue-pro.css": "./es/antd-vue-pro.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "es",
@@ -44,9 +45,10 @@
   "dependencies": {
     "scroll-into-view-if-needed": "^3.1.0",
     "vue-component-type-helpers": "^3.2.5",
-    "@qin-ui/pro-components-core": "^2.0.4"
+    "@qin-ui/pro-components-core": "^2.1.0"
   },
   "devDependencies": {
+    "@types/node": "^24",
     "@vue/test-utils": "^2.4.11",
     "ant-design-vue": "^4.2.6",
     "happy-dom": "^20.11.6",

package/src/components/component-provider/components/index.vue

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 /**
+ * 全局配置提供者组件
+ *
  * @component ProComponentProvider
- * @description @qin-ui/antd-vue-pro 全局配置提供者组件
  * @public
  *
  * 用于在组件树的顶层配置所有子组件的全局默认属性。
@@ -28,15 +29,16 @@
  * </template>
  * ```
  */
-import { ComponentVars } from '../types';
 import {
+  INJECT_COMPONENT_VARS,
   INJECT_COMPONENTS,
   INJECT_CONFIG,
   ensureInjectConfig,
 } from '../constants';
+import type { ComponentVars } from '../types';
 import { computed, provide } from 'vue';
-import { getObject } from '../../../shared/core';
-import { ComponentName } from '../../form/constants';
+import { getObject, omit } from '../../../shared/core';
+import type { ComponentName } from '../../form/constants';
 import { LOCALE_INJECT_KEY, type ProLocale } from '../../../locale';
 
 type ComponentMap = Partial<Record<ComponentName, any>>;
@@ -48,19 +50,19 @@ defineOptions({
 
 type Props = {
   /**
-   * @description 组件全局配置
+   * 组件全局配置
    * 可配置所有内置组件和 Pro 组件的默认属性
    * @example { 'input': { placeholder: '请输入' }, 'pro-form': { grid: { gutter: 24 } } }
    */
   componentVars?: ComponentVars;
   /**
-   * @description 自定义组件映射
+   * 自定义组件映射
    * 用于替换或扩展内置组件，传入的组件会覆盖默认的同名组件
    * @example { 'input': MyCustomInput, 'select': MyCustomSelect }
    */
   componentMap?: ComponentMap;
   /**
-   * @description 内置文案覆盖
+   * 内置文案覆盖
    * 可覆盖任意 locale 文案（如查询/重置/序号/占位符等），
    * 未覆盖的文案默认跟随宿主组件库语言自动切换
    * @example { 'table.query': '搜索' }
@@ -76,18 +78,24 @@ const props = withDefaults(defineProps<Props>(), {
 
 /*
  * 遍历 componentVars 的每个 key，获取或创建对应的 inject 配置
- * 将用户提供的值合并到默认值上，通过 provide 响应式注入到子组件树
+ * 将用户提供的值合并到默认值上，剔除该注入项的不可注入键后通过 provide 响应式注入到子组件树
  * 子组件通过 inject(config.injectionKey) 获取合并后的计算属性配置
  */
 (Object.keys(INJECT_CONFIG) as Array<keyof typeof INJECT_CONFIG>).forEach(
   key => {
     const config = INJECT_CONFIG[key];
+    const ignored = config.ignoreProps;
     provide(
       config.injectionKey,
-      computed(() => ({
-        ...config.default,
-        ...getObject(props.componentVars?.[key as keyof ComponentVars]),
-      }))
+      computed(() =>
+        omit(
+          {
+            ...config.default,
+            ...getObject(props.componentVars?.[key as keyof ComponentVars]),
+          },
+          ignored ?? []
+        )
+      )
     );
   }
 );
@@ -108,6 +116,12 @@ if (props.componentVars) {
   });
 }
 
+// 全量 componentVars：自定义组件键在运行期新增后同样可被子组件读取
+provide(
+  INJECT_COMPONENT_VARS,
+  computed(() => (props.componentVars as Record<string, any>) ?? {})
+);
+
 // 注入自定义组件映射，BaseField 在解析组件时会优先使用此映射
 provide(
   INJECT_COMPONENTS,

package/src/components/component-provider/constants/index.ts

@@ -1,28 +1,40 @@
-import { RequiredComponentVars } from '../types';
-import { InjectionKey, Component, type ComputedRef } from 'vue';
+import type { RequiredComponentVars } from '../types';
+import type { InjectionKey, Component } from 'vue';
+import { type ComputedRef } from 'vue';
 
 const getPopupContainer = (triggerNode: any) =>
   triggerNode.closest?.("form[class*='-form']") ||
   (typeof document !== 'undefined' ? document.body : undefined);
 
+/** 自定义组件映射的注入 key：ProComponentProvider 注入，BaseField 解析组件时优先取用 */
 export const INJECT_COMPONENTS: InjectionKey<
   | ComputedRef<Partial<Record<string, Component>> | undefined>
   | Partial<Record<string, Component>>
 > = Symbol('INJECT_COMPONENTS');
 
+/** 全量 componentVars 注入通道：运行期新增的自定义组件键由此读取（按组件名取配置） */
+export const INJECT_COMPONENT_VARS: InjectionKey<
+  ComputedRef<Record<string, any> | undefined> | Record<string, any>
+> = Symbol('COMPONENT_VARS');
+
+/** 单个组件名的注入配置：注入 key、默认值与不接受 Provider 注入的键 */
 export type InjectConfigEntry<T = any> = {
   injectionKey: InjectionKey<T>;
   default: T;
+  /** 不接受 Provider 注入的键，注入层静默剔除 */
+  ignoreProps?: readonly string[];
 };
 
+/** 内置组件名的注入配置表：每个组件名对应一份默认值，Provider 注入值与之合并 */
 export const INJECT_CONFIG: {
-  [key in keyof RequiredComponentVars]: {
-    injectionKey: InjectionKey<RequiredComponentVars[key]>;
-    default: RequiredComponentVars[key];
-  };
+  [key in keyof RequiredComponentVars]: InjectConfigEntry<
+    RequiredComponentVars[key]
+  >;
 } = {
   'pro-table': {
     injectionKey: Symbol(''),
+    // 列 / 数据源取自组件绑定或 `:table` 实例，加载态由组件自身状态驱动
+    ignoreProps: ['loading', 'columns', 'dataSource'],
     default: {
       pagination: {
         showSizeChanger: true,
@@ -39,6 +51,8 @@ export const INJECT_CONFIG: {
   },
   'pro-form': {
     injectionKey: Symbol(''),
+    // 表单实例由 `:form` 显式传入
+    ignoreProps: ['form'],
     default: { grid: { gutter: { xs: 8, sm: 16, md: 16, lg: 24 } } },
   },
   'pro-form-item': {
@@ -142,9 +156,16 @@ export const INJECT_CONFIG: {
   },
 };
 
+/** 内置集合之外的组件名经此登记的注入通道，无原型链 */
 const DYNAMIC_INJECT_CONFIG: Record<string, InjectConfigEntry> =
   Object.create(null);
 
+/**
+ * 按组件名取注入配置
+ * @description 先查内置配置表，再查动态登记的通道
+ * @param key - 组件名（含 `date-picker.month` 等子类型段）
+ * @returns 对应注入配置，未登记时为 `undefined`
+ */
 export const getInjectConfig = (key: string): InjectConfigEntry | undefined => {
   return (
     (INJECT_CONFIG as Record<string, InjectConfigEntry>)[key] ||
@@ -152,6 +173,12 @@ export const getInjectConfig = (key: string): InjectConfigEntry | undefined => {
   );
 };
 
+/**
+ * 按组件名取注入配置，未登记时补建
+ * @description 补建的通道使用独立的 Symbol 注入 key 与空默认值，同一组件名重复调用返回同一配置
+ * @param key - 组件名
+ * @returns 已存在或新建的注入配置
+ */
 export const ensureInjectConfig = (key: string): InjectConfigEntry => {
   const existing = getInjectConfig(key);
   if (existing) return existing;

package/src/components/component-provider/types/index.ts

@@ -1,10 +1,14 @@
-import { GridItemProps, FormItemProps, TableProps } from '../../../shared/ui';
-import { Base, Grid } from '../../form/types';
-import { ProFormProps } from '../../form/components';
-import { ProTableProps } from '../../table';
-import { AllowedComponentProps } from 'vue';
+import type {
+  GridItemProps,
+  FormItemProps,
+  TableProps,
+} from '../../../shared/ui';
+import type { Base, Grid } from '../../form/types';
+import type { ProFormProps } from '../../form/components';
+import type { ProTableProps } from '../../table';
+import type { AllowedComponentProps } from 'vue';
 
-import { GetComponentType, ComponentName } from '../../form/constants';
+import type { GetComponentType, ComponentName } from '../../form/constants';
 import type { ComponentProps } from 'vue-component-type-helpers';
 
 type PP<T extends Record<string, any>> = Partial<T & AllowedComponentProps>;
@@ -16,7 +20,7 @@ type FP<T extends Record<string, any>> = Partial<
 >;
 
 /**
- * @qin-ui/antd-vue-pro 全局配置变量类型
+ * 全局配置变量类型
  *
  * @description 定义可通过 ProComponentProvider 配置的所有组件默认属性。
  * 支持配置表单、表格、表单项以及所有内置组件的默认属性。
@@ -40,9 +44,13 @@ type FP<T extends Record<string, any>> = Partial<
  * ```
  */
 export type RequiredComponentVars = {
-  /** ProTable 全局默认属性 */
+  /**
+   * ProTable 全局默认属性
+   *
+   * @description `columns` / `dataSource` / `loading` 不参与全局注入：三者分别由 `:table` 实例（`useTable`）与组件自身查询状态驱动。
+   */
   'pro-table': PP<
-    TableProps &
+    Omit<TableProps, 'loading' | 'columns' | 'dataSource'> &
       Pick<
         ProTableProps,
         | 'control'

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

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 /**
+ * 字段级渲染组件，负责将 field 配置渲染为实际的输入组件
+ *
  * @component BaseField
- * @description 字段级渲染组件，负责将 field 配置渲染为实际的输入组件
  *
  * ## 核心职责
  *
@@ -34,18 +35,23 @@ import {
   mergeProps,
   ref,
   toValue,
-  useAttrs,
 } from 'vue';
-import { cloneDeep } from '../../../../shared/core';
+import {
+  cloneDeep,
+  getObject,
+  useReactiveAttrs,
+} from '../../../../shared/core';
 import {
   useInjectDisabled,
   useInjectFormItemContext,
+  useProvideFormItemContext,
 } from '../../../../shared/ui';
 import type { Field } from '../../types';
 import ContainerFragment from '../ContainerFragment/index.vue';
 import SlotComponent from '../SlotComponent/index.vue';
 import { componentMap, InjectionFormSlotsKey } from '../../constants';
 import {
+  INJECT_COMPONENT_VARS,
   INJECT_COMPONENTS,
   getInjectConfig,
 } from '../../../component-provider/constants';
@@ -60,7 +66,9 @@ const cloneDeepIfObject = (val: unknown) =>
 defineOptions({ name: 'BaseField', inheritAttrs: false });
 
 type Props = {
+  /** 组件名或组件对象 */
   component?: string | Component;
+  /** 字段路径，用于绑定表单数据 */
   path?: string;
 };
 const props = withDefaults(defineProps<Props>(), {
@@ -74,12 +82,29 @@ const form = useForm(false);
 
 const componentRef = ref<any>();
 
+const emit = defineEmits<{
+  (e: 'field-value-change', value: unknown): void;
+}>();
+
+/*
+ * 派生 FormItem 校验上下文：保留父级 id、clearValidate 与 blur 通路，变更回调置空。
+ * 控件（含包装组件内部与插槽内的宿主控件）的值变更统一经字段事件回传一次，
+ * 不在宿主上下文内自报，避免同一字段同一 tick 触发两遍校验
+ */
 const formItemContext = useInjectFormItemContext();
-const triggerFormItemChange = () => {
-  formItemContext.onFieldChange();
+useProvideFormItemContext({
+  id: formItemContext.id,
+  onFieldBlur: formItemContext.onFieldBlur,
+  onFieldChange: () => {},
+  clearValidate: formItemContext.clearValidate,
+});
+
+// 值写入 formData 后向外广播，由 BaseFormItem 触发所属 FormItem 校验
+const triggerFormItemChange = (value: unknown) => {
+  emit('field-value-change', value);
 };
 
-const attrs: any = useAttrs();
+const attrs: any = useReactiveAttrs();
 
 /**
  * 全局默认配置注入：key = 组件名 + picker 修饰段，inject 须在 setup 同步期调用。
@@ -97,6 +122,8 @@ const componentInjectConfig = injectConfigKey
 const rawInjectComponentProps = componentInjectConfig
   ? inject(componentInjectConfig.injectionKey, componentInjectConfig.default)
   : undefined;
+// 全量 componentVars：运行期新增的自定义组件键由此兜底读取
+const componentVars = inject(INJECT_COMPONENT_VARS, undefined);
 
 // setter: 向 formData 写入值，支持 valueFormatter / valueFormatter.set 转换
 const value = computed({
@@ -123,7 +150,7 @@ const value = computed({
           : undefined;
 
     if (setFormatter) {
-      // 仅当 set 转换函数需要旧值参数时，才获取旧值上下文
+      // 旧值仅在 set 转换函数声明双形参时注入
       const oldVal =
         setFormatter.length > 1
           ? cloneDeepIfObject(form.getFormData?.(props.path))
@@ -131,7 +158,7 @@ const value = computed({
       newVal = setFormatter(val, oldVal);
     }
     form.setFormData?.(props.path, newVal);
-    triggerFormItemChange();
+    triggerFormItemChange(newVal);
     // 字段配置/attrs 传入的 onUpdate:* 监听器与内部写值组合回放，参数为组件原始 emit 值
     const { onUpdateValue } = groupedAttrs.value;
     if (typeof onUpdateValue === 'function') {
@@ -149,7 +176,10 @@ const parentDisabled = useInjectDisabled();
  * 属性分为三类：绑定属性（v-model）、组件属性（传递给组件）、插槽（动态渲染）
  */
 const groupedAttrs = computed(() => {
-  const currentInjectProps = toValue(rawInjectComponentProps) || {};
+  const currentInjectProps = {
+    ...(toValue(rawInjectComponentProps) || {}),
+    ...getObject(toValue(componentVars)?.[injectConfigKey]),
+  };
   const initProps = getInitProps(
     { component: props.component, picker: attrs.picker } as Field,
     currentInjectProps,
@@ -177,10 +207,8 @@ const groupedAttrs = computed(() => {
   };
 });
 
-// 从 ProForm 插槽注入的 slots 集合（优先级最高；shallowRef 形态，computed 内经 .value 读取建立依赖）
-const injectedFormSlots = inject(InjectionFormSlotsKey, undefined) as
-  | { value: Record<string, any> | undefined }
-  | undefined;
+// 从 ProForm 插槽注入的 slots 集合（优先级最高）
+const injectedFormSlots = inject(InjectionFormSlotsKey, undefined);
 
 // 从 ProComponentProvider 注入的自定义组件映射
 const customComponents = inject(INJECT_COMPONENTS, {});

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

@@ -1,4 +1,4 @@
-import { Field } from '../../../types';
+import type { Field } from '../../../types';
 
 type LocaleT = (
   key: string,
@@ -26,6 +26,17 @@ const getPlaceholderProps = (
   return { placeholder: t(placeholderKey) };
 };
 
+/**
+ * 解析字段的 Provider 默认属性
+ *
+ * @description 仅字符串组件名取注入值（含 `date-picker` 子类型段）；组件对象无注入配置，返回空对象。
+ * `date-picker` 不拼接 `picker` 段，其子类型预设由注入 key 在 BaseField 内单独解析
+ *
+ * @param field - 字段配置项
+ * @param injectProps - 该组件名对应的 Provider 注入默认值
+ * @param t - 翻译函数，用于兜底占位符文案
+ * @returns 合并占位符兜底后的初始属性
+ */
 export const getInitProps = (
   field: Field,
   injectProps: Record<string, any> = {},
@@ -43,6 +54,13 @@ export const getInitProps = (
 /** 已告警过的未知组件名（模块级去重集合） */
 const warnedUnknownComponents = new Set<string>();
 
+/**
+ * 输出未识别组件名的告警
+ *
+ * @description 按组件名去重，同一名称仅告警一次
+ *
+ * @param name - 未识别的组件名
+ */
 export function warnUnknownComponent(name: string) {
   if (warnedUnknownComponents.has(name)) return;
   warnedUnknownComponents.add(name);

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

@@ -1,7 +1,8 @@
 <script lang="ts" setup>
 /**
+ * 表单字段渲染引擎
+ *
  * @component BaseFormItem
- * @description 表单字段渲染引擎
  *
  * 负责将字段配置数组渲染为实际的表单项，支持：
  * - 字段分组（嵌套 fields 递归渲染）
@@ -13,22 +14,22 @@
  * ## 渲染流程
  *
  * 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';
@@ -39,27 +40,14 @@ import ContainerFragment from '../ContainerFragment/index.vue';
 import { useGroupFieldAttrs } from '../../hooks/useGroupFieldAttrs';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
 
-/*
- * 无 path 字段的稳定渲染 key：以字段原始对象为 key 分配自增 id，
- * 字段插删/重排/过滤时保持 key 与对象绑定，不随数组位置漂移
- */
-let fieldKeySeed = 0;
-const fieldKeyMap = new WeakMap<object, number>();
-const getFieldKey = (field: unknown): number => {
-  const raw = toRaw(field as object);
-  let key = fieldKeyMap.get(raw);
-  if (key === undefined) {
-    key = ++fieldKeySeed;
-    fieldKeyMap.set(raw, key);
-  }
-  return key;
-};
-
 defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
 
 type Props = {
+  /** 是否启用网格布局 */
   grid?: Grid;
+  /** 字段配置数组 */
   fields?: Fields;
+  /** 是否禁用所有子字段 */
   disabled?: boolean;
 };
 const props = withDefaults(defineProps<Props>(), {
@@ -69,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 消费
@@ -93,7 +83,7 @@ const computedGridProps = computed<GridProps>(() => {
 
 /**
  * 以字段原始对象为 key 登记 FormItem / 控件实例，供 getFormItemRef / getComponentRef 读取；
- * WeakMap 不参与响应式追踪，条目随字段对象回收自动释放。
+ * 字段对象被回收后对应条目不再可读。
  */
 const formItemInstanceMap = new WeakMap<object, any>();
 const componentInstanceMap = new WeakMap<object, any>();
@@ -106,7 +96,7 @@ const defineFieldAccessors = (
 ) => {
   try {
     for (const [key, getter] of Object.entries(accessors)) {
-      // 不可枚举：不进入 Object.keys / spread，不随字段配置透传
+      // 访问器仅用于字段对象读取，不参与属性遍历与字段配置透传
       Object.defineProperty(raw, key, {
         value: getter,
         enumerable: false,
@@ -124,6 +114,16 @@ const defineFieldAccessors = (
   }
 };
 
+/*
+ * 字段值变更经 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);
@@ -165,10 +165,7 @@ const groupedFields = useGroupFieldAttrs(validFields);
     :component="enableGrid ? AGrid : undefined"
     v-bind="computedGridProps"
   >
-    <template
-      v-for="item of groupedFields"
-      :key="item.path || getFieldKey(item.rawField)"
-    >
+    <template v-for="item of groupedFields" :key="item.renderKey">
       <ContainerFragment
         :component="enableGrid ? AGridItem : undefined"
         v-bind="item.gridItemProps"
@@ -206,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;
 };