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

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,
+  };
+}

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

@@ -0,0 +1,139 @@
+import { computed, toRaw, toValue, type ComputedRef } from 'vue';
+import { isObjectItem, isPlainObject } from '../../../shared/core';
+import { ELLIPSIS_TOOLTIP_CELL_ATTR } from './useEllipsisTooltip';
+
+type ColumnTransformResult = {
+  columns: any[];
+  changed: boolean;
+  hasTooltip: boolean;
+};
+
+/**
+ * 省略 Tooltip 列转换
+ *
+ * @description 一次遍历完成 hidden 过滤、分组子列递归与 showTooltip 列标记；
+ * 仅对发生变化的列生成克隆并登记原始列，供宿主回传列对象时还原。
+ * 列还原最多回溯两跳（宿主克隆 → 转换克隆 → 原始列），依赖单遍转换每列最多产生一层克隆。
+ *
+ * @param getColumns - 读取原始列配置
+ * @param globalEnabled - 是否全局启用列 Tooltip
+ * @returns 可见列、是否含 Tooltip 列与列还原函数
+ */
+export function useEllipsisTooltipColumns(
+  getColumns: () => any[],
+  globalEnabled: () => boolean = () => false
+): {
+  columns: ComputedRef<any[]>;
+  hasTooltip: ComputedRef<boolean>;
+  resolveOriginalColumn: (column: any) => any;
+  resolveSorterColumn: (sorter: any) => any;
+} {
+  const originalColumns = new WeakMap<object, any>();
+
+  const registerColumnClone = (next: any, source: any) => {
+    if (next !== source && isObjectItem(next) && !originalColumns.has(next)) {
+      originalColumns.set(next, source);
+    }
+    return next;
+  };
+
+  // 宿主内部列克隆通过 __originColumn__ 回指原始列（@private）
+  const resolveOriginalColumn = (column: any) => {
+    const raw = toRaw(column);
+    const source = originalColumns.get(raw) ?? raw.__originColumn__;
+    if (!isObjectItem(source)) return column;
+    return originalColumns.get(toRaw(source)) ?? source;
+  };
+
+  const resolveSorterColumn = (sorter: any) =>
+    sorter && typeof sorter === 'object' && sorter.column
+      ? { ...sorter, column: resolveOriginalColumn(sorter.column) }
+      : sorter;
+
+  const transformColumns = (
+    columns: any[],
+    global: boolean,
+    ancestors: Set<object> = new Set()
+  ): ColumnTransformResult => {
+    const list: any[] = [];
+    let changed = false;
+    let hasTooltip = false;
+
+    for (const column of columns) {
+      if (!isObjectItem(column) || toValue(column.hidden)) {
+        changed = true;
+        continue;
+      }
+
+      let childChanged = false;
+      let childColumns = column.children;
+      let childHasTooltip = false;
+
+      if (Array.isArray(column.children) && column.children.length > 0) {
+        if (ancestors.has(column)) {
+          changed = true;
+          continue;
+        }
+        ancestors.add(column);
+        const child = transformColumns(column.children, global, ancestors);
+        ancestors.delete(column);
+        childChanged = child.changed;
+        childColumns = child.columns;
+        childHasTooltip = child.hasTooltip;
+      }
+
+      const ellipsis = column.ellipsis;
+      const explicit =
+        ellipsis === false
+          ? false
+          : isPlainObject(ellipsis)
+            ? ellipsis.showTooltip
+            : undefined;
+      const tooltipEnabled =
+        explicit === false ? false : global || explicit === true;
+      let next = column;
+
+      if (childChanged || tooltipEnabled) {
+        const { showTooltip: _showTooltip, ...restEllipsis } = isPlainObject(
+          ellipsis
+        )
+          ? ellipsis
+          : {};
+        const customCell = column.customCell;
+        next = {
+          ...column,
+          ...(childChanged ? { children: childColumns } : {}),
+          ...(tooltipEnabled
+            ? {
+                ellipsis: { ...restEllipsis, showTitle: false },
+                customCell: (
+                  record: any,
+                  rowIndex: number,
+                  cellColumn: any
+                ) => ({
+                  ...(customCell?.(record, rowIndex, cellColumn) ?? {}),
+                  [ELLIPSIS_TOOLTIP_CELL_ATTR]: '',
+                }),
+              }
+            : {}),
+        };
+        registerColumnClone(next, column);
+        changed = true;
+      }
+
+      if (tooltipEnabled || childHasTooltip) hasTooltip = true;
+      list.push(next);
+    }
+
+    return { columns: changed ? list : columns, changed, hasTooltip };
+  };
+
+  const state = computed(() => transformColumns(getColumns(), globalEnabled()));
+
+  return {
+    columns: computed(() => state.value.columns),
+    hasTooltip: computed(() => state.value.hasTooltip),
+    resolveOriginalColumn,
+    resolveSorterColumn,
+  };
+}

