@qin-ui/antd-vue-pro 2.5.2 → 2.6.0

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

@@ -6,12 +6,12 @@
  *
  * 架构设计说明 (Architecture Overview)
  *
- * [ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]
+ * [ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItems / BaseFormItem / BaseField) ]
  *
  * 1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）
  *    均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。
  * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件。
- * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成。
+ * 3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItems>` 递归完成。
  *
  * @public
  *
@@ -57,7 +57,7 @@ import {
   type Slot,
 } from 'vue';
 import { INJECT_CONFIG } from '../../../component-provider/constants';
-import BaseFormItem from '../BaseFormItem/index.vue';
+import BaseFormItems from '../BaseFormItems/index.vue';
 import { InjectionFormKey, InjectionFormSlotsKey } from '../../constants';
 import type { Grid, VModelProps, PathProps } from '../../types';
 import type { Path } from '../../../../shared/core';
@@ -82,7 +82,7 @@ const props = withDefaults(defineProps<Props>(), {
 /**
  * 依赖注入中心：
  * 未传 form 实例（含运行期置空）时回退内部表单实例；
- * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
+ * 将 Form 实例注入到 Vue Context 中，供深层子组件（如 BaseFormItems, BaseField, 自定义插槽）跨层级直接访问数据和方法。
  */
 // 兜底表单实例：setup 同步期创建，未传 :form（含运行期置空）时经 currentForm 生效
 const fallbackForm = useForm() as unknown as F;
@@ -165,7 +165,7 @@ provide(InjectionFormSlotsKey, formSlotsRef);
     v-bind="formAttrs"
     class="pro-form"
   >
-    <BaseFormItem :fields="fields" :grid="props.grid" />
+    <BaseFormItems :fields="fields" :grid="props.grid" />
     <slot />
   </AForm>
 </template>

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

@@ -3,12 +3,12 @@ import type {
   ComponentExposed,
 } from 'vue-component-type-helpers';
 import ProForm from './ProForm/index.vue';
-import BaseFormItem from './BaseFormItem/index.vue';
+import BaseFormItems from './BaseFormItems/index.vue';
 
 export { default as BaseField } from './BaseField/index.vue';
 export { default as ContainerFragment } from './ContainerFragment/index.vue';
 export { default as SlotComponent } from './SlotComponent/index.vue';
-export { ProForm, BaseFormItem };
+export { ProForm, BaseFormItems };
 
 // instance
 /** ProForm 的组件实例类型，用于 `ref` 标注与 `defineExpose` 访问 */
@@ -16,7 +16,7 @@ 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>;
+/** BaseFormItems 的组件实例类型 */
+export type ProFormItemsInstance = ComponentExposed<typeof BaseFormItems>;
+/** BaseFormItems 的组件属性类型 */
+export type ProFormItemsProps = ComponentProps<typeof BaseFormItems>;

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

@@ -1,5 +1,11 @@
-import { computed, inject, mergeProps, toValue, type ComputedRef } from 'vue';
-import { getFieldKey } from '../utils/fieldKey';
+import {
+  computed,
+  inject,
+  mergeProps,
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from 'vue';
 import {
   formItemProps,
   gridItemProps,
@@ -35,16 +41,102 @@ export interface GroupedField {
   formItemContainer?: Base['formItemContainer'];
   /** 字段原始对象，供实例登记与访问器挂载使用 */
   rawField: Field;
-  /** 渲染 key，取自字段对象身份 */
-  renderKey: string | number;
 }
 
+/** 将单个字段配置拆分为 grid / formItem / component / slots 分组 */
+const groupField = (
+  field: Field,
+  rawInject: Record<string, any>
+): GroupedField => {
+  let gridItemProps: Record<string, any> = {};
+  let formItemProps: Record<string, any> = {};
+  const componentProps: Record<string, any> = { slots: {} };
+  const formItemSlots: Record<string, any> = {};
+
+  if (isPlainObject(field)) {
+    // prettier-ignore
+    const { path: _path, 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 时使用注入的断点配置
+     */
+    const initGridItemProps =
+      span || span === 0
+        ? { span }
+        : { xs, sm, md, lg, xl, xxl, span: injectSpan };
+
+    // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
+    gridItemProps = fields
+      ? { ...initGridItemProps, span: span ?? 24 }
+      : initGridItemProps;
+    // 字段级容器优先，回退注入级配置
+    const container = formItemContainer ?? injectFormItemContainer;
+    formItemProps = mergeProps(
+      injectRest,
+      { class: injectClassName, style: injectStyle },
+      { class: toValue(formItemClass), style: toValue(formItemStyle) },
+      formItemDataAttrs
+    );
+
+    Object.keys(rest).forEach(k => {
+      if (gridItemPropKeySet.has(k)) {
+        gridItemProps[k] = rest[k];
+      } else if (formItemPropKeySet.has(k)) {
+        formItemProps[k] = rest[k];
+      } else {
+        componentProps[k] = rest[k];
+      }
+    });
+
+    Object.assign(componentProps, componentDataAttrs);
+    Object.keys(slots).forEach(k => {
+      if (formItemSlotKeySet.has(k)) {
+        formItemSlots[k] = slots[k];
+      } else {
+        componentProps.slots[k] = slots[k];
+      }
+    });
+
+    // label 插槽与字段 label 同时存在时由插槽渲染，剥离 label 属性
+    if (formItemSlots.label && formItemProps.label !== undefined) {
+      delete formItemProps.label;
+    }
+
+    return {
+      path: resolveFieldIdentity(field),
+      gridItemProps: gridItemProps as GridItemProps,
+      formItemProps: formItemProps as any,
+      formItemSlots,
+      componentProps,
+      formItemContainer: container,
+      rawField: field,
+    };
+  }
+
+  return {
+    path: resolveFieldIdentity(field),
+    gridItemProps: gridItemProps as GridItemProps,
+    formItemProps: formItemProps as any,
+    formItemSlots,
+    componentProps,
+    rawField: field,
+  };
+};
+
 /**
  * 将 fields 配置数组逐个拆分为 grid / formItem / component / slots 分组。
  *
  * @description
  * 1. 响应式集成 ProComponentProvider 的 `pro-form-item` 全局变量配置；
  * 2. 剥离 `extraProps`（用户自定义字段标识袋）：保留在字段原始对象上供业务层存取，渲染层经解构剥离，不落入 componentProps 透传。
+ *
+ * @param {ComputedRef<Field[]>} validFields - 已过滤隐藏字段的字段配置数组
+ * @returns 字段渲染分组数组
  */
 export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
   const config = INJECT_CONFIG['pro-form-item'];
@@ -52,89 +144,23 @@ export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
 
   return computed<GroupedField[]>(() => {
     const rawInject = toValue(injectFormItemProps) || {};
-    return validFields.value.map(field => {
-      let gridItemProps: Record<string, any> = {};
-      let formItemProps: Record<string, any> = {};
-      const componentProps: Record<string, any> = { slots: {} };
-      const formItemSlots: Record<string, any> = {};
-
-      if (isPlainObject(field)) {
-        // prettier-ignore
-        const { path: _path, 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 时使用注入的断点配置
-         */
-        const initGridItemProps =
-          span || span === 0
-            ? { span }
-            : { xs, sm, md, lg, xl, xxl, span: injectSpan };
-
-        // 分组字段未指定 span 时整行渲染（span 兜底 24），注入的响应式断点保持生效
-        gridItemProps = fields
-          ? { ...initGridItemProps, span: span ?? 24 }
-          : initGridItemProps;
-        // 字段级容器优先，回退注入级配置
-        const container = formItemContainer ?? injectFormItemContainer;
-        formItemProps = mergeProps(
-          injectRest,
-          { class: injectClassName, style: injectStyle },
-          { class: toValue(formItemClass), style: toValue(formItemStyle) },
-          formItemDataAttrs
-        );
-
-        Object.keys(rest).forEach(k => {
-          if (gridItemPropKeySet.has(k)) {
-            gridItemProps[k] = rest[k];
-          } else if (formItemPropKeySet.has(k)) {
-            formItemProps[k] = rest[k];
-          } else {
-            componentProps[k] = rest[k];
-          }
-        });
-
-        Object.assign(componentProps, componentDataAttrs);
-        Object.keys(slots).forEach(k => {
-          if (formItemSlotKeySet.has(k)) {
-            formItemSlots[k] = slots[k];
-          } else {
-            componentProps.slots[k] = slots[k];
-          }
-        });
-
-        // label 插槽与字段 label 同时存在时由插槽渲染，剥离 label 属性
-        if (formItemSlots.label && formItemProps.label !== undefined) {
-          delete formItemProps.label;
-        }
-
-        const raw = resolveFieldIdentity(field);
-        return {
-          path: raw,
-          gridItemProps: gridItemProps as GridItemProps,
-          formItemProps: formItemProps as any,
-          formItemSlots,
-          componentProps,
-          formItemContainer: container,
-          rawField: field,
-          renderKey: getFieldKey(field),
-        };
-      }
-
-      const raw = resolveFieldIdentity(field);
-      return {
-        path: raw,
-        gridItemProps: gridItemProps as GridItemProps,
-        formItemProps: formItemProps as any,
-        formItemSlots,
-        componentProps,
-        rawField: field,
-        renderKey: getFieldKey(field),
-      };
-    });
+    return validFields.value.map(field => groupField(field, rawInject));
   });
 }
+
+/**
+ * 将单个字段配置拆分为 grid / formItem / component / slots 分组
+ *
+ * @description 拆分规则与 `useGroupFieldAttrs` 一致，结果依赖该字段自身配置与 Provider 的 `pro-form-item` 默认值。
+ *
+ * @param {MaybeRefOrGetter<Field>} field - 待拆分的字段配置
+ * @returns {ComputedRef<GroupedField>} 单字段渲染分组
+ */
+export function useGroupedField(field: MaybeRefOrGetter<Field>) {
+  const config = INJECT_CONFIG['pro-form-item'];
+  const injectFormItemProps = inject(config.injectionKey, config.default);
+
+  return computed<GroupedField>(() =>
+    groupField(toValue(field), toValue(injectFormItemProps) || {})
+  );
+}

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

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

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

@@ -46,6 +46,7 @@
  * @param {boolean | Partial<Control>} [control] - 是否展示尺寸与列控制按钮；显式传入 columns 时列控入口不渲染
  * @param {SearchFormConfig} [searchFormConfig] - 搜索栏查询字段表单配置
  * @param {ContainerComponent | false} [tableContainer] - 表格区域包裹容器
+ * @param {boolean | EllipsisTooltipConfig} [ellipsisTooltip] - truthy 时全局启用所有列；对象同时作为 Tooltip 配置；列上 `showTooltip: false` 或 `ellipsis: false` 可退出
  *
  * @slot search-form - 搜索区域插槽，作用域参数 form / search / reset
  * @slot button-bar - 表格头部按钮区插槽
@@ -65,7 +66,9 @@ import {
   nextTick,
   onMounted,
   inject,
+  ref,
   toValue,
+  watch,
   type Slot,
 } from 'vue';
 import { INJECT_CONFIG } from '../../component-provider/constants';
@@ -91,7 +94,15 @@ import DefaultSearchFormContainer from './DefaultSearchFormContainer.vue';
 import DefaultTableContainer from './DefaultTableContainer.vue';
 import SizeControl from './SizeControl.vue';
 import ColumnControl from './ColumnControl.vue';
-import type { Column, Columns, ColumnControlConfig } from '../types';
+import TableEllipsisTooltip from './TableEllipsisTooltip.vue';
+import { useEllipsisTooltip } from '../hooks/useEllipsisTooltip';
+import { useEllipsisTooltipColumns } from '../hooks/useEllipsisTooltipColumns';
+import type {
+  Column,
+  Columns,
+  ColumnControlConfig,
+  EllipsisTooltipConfig,
+} from '../types';
 
 defineOptions({ name: 'ProTable', inheritAttrs: false });
 
@@ -124,6 +135,8 @@ type Props = {
   searchFormConfig?: SearchFormConfig;
   /** 表格区域包裹容器 */
   tableContainer?: ContainerComponent | false;
+  /** 表格级省略 Tooltip 配置；truthy 时全局启用 */
+  ellipsisTooltip?: boolean | EllipsisTooltipConfig;
 } & /* @vue-ignore */ TableProps;
 
 const props = withDefaults(defineProps<Props>(), {
@@ -134,6 +147,7 @@ const props = withDefaults(defineProps<Props>(), {
   control: undefined,
   searchFormConfig: undefined,
   tableContainer: undefined,
+  ellipsisTooltip: undefined,
 });
 
 const { t } = useLocale();
@@ -171,6 +185,8 @@ const searchFormProps = computed(() => {
 
 const attrs: Record<string, any> = useReactiveAttrs();
 
+const rootRef = ref<HTMLElement | null>(null);
+
 const size = defineModel<TableProps['size']>('size');
 const loading = defineModel<boolean>('loading', { default: false });
 
@@ -318,25 +334,6 @@ const effectiveSize = computed<TableProps['size']>(() => {
   return size.value ?? injectAttrs.value.size;
 });
 
-/*
- * 下发给宿主表格的属性：Provider 注入为底（其不可注入键已在注入层剔除），调用方绑定与 v-model 透传值覆盖同键。
- * size / loading 为声明模型，其 onUpdate:* 回写通道不进入 attrs，无需另行剔除
- */
-const computedTableProps = computed<TableProps>(() => {
-  const merged = {
-    ...injectAttrs.value,
-    ...omitBy(
-      pick(camelAttrs.value, tableProperties),
-      value => value === undefined
-    ),
-  } as Record<string, any>;
-  // onChange 由模板监听器收口，散落 attrs 中的同名监听器并入会形成重复回调
-  delete merged.onChange;
-  merged.size = effectiveSize.value;
-  merged.loading = undefined;
-  return merged as TableProps;
-});
-
 const computedTableContainer = computed(() => {
   const container =
     props.tableContainer ??
@@ -378,45 +375,93 @@ const computedColumns = computed<Columns<RecordType>>(() => {
   return needIndex ? [indexColumn.value, ...cols] : cols;
 });
 
+const ellipsisTooltipValue = computed(
+  () => props.ellipsisTooltip ?? injectProps.value.ellipsisTooltip
+);
+const ellipsisTooltipConfig = computed<EllipsisTooltipConfig>(() =>
+  typeof ellipsisTooltipValue.value === 'object' && ellipsisTooltipValue.value
+    ? ellipsisTooltipValue.value
+    : {}
+);
+const ellipsisTooltipGlobal = computed(() =>
+  Boolean(ellipsisTooltipValue.value)
+);
+
+const {
+  columns: visibleComputedColumns,
+  hasTooltip: ellipsisTooltipEnabled,
+  resolveOriginalColumn,
+  resolveSorterColumn,
+} = useEllipsisTooltipColumns(
+  () => computedColumns.value,
+  () => ellipsisTooltipGlobal.value
+);
+
 /*
- * 递归过滤 hidden 列（含分组子列）：仅对被过滤过子列的列生成浅拷贝，
- * 未发生变动的列保持原对象引用（每次 columns 变化执行一次，不在渲染期递归）
+ * 下发给宿主表格的属性：Provider 注入为底（其不可注入键已在注入层剔除），调用方绑定与 v-model 透传值覆盖同键。
+ * size / loading 为声明模型，其 onUpdate:* 回写通道不进入 attrs，无需另行剔除
  */
-const filterVisibleColumns = (
-  columns: any[],
-  ancestors: Set<object> = new Set()
-): { list: any[]; changed: boolean } => {
-  const list: any[] = [];
-  let changed = false;
-  for (const column of columns) {
-    if (!isObjectItem(column) || toValue((column as Column).hidden)) {
-      changed = true;
-      continue;
-    }
-    if (Array.isArray(column.children) && column.children.length > 0) {
-      // 环状分组列不再深入，重复出现的祖先引用直接剔除
-      if (ancestors.has(column)) {
-        changed = true;
-        continue;
-      }
-      ancestors.add(column);
-      const filtered = filterVisibleColumns(column.children, ancestors);
-      ancestors.delete(column);
-      if (filtered.changed) {
-        changed = true;
-        list.push({ ...column, children: filtered.list });
-        continue;
-      }
-    }
-    list.push(column);
+const computedTableProps = computed<TableProps>(() => {
+  const merged = {
+    ...injectAttrs.value,
+    ...omitBy(
+      pick(camelAttrs.value, tableProperties),
+      value => value === undefined
+    ),
+  } as Record<string, any>;
+  // onChange 由模板监听器收口，散落 attrs 中的同名监听器并入会形成重复回调
+  delete merged.onChange;
+  // resizeColumn 回传转换列时，用户回调仍操作原始列
+  const resizeColumn = merged.onResizeColumn;
+  if (typeof resizeColumn === 'function') {
+    merged.onResizeColumn = (width: number, column: any) =>
+      resizeColumn(width, resolveOriginalColumn(column));
   }
-  return { list, changed };
-};
+  merged.size = effectiveSize.value;
+  merged.loading = undefined;
+  return merged as TableProps;
+});
 
-const visibleComputedColumns = computed(() => {
-  return filterVisibleColumns(computedColumns.value).list;
+const ellipsisTooltipContainer = computed(() => {
+  const getPopupContainer = ellipsisTooltipConfig.value.getPopupContainer;
+  if (!getPopupContainer) return undefined;
+  return () => {
+    if (typeof document === 'undefined') return undefined;
+    const root = rootRef.value ?? document.body;
+    return getPopupContainer(root) ?? document.body;
+  };
+});
+const ellipsisTooltipDelay = computed(() =>
+  Math.max(0, (ellipsisTooltipConfig.value.mouseEnterDelay ?? 0.2) * 1000)
+);
+const ellipsisTooltipLeaveDelay = computed(() =>
+  Math.max(0, (ellipsisTooltipConfig.value.mouseLeaveDelay ?? 0.1) * 1000)
+);
+const ellipsisTooltipProps = computed(() => {
+  const config = ellipsisTooltipConfig.value;
+  const {
+    getPopupContainer: _getPopupContainer,
+    mouseEnterDelay: _mouseEnterDelay,
+    mouseLeaveDelay: _mouseLeaveDelay,
+    ...rest
+  } = config;
+  return rest;
 });
 
+const {
+  open: ellipsisTooltipOpen,
+  content: ellipsisTooltipContent,
+  anchorStyle: ellipsisTooltipAnchorStyle,
+  onMouseOver: onEllipsisMouseOver,
+  onMouseOut: onEllipsisMouseOut,
+  close: closeEllipsisTooltip,
+} = useEllipsisTooltip(
+  rootRef,
+  ellipsisTooltipEnabled,
+  ellipsisTooltipDelay,
+  ellipsisTooltipLeaveDelay
+);
+
 // 数据源优先级：显式绑定 > table 实例（useTable 创建的 dataSource）
 const computedDataSource = computed<RecordType[]>(() => {
   return (
@@ -424,6 +469,9 @@ const computedDataSource = computed<RecordType[]>(() => {
   );
 });
 
+// 列或数据变化后旧锚点失效，关闭共享 Tooltip
+watch([visibleComputedColumns, computedDataSource], closeEllipsisTooltip);
+
 /*
  * 分页优先级：显式绑定 > provider 全局配置 > 默认合成；
  * provider 作为基础配置与 table.pageParam 合并，显式绑定的对象形态在其之上覆盖
@@ -479,8 +527,15 @@ const onTableChange: TableProps['onChange'] = (...args) => {
     );
     if (shadowed.length) warnPaginationShadow(shadowed);
   }
-  // change 回放：模板监听器优先，未绑定时回退 Provider 全局配置
-  (attrs.onChange ?? injectProps.value.onChange)?.(...args);
+  // change 回放：模板监听器优先，未绑定时回退 Provider 全局配置；sorter.column 还原为原始列
+  const nextArgs = [...args] as any[];
+  const sorterArg = nextArgs[2];
+  if (Array.isArray(sorterArg)) {
+    nextArgs[2] = sorterArg.map(resolveSorterColumn);
+  } else if (sorterArg) {
+    nextArgs[2] = resolveSorterColumn(sorterArg);
+  }
+  (attrs.onChange ?? injectProps.value.onChange)?.(...nextArgs);
   _search();
 };
 
@@ -541,7 +596,15 @@ defineExpose({
 </script>
 
 <template>
-  <div class="pro-table" :class="attrs.class" :style="attrs.style">
+  <div
+    ref="rootRef"
+    class="pro-table"
+    data-pro-table-root
+    :class="attrs.class"
+    :style="attrs.style"
+    @mouseover="onEllipsisMouseOver"
+    @mouseout="onEllipsisMouseOut"
+  >
     <ContainerFragment
       v-if="searchFormVisible || $slots['search-form']"
       :component="computedSearchFormConfig.container"
@@ -620,6 +683,15 @@ defineExpose({
         </ATable>
       </slot>
     </ContainerFragment>
+
+    <TableEllipsisTooltip
+      v-if="ellipsisTooltipEnabled"
+      :open="ellipsisTooltipOpen"
+      :content="ellipsisTooltipContent"
+      :anchor-style="ellipsisTooltipAnchorStyle"
+      :container="ellipsisTooltipContainer"
+      v-bind="ellipsisTooltipProps"
+    />
   </div>
 </template>