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

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

@@ -1,8 +1,9 @@
 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 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, Tooltip, 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 { TooltipProps } from 'ant-design-vue';
 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';

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,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"}
+{"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,OAAO,EACP,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,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,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.5.3",
+  "version": "2.6.0",
   "description": "二次封装antd vue组件",
   "bin": {
     "antd-vue-pro": "./bin/init-ai.mjs"
@@ -44,7 +44,7 @@
   "dependencies": {
     "scroll-into-view-if-needed": "^3.1.0",
     "vue-component-type-helpers": "^3.2.5",
-    "@qin-ui/pro-components-core": "^2.1.1"
+    "@qin-ui/pro-components-core": "^2.1.2"
   },
   "devDependencies": {
     "@types/node": "^24",

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

@@ -58,6 +58,7 @@ export type RequiredComponentVars = {
         | 'immediateSearch'
         | 'addIndexColumn'
         | 'tableContainer'
+        | 'ellipsisTooltip'
       >
   >;
   /** ProForm 全局默认属性，grid 必须为 GridProps 对象而非 boolean */

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>
 

package/src/components/table/components/TableEllipsisTooltip.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+/**
+ * 表格级共享省略 Tooltip
+ *
+ * @component TableEllipsisTooltip
+ * @description 以固定定位锚点承载单个宿主 Tooltip，锚点位置由 ProTable 按悬停单元格更新；
+ * 整个表格只渲染一个 Tooltip 实例，实例数量不随单元格数量增长。
+ */
+import { nextTick, ref, useAttrs, watch, type Component } from 'vue';
+import { Tooltip as ATooltip } from '../../../shared/ui';
+import type { EllipsisTooltipAnchorStyle } from '../hooks/useEllipsisTooltip';
+import type { EllipsisTooltipConfig } from '../types';
+
+defineOptions({ name: 'TableEllipsisTooltip', inheritAttrs: false });
+
+type HostTooltipProps = Omit<
+  EllipsisTooltipConfig,
+  'getPopupContainer' | 'mouseEnterDelay' | 'mouseLeaveDelay'
+>;
+
+type Props = {
+  open?: boolean;
+  content?: string;
+  anchorStyle?: EllipsisTooltipAnchorStyle;
+  container?: () => HTMLElement | null | undefined;
+} & /* @vue-ignore */ HostTooltipProps;
+
+const props = withDefaults(defineProps<Props>(), {
+  open: false,
+  content: '',
+  anchorStyle: () => ({
+    position: 'fixed',
+    pointerEvents: 'none',
+    opacity: 0,
+  }),
+  container: () => undefined,
+});
+const attrs = useAttrs() as HostTooltipProps;
+const HostTooltip = ATooltip as unknown as Component;
+
+type TooltipInstance = {
+  forceAlign?: () => void;
+  forcePopupAlign?: () => void;
+};
+
+const tooltipRef = ref<TooltipInstance | null>(null);
+
+/** 锚点或内容变化后重算宿主浮层位置 */
+const forceAlign = async () => {
+  if (!props.open) return;
+  await nextTick();
+  const instance = tooltipRef.value;
+  (instance?.forceAlign ?? instance?.forcePopupAlign)?.();
+};
+
+watch(() => props.anchorStyle, forceAlign, { deep: true });
+watch(
+  () => props.open,
+  value => {
+    if (value) forceAlign();
+  }
+);
+
+const getContainerNode = (): HTMLElement | undefined => {
+  const container = props.container?.();
+  if (container) return container;
+  return typeof document !== 'undefined' ? document.body : undefined;
+};
+
+const getPopupContainer = () => getContainerNode() ?? document.body;
+</script>
+
+<template>
+  <Teleport :to="getContainerNode() ?? 'body'">
+    <HostTooltip
+      v-bind="attrs"
+      ref="tooltipRef"
+      :open="open"
+      :title="content"
+      :trigger="[]"
+      :get-popup-container="getPopupContainer"
+    >
+      <span
+        class="pro-table_ellipsis-tooltip-anchor"
+        :style="anchorStyle"
+        aria-hidden="true"
+      />
+    </HostTooltip>
+  </Teleport>
+</template>

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

@@ -0,0 +1,244 @@
+import {
+  onBeforeUnmount,
+  onDeactivated,
+  onMounted,
+  ref,
+  watch,
+  type Ref,
+} from 'vue';
+
+/** 省略单元格标记属性，由列转换写入 body 单元格 */
+export const ELLIPSIS_TOOLTIP_CELL_ATTR = 'data-pro-table-ellipsis';
+
+/** ProTable 根节点归属标记 */
+export const PRO_TABLE_ROOT_ATTR = 'data-pro-table-root';
+
+/** 共享 Tooltip 锚点样式 */
+export type EllipsisTooltipAnchorStyle = {
+  position: 'fixed';
+  pointerEvents: 'none';
+  opacity: number;
+  left?: string;
+  top?: string;
+  width?: string;
+  height?: string;
+};
+
+/** 共享 Tooltip 状态与事件处理器 */
+export type EllipsisTooltipState = {
+  /** Tooltip 是否展示 */
+  open: Ref<boolean>;
+  /** Tooltip 文本 */
+  content: Ref<string>;
+  /** 固定定位锚点样式 */
+  anchorStyle: Ref<EllipsisTooltipAnchorStyle>;
+  /** 根节点 mouseover 处理器 */
+  onMouseOver: (event: MouseEvent) => void;
+  /** 根节点 mouseout 处理器 */
+  onMouseOut: (event: MouseEvent) => void;
+  /** 关闭 Tooltip */
+  close: () => void;
+};
+
+/** 共享 Tooltip 锚点的基础样式：固定定位，不参与命中测试与绘制 */
+const ANCHOR_BASE_STYLE: EllipsisTooltipAnchorStyle = {
+  position: 'fixed',
+  pointerEvents: 'none',
+  opacity: 0,
+};
+
+/** 读取单元格可读文本，连续空白折叠为单个空格 */
+const getCellText = (cell: HTMLElement) => {
+  const text = cell.innerText || cell.textContent || '';
+  return text.replace(/\s+/g, ' ').trim();
+};
+
+/** 单元格测量结果：文本与是否横向溢出 */
+type CellMeasurement = {
+  text: string;
+  overflow: boolean;
+};
+
+/** 单次读取单元格文本并判断横向溢出 */
+const measureCell = (cell: HTMLElement): CellMeasurement => {
+  const text = getCellText(cell);
+  return {
+    text,
+    overflow: Boolean(text) && cell.scrollWidth > cell.clientWidth,
+  };
+};
+
+/**
+ * 表格级共享省略 Tooltip
+ *
+ * @description
+ * 在 ProTable 根节点上以事件委托识别带标记的 body 单元格，维护单个 Tooltip 的显隐、文本与固定定位锚点；
+ * 仅在单元格文本横向溢出时触发；表格滚动、窗口尺寸变化、KeepAlive 停用时关闭，卸载时移除监听。
+ *
+ * @param rootRef - ProTable 根节点引用
+ * @param enabled - 是否启用共享 Tooltip；为 false 时不注册全局监听
+ * @param delay - 悬停延迟（ms），0 表示立即展示
+ * @param leaveDelay - 移出延迟（ms），0 表示立即关闭
+ * @returns Tooltip 状态与根节点事件处理器
+ */
+export function useEllipsisTooltip(
+  rootRef: Ref<HTMLElement | null | undefined>,
+  enabled: Ref<boolean>,
+  delay: Ref<number>,
+  leaveDelay: Ref<number>
+): EllipsisTooltipState {
+  const open = ref(false);
+  const content = ref('');
+  const anchorStyle = ref<EllipsisTooltipAnchorStyle>({
+    ...ANCHOR_BASE_STYLE,
+  });
+  let activeCell: HTMLElement | null = null;
+  let pendingCell: HTMLElement | null = null;
+  let openTimer: ReturnType<typeof setTimeout> | null = null;
+  let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearOpenTimer = () => {
+    if (openTimer === null) return;
+    clearTimeout(openTimer);
+    openTimer = null;
+    pendingCell = null;
+  };
+
+  const clearCloseTimer = () => {
+    if (closeTimer === null) return;
+    clearTimeout(closeTimer);
+    closeTimer = null;
+  };
+
+  const close = () => {
+    clearOpenTimer();
+    clearCloseTimer();
+    open.value = false;
+    activeCell = null;
+  };
+
+  const getEventRoot = (node: Node | null) => {
+    const element = node instanceof Element ? node : node?.parentElement;
+    return element?.closest?.(`[${PRO_TABLE_ROOT_ATTR}]`) ?? null;
+  };
+
+  const getCellFromEvent = (event: MouseEvent) => {
+    const target = event.target as Element | null;
+    const cell = target?.closest?.(`[${ELLIPSIS_TOOLTIP_CELL_ATTR}]`);
+    if (!(cell instanceof HTMLElement)) return null;
+    const root = rootRef.value;
+    if (!root) return null;
+    if (cell.closest(`[${PRO_TABLE_ROOT_ATTR}]`) !== root) return null;
+    return cell;
+  };
+
+  const onMouseOver = (event: MouseEvent) => {
+    const cell = getCellFromEvent(event);
+    if (!cell) return;
+    clearCloseTimer();
+    if (cell === activeCell || cell === pendingCell) return;
+    close();
+    const measurement = measureCell(cell);
+    if (!measurement.overflow) return;
+    const rect = cell.getBoundingClientRect();
+    if (!rect.width || !rect.height) return;
+    content.value = measurement.text;
+    anchorStyle.value = {
+      ...ANCHOR_BASE_STYLE,
+      left: `${rect.left}px`,
+      top: `${rect.top}px`,
+      width: `${rect.width}px`,
+      height: `${rect.height}px`,
+    };
+    pendingCell = cell;
+    openTimer = setTimeout(
+      () => {
+        openTimer = null;
+        pendingCell = null;
+        if (!cell.isConnected) return;
+        activeCell = cell;
+        open.value = true;
+      },
+      Math.max(0, delay.value)
+    );
+  };
+
+  const onMouseOut = (event: MouseEvent) => {
+    if (!activeCell && !pendingCell) return;
+
+    const owner = activeCell ?? pendingCell;
+    const target = event.target as Node | null;
+    if (!owner || !target || !owner.contains(target)) return;
+
+    const related = event.relatedTarget as Node | null;
+    if (related && owner.contains(related)) {
+      const relatedRoot = getEventRoot(related);
+      if (!relatedRoot || relatedRoot === rootRef.value) return;
+      close();
+      return;
+    }
+
+    if (pendingCell) {
+      close();
+      return;
+    }
+
+    clearCloseTimer();
+    const delayMs = Math.max(0, leaveDelay.value);
+    if (delayMs === 0) {
+      close();
+      return;
+    }
+    closeTimer = setTimeout(() => {
+      closeTimer = null;
+      close();
+    }, delayMs);
+  };
+
+  const onViewportChange = () => close();
+  let listening = false;
+
+  const addViewportListeners = () => {
+    if (listening || typeof window === 'undefined') return;
+    listening = true;
+    window.addEventListener('scroll', onViewportChange, true);
+    window.addEventListener('resize', onViewportChange);
+  };
+
+  const removeViewportListeners = () => {
+    if (!listening) return;
+    listening = false;
+    window.removeEventListener('scroll', onViewportChange, true);
+    window.removeEventListener('resize', onViewportChange);
+  };
+
+  onDeactivated(close);
+
+  onMounted(() => {
+    if (enabled.value) addViewportListeners();
+  });
+
+  watch(enabled, value => {
+    if (value) {
+      addViewportListeners();
+    } else {
+      removeViewportListeners();
+      close();
+    }
+  });
+
+  onBeforeUnmount(() => {
+    removeViewportListeners();
+    clearOpenTimer();
+    clearCloseTimer();
+  });
+
+  return {
+    open,
+    content,
+    anchorStyle,
+    onMouseOver,
+    onMouseOut,
+    close,
+  };
+}