package/src/components/table/index.ts

@@ -10,7 +10,13 @@ export type ProTableProps = ComponentProps<typeof ProTable>;
 export type ProTableInstance = ComponentExposed<typeof ProTable>;
 
 // 仅导出核心列配置类型
-export { type Column, type ColumnControlConfig, type Columns } from './types';
+export {
+  type Column,
+  type ColumnControlConfig,
+  type ColumnEllipsis,
+  type Columns,
+  type EllipsisTooltipConfig,
+} from './types';
 
 // 仅导出核心表格 Hook 与类型
 export { useTable, type Table } from './hooks';

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

@@ -1,9 +1,64 @@
-import type { ColumnType } from '../../../shared/ui';
+import type { ColumnType, TooltipProps } from '../../../shared/ui';
 import type { Data, KeyExpandString, Paths, Path } from '../../../shared/core';
 import type { ComputedRef, MaybeRef } from 'vue';
 
 type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
+/**
+ * 列内容省略配置
+ *
+ * @description 在宿主 `ellipsis` 基础上增加 `showTooltip`：单元格文本横向溢出时，
+ * 悬停由表格级共享的同一个 Tooltip 展示完整文本。`showTooltip` 为 `true` 时不输出宿主原生 `title`。
+ *
+ * @example
+ * ```ts
+ * const column: Column<User> = {
+ *   dataIndex: 'name',
+ *   ellipsis: { showTooltip: true },
+ * }
+ * ```
+ *
+ * @public
+ */
+export type ColumnEllipsis = NonNullable<
+  Exclude<ColumnType['ellipsis'], boolean>
+> & {
+  /** 文本溢出时是否显示表格级共享 Tooltip */
+  showTooltip?: boolean;
+};
+
+/**
+ * ProTable 共享省略 Tooltip 配置
+ *
+ * @description 复用宿主 Tooltip 的容器、延迟、方位与浮层样式字段，控制表格级单例 Tooltip。
+ * ProTable 侧另接受 `true` 作为全局启用简写；列上 `showTooltip: false` 或 `ellipsis: false` 可退出。
+ *
+ * @example
+ * ```ts
+ * const config: EllipsisTooltipConfig = {
+ *   getPopupContainer: () => document.body,
+ *   mouseEnterDelay: 0.2,
+ *   mouseLeaveDelay: 0.1,
+ *   placement: 'top',
+ * }
+ * ```
+ *
+ * @public
+ */
+export type EllipsisTooltipConfig = Pick<
+  TooltipProps,
+  | 'getPopupContainer'
+  | 'mouseEnterDelay'
+  | 'mouseLeaveDelay'
+  | 'placement'
+  | 'arrow'
+  | 'autoAdjustOverflow'
+  | 'color'
+  | 'overlayClassName'
+  | 'overlayStyle'
+  | 'overlayInnerStyle'
+>;
+
 /**
  * 表格列配置类型
  *
@@ -11,6 +66,7 @@ type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
  * - 类型安全的 dataIndex（基于泛型 D 推导路径），优先使用
  * - key 作为辅助标识，当 dataIndex 不满足需求时使用
  * - hidden 属性用于控制列显隐
+ * - ellipsis 支持 `{ showTooltip: boolean }` 的表格级共享 Tooltip
  * - 所有 Ant Design Vue 原生的列属性依然可用（title、width、fixed、align 等）
  *
  * @template D - 表格行数据类型
@@ -37,7 +93,7 @@ type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
  */
 export type Column<D extends Data = Data> = Omit<
   ColumnType,
-  'dataIndex' | 'key'
+  'dataIndex' | 'key' | 'ellipsis'
 > & {
   /**
    * 列数据路径（主要字段）
@@ -59,6 +115,10 @@ export type Column<D extends Data = Data> = Omit<
    * @default false
    */
   hidden?: MaybeRefOrComputedRef<boolean>;
+  /**
+   * 列内容省略配置；`true` 等价于宿主默认省略，对象形态额外支持表格级共享 Tooltip
+   */
+  ellipsis?: boolean | ColumnEllipsis;
   /**
    * 分组子列；提供时该列作为分组表头渲染，子列沿用同一配置类型
    */

package/src/shared/ui/index.ts

@@ -36,6 +36,7 @@ export {
   Transfer,
   TreeSelect,
   RangePicker,
+  Tooltip,
   type FormItemInstance,
   type FormInstance,
   type RowProps as GridProps,
@@ -45,6 +46,7 @@ export {
 } 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 {