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

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

@@ -1,6 +1,5 @@
 /**
- * 统一 re-export @qin-ui/pro-components-core，包内所有文件通过此文件引入 core 内容，
- * 避免直接散列依赖 @qin-ui/pro-components-core，便于将来统一维护。
+ * 统一 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';
 //# 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;;;GAGG;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,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/antd-vue-pro",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "description": "二次封装antd vue组件",
   "bin": {
     "antd-vue-pro": "./bin/init-ai.mjs"
@@ -23,7 +23,8 @@
     "README.md",
     "LICENSE",
     "api.json",
-    "AI-CONTEXT.md"
+    "AI-CONTEXT.md",
+    "tsconfig.json"
   ],
   "homepage": "https://dufan3715.github.io/pro-components/",
   "repository": {
@@ -43,11 +44,11 @@
   "dependencies": {
     "scroll-into-view-if-needed": "^3.1.0",
     "vue-component-type-helpers": "^3.2.5",
-    "@qin-ui/pro-components-core": "^2.0.2"
+    "@qin-ui/pro-components-core": "^2.0.4"
   },
   "devDependencies": {
     "@vue/test-utils": "^2.4.11",
-    "ant-design-vue": "^4",
+    "ant-design-vue": "^4.2.6",
     "happy-dom": "^20.11.6",
     "vitest": "^4.1.11"
   },

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

@@ -1,6 +1,6 @@
 import { GridItemProps, FormItemProps, TableProps } from '../../../shared/ui';
 import { Base, Grid } from '../../form/types';
-import { ProFormProps } from '../../form';
+import { ProFormProps } from '../../form/components';
 import { ProTableProps } from '../../table';
 import { AllowedComponentProps } from 'vue';
 

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

@@ -42,7 +42,8 @@ import {
   useInjectFormItemContext,
 } from '../../../../shared/ui';
 import type { Field } from '../../types';
-import { ContainerFragment, SlotComponent } from '..';
+import ContainerFragment from '../ContainerFragment/index.vue';
+import SlotComponent from '../SlotComponent/index.vue';
 import { componentMap, InjectionFormSlotsKey } from '../../constants';
 import {
   INJECT_COMPONENTS,
@@ -52,6 +53,10 @@ import { useForm } from '../../hooks/useForm';
 import { getInitProps, warnUnknownComponent } from './utils';
 import { useLocale } from '../../../../locale';
 
+const cloneDeepIfObject = (val: unknown) =>
+  // 原始值直接传递，引用值克隆快照
+  typeof val === 'object' && val !== null ? cloneDeep(val) : val;
+
 defineOptions({ name: 'BaseField', inheritAttrs: false });
 
 type Props = {
@@ -76,7 +81,11 @@ const triggerFormItemChange = () => {
 
 const attrs: any = useAttrs();
 
-// 全局默认配置注入：key = 组件名 + picker 修饰段；inject 须在 setup 同步期调用
+/**
+ * 全局默认配置注入：key = 组件名 + picker 修饰段，inject 须在 setup 同步期调用。
+ * 组件名与 `picker` 仅取 setup 期初始值——运行期变更不会切换 Provider 的默认值预设
+ * （`date-picker.month` 等子类型预设需在初始渲染前确定）。
+ */
 const pickerVal = attrs.picker;
 const injectConfigKey =
   typeof props.component === 'string'
@@ -117,12 +126,19 @@ const value = computed({
       // 仅当 set 转换函数需要旧值参数时，才获取旧值上下文
       const oldVal =
         setFormatter.length > 1
-          ? cloneDeep(form.getFormData?.(props.path))
+          ? cloneDeepIfObject(form.getFormData?.(props.path))
           : undefined;
       newVal = setFormatter(val, oldVal);
     }
     form.setFormData?.(props.path, newVal);
     triggerFormItemChange();
+    // 字段配置/attrs 传入的 onUpdate:* 监听器与内部写值组合回放，参数为组件原始 emit 值
+    const { onUpdateValue } = groupedAttrs.value;
+    if (typeof onUpdateValue === 'function') {
+      onUpdateValue(val);
+    } else if (Array.isArray(onUpdateValue)) {
+      onUpdateValue.forEach(listener => listener(val));
+    }
   },
 });
 
@@ -149,8 +165,7 @@ const groupedAttrs = computed(() => {
   ) as Required<Field>;
 
   // prettier-ignore
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, [effectiveModelProp]: _modelVal, [`onUpdate:${effectiveModelProp}`]: _onUpdateModelVal, ...bindAttrs } = mergedProps as any;
+  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, [effectiveModelProp]: _modelVal, [`onUpdate:${effectiveModelProp}`]: onUpdateValue, ...bindAttrs } = mergedProps as any;
 
   return {
     attrs: bindAttrs,
@@ -158,12 +173,13 @@ const groupedAttrs = computed(() => {
     componentContainer,
     modelProp,
     valueFormatter,
+    onUpdateValue,
   };
 });
 
-// 从 ProForm 插槽注入的 slots 集合（优先级最高）
-const formSlots = inject(InjectionFormSlotsKey, undefined) as
-  | Record<string, any>
+// 从 ProForm 插槽注入的 slots 集合（优先级最高；shallowRef 形态，computed 内经 .value 读取建立依赖）
+const injectedFormSlots = inject(InjectionFormSlotsKey, undefined) as
+  | { value: Record<string, any> | undefined }
   | undefined;
 
 // 从 ProComponentProvider 注入的自定义组件映射
@@ -174,7 +190,7 @@ const customComponents = inject(INJECT_COMPONENTS, {});
  * ProForm 插槽 → 自定义组件映射 → 内置组件映射 → 原始 component 值
  */
 const is = computed(() => {
-  const teleportSlot = props.path && formSlots?.[props.path];
+  const teleportSlot = props.path && injectedFormSlots?.value?.[props.path];
   if (teleportSlot) return teleportSlot;
   if (typeof props.component === 'string') {
     const resolved =

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

@@ -40,7 +40,7 @@ export const getInitProps = (
   return {};
 };
 
-/** 已告警过的未知组件名（模块级去重，避免 computed 重算导致刷屏） */
+/** 已告警过的未知组件名（模块级去重集合） */
 const warnedUnknownComponents = new Set<string>();
 
 export function warnUnknownComponent(name: string) {

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

@@ -33,10 +33,28 @@ import {
 } 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';
 
+/*
+ * 无 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 = {
@@ -55,6 +73,7 @@ const validFields = computed(() =>
   (props.fields ?? []).filter(field => !toValue(field.hidden))
 );
 
+// 向下注入表单级禁用上下文，BaseField 经 useInjectDisabled 消费
 useProviderDisabled(computed(() => props.disabled));
 
 const config = INJECT_CONFIG['pro-form'];
@@ -79,15 +98,45 @@ const computedGridProps = computed<GridProps>(() => {
 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.keys / spread，不随字段配置透传
+      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, 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;
+    delete raw.getFormItemComputedProps;
   }
 };
 
@@ -96,12 +145,15 @@ 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;
+    delete raw.getComponentComputedProps;
   }
 };
 
@@ -113,7 +165,10 @@ 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.path || getFieldKey(item.rawField)"
+    >
       <ContainerFragment
         :component="enableGrid ? AGridItem : undefined"
         v-bind="item.gridItemProps"

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

@@ -9,8 +9,8 @@
  *
  * 1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）
  *    均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。
- * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件，避免了深层嵌套的 Props 传递。
- * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成，实现了 UI 布局与表单逻辑的解耦。
+ * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件。
+ * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成。
  *
  * @public
  *
@@ -47,13 +47,16 @@ import {
   computed,
   inject,
   mergeProps,
+  onUpdated,
   provide,
+  shallowRef,
   toValue,
+  triggerRef,
   useAttrs,
   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 {
@@ -75,12 +78,12 @@ const props = withDefaults(defineProps<Props>(), {
 
 /**
  * 依赖注入中心：
- * 若外部未传 form 实例，则自动初始化内部表单实例；
+ * 未传 form 实例（含运行期置空）时惰性初始化内部表单实例；
  * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
  */
-const fallbackForm = props.form ? undefined : useForm();
+let fallbackForm: F | undefined;
 const currentForm = computed(
-  () => props.form ?? (fallbackForm as unknown as F)
+  () => props.form ?? (fallbackForm ??= useForm() as unknown as F)
 );
 
 /**
@@ -98,9 +101,14 @@ const fields = computed(() => {
 const formData = computed(() => currentForm.value?.formData);
 const setFormRef = (el: any) => currentForm.value?.setFormRef?.(el);
 
+/*
+ * formKey 子树重挂载契约：以 WeakMap 为每个 form 实例生成自增 key，绑定到原生 Form 的 :key
+ * :form 运行期替换为全新实例时强制整棵表单子树重新挂载，重置宿主校验状态与深层字段非受控状态
+ */
 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);
   }
@@ -118,7 +126,6 @@ const attrs = useAttrs();
  */
 const injectAttrs = computed(() => {
   const raw = toValue(injectFormConfig);
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const { grid: _injectGrid, ...rest } = raw || {};
   return rest;
 });
@@ -134,11 +141,15 @@ type FieldSlots = Record<ExtractPath<F>, Slot<FieldSlotProps>>;
 
 const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
 
-/**
+/*
  * 动态插槽映射中心 (Slot Teleporting)：
- * 在 setup 同步期直接提供响应式 slots 上下文容器，供深层 BaseField 按需动态获取插槽
+ * slots 以 shallowRef 注入，组件每次更新后触发通知，深层 BaseField 可感知父级运行期增删的具名插槽
  */
-provide(InjectionFormSlotsKey, slots);
+const formSlotsRef = shallowRef<Record<string, any>>(slots);
+onUpdated(() => {
+  triggerRef(formSlotsRef);
+});
+provide(InjectionFormSlotsKey, formSlotsRef);
 </script>
 
 <template>

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

@@ -17,6 +17,7 @@ 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 {
   path: string;
@@ -33,7 +34,7 @@ export interface GroupedField {
  *
  * @description
  * 1. 响应式集成 ProComponentProvider 的 `pro-form-item` 全局变量配置；
- * 2. 剥离 `extraProps`（用户自定义字段标识袋）：保留在字段原始对象上供业务层存取，渲染层经解构剥离，避免落入 componentProps 透传为无效 DOM 属性。
+ * 2. 剥离 `extraProps`（用户自定义字段标识袋）：保留在字段原始对象上供业务层存取，渲染层经解构剥离，不落入 componentProps 透传。
  */
 export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
   const config = INJECT_CONFIG['pro-form-item'];
@@ -49,23 +50,11 @@ 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 } =
           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 优先，否则回退注入配置的响应式断点
         const initGridItemProps =
@@ -73,7 +62,10 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
             ? { span }
             : { xs, sm, md, lg, xl, xxl, span: injectSpan };
 
-        gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+        // 分组字段默认整行（span 兜底 24），注入断点同样生效
+        gridItemProps = fields
+          ? { ...initGridItemProps, span: span ?? 24 }
+          : initGridItemProps;
         // 字段级容器优先，回退注入级配置
         const container = formItemContainer ?? injectFormItemContainer;
         formItemProps = mergeProps(
@@ -95,7 +87,7 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
         Object.assign(componentProps, componentDataAttrs);
         Object.keys(slots).forEach(k => {
-          if (FORM_ITEM_SLOT_KEYS.includes(k as any)) {
+          if (formItemSlotKeySet.has(k)) {
             formItemSlots[k] = slots[k];
           } else {
             componentProps.slots[k] = slots[k];

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

@@ -267,10 +267,7 @@ type WithFields<D extends Data = Data> = WithRef<
 /**
  * @description 合并 FormItem 插槽与组件插槽
  */
-export type MergeSlots<
-  T extends abstract new (...args: any) => any,
-  CS = ComponentSlots<T>,
-> = Partial<{
+export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
   [K in keyof FormItemSlots | keyof CS]: K extends keyof FormItemSlots
     ? FormItemSlots[K]
     : K extends keyof CS
@@ -283,10 +280,7 @@ export type MergeSlots<
  * @template T - Vue 组件类型
  * @template D - 数据对象类型
  */
-type WithComponent<
-  T extends abstract new (...args: any) => any,
-  D extends Data = Data,
-> = Omit<
+type WithComponent<T, D extends Data = Data> = Omit<
   WithCommon<Partial<ComponentProps<T>>, D>,
   keyof VNodeProps | 'slots'
 > & {

package/src/components/table/components/ColumnControl.vue

@@ -55,7 +55,7 @@ const checkedColumnsOptions = computed<
     const disabled =
       props.columnControl?.disabledKeys?.some(dk => String(dk) === key) ??
       false;
-    // labels 优先；title 为字符串时直接使用；vnode 等其他类型降级为 key，避免渲染异常
+    // labels 优先；title 为字符串时直接使用；vnode 等其他类型降级为 key
     const label =
       (props.columnControl?.labels?.[key] as string) ??
       (typeof item.title === 'string' ? item.title : key);
@@ -80,10 +80,12 @@ const checkedColumnKeys = computed({
     );
   },
   set(val) {
+    // 仅写 hidden 发生翻转的列
+    const checkedSet = new Set(val);
     checkedColumnsOptions.value.forEach(item => {
-      if (item.disabled) return;
+      if (item.disabled || item.checked === checkedSet.has(item.value)) return;
       props.table?.setColumn?.(item.value, {
-        hidden: !val.includes(item.value),
+        hidden: !checkedSet.has(item.value),
       });
     });
   },

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

@@ -49,7 +49,7 @@ import {
   type Slot,
 } from 'vue';
 import { INJECT_CONFIG } from '../../component-provider/constants';
-import { ContainerFragment } from '../../form';
+import ContainerFragment from '../../form/components/ContainerFragment/index.vue';
 import type { ContainerComponent } from '../../form/types';
 import SearchForm from './SearchForm.vue';
 import { SearchFormProps } from './SearchForm.vue';
@@ -64,12 +64,10 @@ import {
   Path,
 } from '../../../shared/core';
 import { ComponentSlots } from 'vue-component-type-helpers';
-import {
-  DefaultSearchFormContainer,
-  DefaultTableContainer,
-  SizeControl,
-  ColumnControl,
-} from '.';
+import DefaultSearchFormContainer from './DefaultSearchFormContainer.vue';
+import DefaultTableContainer from './DefaultTableContainer.vue';
+import SizeControl from './SizeControl.vue';
+import ColumnControl from './ColumnControl.vue';
 import { Column, Columns, ColumnControlConfig } from '../types';
 
 defineOptions({ name: 'ProTable', inheritAttrs: false });
@@ -147,10 +145,26 @@ const loading = defineModel<boolean>('loading', { default: false });
 
 // 递增序号做请求竞态守卫，仅最新一次请求可变更 loading
 let searchSequence = 0;
+let warnedSearchConfig = false;
+const warnSearchConfig = (reason: string) => {
+  if (warnedSearchConfig) return;
+  warnedSearchConfig = true;
+  console.warn(`[ProTable] ${reason}`);
+};
 const _search = async () => {
-  const seq = ++searchSequence;
+  if (props.search && attrs.onSearch) {
+    warnSearchConfig(
+      '同时配置了 :search prop 与 @search 监听，@search 监听不会被执行，请仅保留其一。'
+    );
+  }
   const searchPromise = (props.search || attrs.onSearch)?.();
-  if (!isPromise(searchPromise)) return;
+  if (!isPromise(searchPromise)) {
+    warnSearchConfig(
+      'search 未返回 Promise，本次查询不参与 loading 竞态管理（在途请求的 loading 状态保持不变）。'
+    );
+    return;
+  }
+  const seq = ++searchSequence;
   loading.value = true;
   try {
     await searchPromise;
@@ -206,7 +220,7 @@ const columnRequiredSlotNames = new Set([
 /**
  * 判定插槽是否具备渲染条件（守卫过渡状态或空列下 column 为 undefined 的情况）
  * 当列被动态隐藏或所有列均隐藏时，旧单元格销毁过渡帧或空占位中 column 可能为 undefined，
- * 此时直接阻断依赖 column 的业务插槽调用，防止访问 column 属性抛出 TypeError；
+ * 此时阻断依赖 column 的业务插槽调用；
  * 非列依赖的表格级插槽（如 emptyText、footer、summary 等）始终正常渲染。
  */
 const isSlotRenderable = (name: string, scoped: any) => {
@@ -306,7 +320,8 @@ const computedPagination = computed<PaginationProps | false>(() => {
 
 const onTableChange: TableProps['onChange'] = (...args) => {
   props.table?.setPageParam?.(args[0]);
-  attrs.onChange?.(...args);
+  // change 回放：模板监听器优先，未绑定时回退 Provider 全局配置
+  (attrs.onChange ?? injectProps.value.onChange)?.(...args);
   _search();
 };
 

package/src/components/table/components/SearchForm.vue

@@ -46,7 +46,7 @@ export type SearchFormProps = {
  *
  * 1. 内部渲染 ProForm，使用 table.searchForm 管理搜索条件
  * 2. 支持 grid（网格）和 inline（行内）两种布局
- * 3. 网格布局下支持展开/折叠：通过 IntersectionObserver 自动检测哪些字段溢出
+ * 3. 网格布局下支持展开/折叠（溢出检测与初值自动展开见下方机制说明）
  * 4. 提供搜索、重置、展开/折叠按钮（支持自定义）
  *
  * ## 展开/折叠机制
@@ -63,8 +63,8 @@ import {
   type Component,
   type DefineComponent,
 } from 'vue';
-import ProForm from '../../form';
-import { type Form } from '../../form';
+import ProForm from '../../form/components/ProForm/index.vue';
+import { type Form } from '../../form/hooks/useForm';
 import DownOutlined from './icons/DownOutlined.vue';
 import { useLocale } from '../../../locale';
 import { useSearchFormExpand } from '../../../shared/core';

package/src/components/table/hooks/useTable.ts

@@ -29,7 +29,7 @@ import { Fields } from '../../form/types';
  * @property appendColumn - 在指定列后追加新列，传 undefined 在末尾追加
  * @property prependColumn - 在指定列前插入新列，传 undefined 在开头插入
  * @property setPageParam - 设置分页参数，支持部分更新和函数式更新
- * @property resetQueryParams - 重置分页到第一页并恢复搜索条件到初始值
+ * @property resetQueryParams - 恢复分页与搜索条件到初始化时的快照（含自定义分页键，非固定回到第一页）
  *
  * @example
  * ```ts

package/src/shared/core/index.ts

@@ -1,6 +1,5 @@
 /**
- * 统一 re-export @qin-ui/pro-components-core，包内所有文件通过此文件引入 core 内容，
- * 避免直接散列依赖 @qin-ui/pro-components-core，便于将来统一维护。
+ * 统一 re-export @qin-ui/pro-components-core，包内所有文件通过此文件引入 core 内容。
  */
 export {
   // hooks

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["ESNext", "ES2022", "DOM"],
+    "baseUrl": ".",
+    "types": ["ant-design-vue/typings/global"],
+    "declaration": true,
+    "declarationMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true
+  },
+  "include": ["src", "__tests__"],
+  "exclude": ["node_modules", "es"]
+}