8-09 · Table：列模型与固定列

// packages/components/table/src/table.vue:219-231
const mainHeaderTableRef = ref<TableSectionExpose | null>(null);
const leftHeaderTableRef = ref<TableSectionExpose | null>(null);
const rightHeaderTableRef = ref<TableSectionExpose | null>(null);
const bodyScrollbarRef = ref<TableScrollbarExpose | null>(null);
const mainBodyTableRef = ref<TableSectionExpose | null>(null);
const leftBodyTableRef = ref<TableSectionExpose | null>(null);
const rightBodyTableRef = ref<TableSectionExpose | null>(null);
const mainFooterTableRef = ref<TableSectionExpose | null>(null);
const leftFooterTableRef = ref<TableSectionExpose | null>(null);
const rightFooterTableRef = ref<TableSectionExpose | null>(null);
let rowHeightSyncFrame: number | null = null;
let rowHeightResizeObserver: ResizeObserver | null = null;
let autoLayoutSyncFrame: number | null = null;

<!-- packages/components/table/src/table.vue:1086-1130 -->
<div
  v-if="store.bodyRows.value.length > 0 && store.hasLeftFixedColumns.value"
  class="xy-table__fixed-panel xy-table__fixed-panel--body is-left"
  :style="leftFixedStyle"
  @wheel.prevent="handleFixedWheel($event)"
>
  <div class="xy-table__fixed-panel-inner" :style="fixedBodyInnerStyle">
    <table-body
      ref="leftBodyTableRef"
      :store="store"
      :columns="store.leftFixedColumns.value"
      panel="left"
      :row-class-name="props.rowClassName"
      :row-style="props.rowStyle"
      :cell-class-name="props.cellClassName"
      :cell-style="props.cellStyle"
      :clickable="props.clickable"
      :striped="mergedStripe"
      :highlight-current-row="props.highlightCurrentRow"
      :indent="props.indent"
      :span-method="props.spanMethod"
      :tooltip-formatter="props.tooltipFormatter"
      :preserve-expanded-content="props.preserveExpandedContent"
      :table-layout="props.tableLayout"
      :show-header="props.showHeader"
      :virtual="props.virtual"
      :virtual-item-size="resolvedVirtualItemSize"
      :virtual-overscan="props.virtualOverscan"
      :scroll-top="layout.scrollTop.value"
      :viewport-height="layout.bodyClientHeight.value"
      :expanded-row-mode="hasExpandedRows ? 'placeholder' : 'none'"
      :main-table-width="mainTableWidth"
      :left-fixed-width="leftFixedWidth"
      :right-fixed-width="rightFixedWidth"
      @row-click="handleRowClick"
      @row-dblclick="handleRowDblclick"
      @row-contextmenu="handleRowContextmenu"
      @cell-click="handleCellClick"
      @cell-dblclick="handleCellDblclick"
      @cell-contextmenu="handleCellContextmenu"
      @cell-mouse-enter="handleCellMouseEnter"
      @cell-mouse-leave="handleCellMouseLeave"
    />
  </div>
</div>

/* packages/theme/src/components/table.css:196-228 */
.xy-table__fixed-panel {
  position: absolute;
  top: 0;
  bottom: 0;
  overflow: hidden;
  z-index: 6;
  pointer-events: none;
  background: var(--xy-table-surface-background-resolved);
}

.xy-table__fixed-panel > * {
  pointer-events: auto;
}

.xy-table__fixed-panel.is-left {
  left: 0;
  box-shadow: 1px 0 0 color-mix(in srgb, var(--xy-table-border-color) 96%, transparent);
}

.xy-table__fixed-panel.is-right {
  right: 0;
  box-shadow: -1px 0 0 color-mix(in srgb, var(--xy-table-border-color) 96%, transparent);
}

.xy-table__fixed-panel--body {
  top: 0;
  bottom: 0;
}

.xy-table__fixed-panel-inner {
  min-width: 100%;
  will-change: transform;
}

// packages/components/table/src/table-layout.ts:40-90
function syncLayout(emitScroll = false) {
  const body = bodyWrapperRef.value;

  if (!body) {
    return;
  }

  scrollLeft.value = body.scrollLeft;
  scrollTop.value = body.scrollTop;
  bodyClientWidth.value = body.clientWidth;
  bodyClientHeight.value = body.clientHeight;
  hasHorizontalScroll.value = body.scrollWidth > body.clientWidth;
  hasVerticalScroll.value = body.scrollHeight > body.clientHeight;
  showLeftShadow.value = body.scrollLeft > 0;
  showRightShadow.value = body.scrollLeft + body.clientWidth < body.scrollWidth - 1;

  if (headerWrapperRef.value) {
    headerWrapperRef.value.scrollLeft = body.scrollLeft;
  }

  if (footerWrapperRef.value) {
    footerWrapperRef.value.scrollLeft = body.scrollLeft;
  }

  if (
    emitScroll &&
    (lastEmittedScroll.scrollLeft !== scrollLeft.value ||
      lastEmittedScroll.scrollTop !== scrollTop.value)
  ) {
    lastEmittedScroll = {
      scrollLeft: scrollLeft.value,
      scrollTop: scrollTop.value
    };
  }
}

function handleBodyScroll() {
  syncLayout(true);
}

function handleFixedWheel(event: WheelEvent) {
  const body = bodyWrapperRef.value;

  if (!body) {
    return;
  }

  body.scrollLeft += event.deltaX;
  body.scrollTop += event.deltaY;
  syncLayout(true);
}

// packages/components/table/src/table-column.vue:114-123（节选）
const descriptor = computed<TableResolvedColumn<T>>(() => ({
  uid,
  key: props.columnKey ?? props.prop ?? props.property ?? uid,
  type: props.type,
  prop: props.prop ?? props.property,
  label: props.label,
  columnKey: props.columnKey,
  width: props.width,
  minWidth: props.minWidth,
  realWidth: toNumberSize(props.width ?? props.minWidth),
  // ...

// packages/components/table/src/use-table-columns.ts:4-26
export function useTableColumns<T = Record<string, unknown>>() {
  const registrations = shallowRef<TableColumnRegistration<T>[]>([]);
  const sortRegistrations = (items: TableColumnRegistration<T>[]) =>
    items.slice().sort((left, right) => left.order.value - right.order.value);

  const registerColumn: TableContext<T>["registerColumn"] = (column) => {
    registrations.value = sortRegistrations([...registrations.value, column]);
  };

  const unregisterColumn: TableContext<T>["unregisterColumn"] = (uid) => {
    registrations.value = registrations.value.filter((column) => column.uid !== uid);
  };

  const columns = computed(() =>
    sortRegistrations(registrations.value).map((column) => column.descriptor.value)
  );

  return {
    columns,
    registerColumn,
    unregisterColumn
  };
}

// packages/components/table/src/table-column.vue:184-235
const registration = {
  uid,
  order,
  descriptor
} as TableColumnRegistration<T>;

function resolveAnchorNode() {
  const node = (instance?.subTree?.el ?? instance?.vnode?.el) as Node | null | undefined;
  return node ?? null;
}

function updateRenderOrder() {
  const anchorNode = resolveAnchorNode();

  if (!anchorNode?.parentNode) {
    return;
  }

  const targetNode = anchorNode as ChildNode;
  const siblings = Array.from(anchorNode.parentNode.childNodes);
  const nextOrder = siblings.indexOf(targetNode);

  if (nextOrder >= 0 && nextOrder !== order.value) {
    order.value = nextOrder;
  }
}

onBeforeMount(() => {
  if (parentColumn) {
    parentColumn.registerChildColumn(registration);
    return;
  }

  table?.registerColumn(registration);
});

onMounted(() => {
  updateRenderOrder();
});

onUpdated(() => {
  updateRenderOrder();
});

onBeforeUnmount(() => {
  if (parentColumn) {
    parentColumn.unregisterChildColumn(uid);
    return;
  }

  table?.unregisterColumn(uid);
});

// packages/components/table/src/util.ts:69-150
export function normalizeColumns<T>(
  columns: TableResolvedColumn<T>[],
  widthOverrides: Record<string, number>,
  tableShowOverflowTooltip?: TableOverflowTooltip,
  tableTooltipEffect?: TableOverflowTooltipOptions["effect"],
  tableTooltipOptions?: TableOverflowTooltipOptions,
  fit = true,
  containerWidth?: number
) {
  const maxLevel = getMaxLevel(columns);
  let leafIndex = 0;
  const leafWidthOverrides: Record<string, number> = {};
  const hasWidthOverride = (uid: string) =>
    Object.prototype.hasOwnProperty.call(widthOverrides, uid);

  const baseColumns = columns.map((column) =>
    normalizeColumn(
      column,
      widthOverrides,
      tableShowOverflowTooltip,
      tableTooltipEffect,
      tableTooltipOptions,
      maxLevel,
      column.fixed
    )
  );
  const leafColumns = flattenColumns(baseColumns);

  if (fit && containerWidth && containerWidth > 0) {
    const totalWidth = leafColumns.reduce((sum, column) => sum + column.realWidth, 0);
    const extraWidth = Math.floor(containerWidth - totalWidth);

    if (extraWidth > 0 && leafColumns.length > 0) {
      const flexibleColumns = leafColumns.filter(
        (column) => column.width === undefined && !hasWidthOverride(column.uid)
      );
      const nonOverriddenColumns = leafColumns.filter((column) => !hasWidthOverride(column.uid));
      const targetColumns =
        flexibleColumns.length > 0
          ? flexibleColumns
          : nonOverriddenColumns.length > 0
            ? nonOverriddenColumns
            : leafColumns;
      const evenExtra = Math.floor(extraWidth / targetColumns.length);
      let remainder = extraWidth % targetColumns.length;

      targetColumns.forEach((column) => {
        leafWidthOverrides[column.uid] = column.realWidth + evenExtra + (remainder > 0 ? 1 : 0);
        if (remainder > 0) {
          remainder -= 1;
        }
      });
    }
  }

  const normalize = (column: TableResolvedColumn<T>): TableResolvedColumn<T> => {
    const children = column.children.map(normalize);
    const isLeaf = children.length === 0;
    const realWidth = isLeaf
      ? (leafWidthOverrides[column.uid] ?? column.realWidth)
      : children.reduce((sum, child) => sum + child.realWidth, 0);
    const leafCount = isLeaf ? 1 : children.reduce((sum, item) => sum + item.leafCount, 0);
    const normalized: TableResolvedColumn<T> = {
      ...column,
      children,
      realWidth,
      leafCount,
      colSpan: leafCount,
      rowSpan: isLeaf ? maxLevel - column.level + 1 : 1,
      leafIndex: isLeaf ? leafIndex : (children[0]?.leafIndex ?? leafIndex)
    };

    if (isLeaf) {
      normalized.leafIndex = leafIndex;
      leafIndex += 1;
    }

    return normalized;
  };

  return baseColumns.map(normalize);
}

// packages/components/table/src/table-header/header.vue:163-211
function startResize(column: TableResolvedColumn<T>, event: MouseEvent) {
  if (event.button !== 0 || !canResizeColumn(column)) {
    return;
  }

  event.preventDefault();
  event.stopPropagation();

  const startCell = (event.currentTarget as HTMLElement | null)?.closest("th");
  const tableElement = startCell?.closest(".xy-table");

  if (!startCell || !tableElement) {
    return;
  }

  const startX = event.clientX;
  const startCellRect = startCell.getBoundingClientRect();
  const tableLeft = tableElement.getBoundingClientRect().left;
  const startWidth = startCellRect.width;
  const oldWidth = Math.round(startWidth);
  const startLeft = startCellRect.right - tableLeft;
  const startColumnLeft = startCellRect.left - tableLeft;
  const minLeft = startColumnLeft + 40;
  const previousCursor = document.body.style.cursor;
  const previousUserSelect = document.body.style.userSelect;

  document.body.style.cursor = "col-resize";
  document.body.style.userSelect = "none";
  emit("header-dragstart", startLeft);

  const handleMouseMove = (moveEvent: MouseEvent) => {
    const nextLeft = Math.max(minLeft, startLeft + (moveEvent.clientX - startX));
    emit("header-dragmove", nextLeft);
  };

  const handleMouseUp = (upEvent: MouseEvent) => {
    window.removeEventListener("mousemove", handleMouseMove);
    window.removeEventListener("mouseup", handleMouseUp);
    document.body.style.cursor = previousCursor;
    document.body.style.userSelect = previousUserSelect;

    const finalLeft = Math.max(minLeft, startLeft + (upEvent.clientX - startX));
    const newWidth = Math.max(40, Math.round(finalLeft - startColumnLeft));
    props.store.setColumnWidth(column.uid, newWidth);
    emit("header-dragend", newWidth, oldWidth, column, upEvent);
  };

  window.addEventListener("mousemove", handleMouseMove);
  window.addEventListener("mouseup", handleMouseUp);
}

// packages/components/table/src/util.ts:299-335
export function projectColumnsByFixed<T>(
  columns: TableResolvedColumn<T>[],
  section: Exclude<TableSection, "main">
) {
  const project = (column: TableResolvedColumn<T>): TableResolvedColumn<T> | null => {
    const children = column.children
      .map((child) => project(child))
      .filter((item): item is TableResolvedColumn<T> => Boolean(item));

    if (children.length === 0 && column.fixed !== section) {
      return null;
    }

    const leafCount =
      children.length > 0 ? children.reduce((sum, item) => sum + item.leafCount, 0) : 1;
    const realWidth =
      children.length > 0
        ? children.reduce((sum, item) => sum + item.realWidth, 0)
        : column.realWidth;

    return {
      ...column,
      fixed: section,
      children,
      leafCount,
      colSpan: leafCount,
      rowSpan: children.length > 0 ? 1 : column.rowSpan,
      realWidth
    };
  };

  return finalizeColumnTree(
    columns
      .map((column) => project(column))
      .filter((item): item is TableResolvedColumn<T> => Boolean(item))
  );
}

// packages/components/table/src/table.vue:547-558
const mainTableWidth = computed(() =>
  store.leafColumns.value.reduce((total, column) => total + column.realWidth, 0)
);
const leftFixedWidth = computed(() =>
  store.leftFixedLeafColumns.value.reduce((total, column) => total + column.realWidth, 0)
);
const rightFixedWidth = computed(() =>
  store.rightFixedLeafColumns.value.reduce((total, column) => total + column.realWidth, 0)
);
const fixedBodyInnerStyle = computed(() => ({
  transform: props.virtual ? undefined : `translateY(-${layout.scrollTop.value}px)`
}));

// packages/components/table/src/table.vue:293-338
function syncFixedPanelRowHeights() {
  rowHeightResizeObserver?.disconnect();

  const headerTables = [
    getSectionTable(mainHeaderTableRef),
    getSectionTable(leftHeaderTableRef),
    getSectionTable(rightHeaderTableRef)
  ];
  const bodyTables = [
    getSectionTable(mainBodyTableRef),
    getSectionTable(leftBodyTableRef),
    getSectionTable(rightBodyTableRef)
  ];
  const footerTables = [
    getSectionTable(mainFooterTableRef),
    getSectionTable(leftFooterTableRef),
    getSectionTable(rightFooterTableRef)
  ];
  const allTables = [...headerTables, ...bodyTables, ...footerTables];

  allTables.forEach(clearTableRowHeights);

  if (!store.hasFixedColumns.value) {
    return;
  }

  syncTableGroupRowHeights(headerTables);
  syncTableGroupRowHeights(bodyTables);
  syncTableGroupRowHeights(footerTables);
  observeRowHeightTables();
}

function scheduleFixedPanelRowHeightSync() {
  if (typeof window === "undefined") {
    return;
  }

  if (rowHeightSyncFrame !== null) {
    window.cancelAnimationFrame(rowHeightSyncFrame);
  }

  rowHeightSyncFrame = window.requestAnimationFrame(() => {
    rowHeightSyncFrame = null;
    syncFixedPanelRowHeights();
  });
}

// packages/components/table/src/table.vue:387-441（节选）
function createAutoLayoutMeasurementTable(sourceTable: HTMLTableElement) {
  if (sourceTable.getBoundingClientRect().width <= 0 || layout.bodyClientWidth.value <= 0) {
    return sourceTable;
  }

  const measurementHost = document.createElement("div");
  const measurementTable = sourceTable.cloneNode(true) as HTMLTableElement;
  const width = Math.max(
    layout.bodyClientWidth.value,
    bodyScrollbarRef.value?.wrapRef?.clientWidth ?? 0,
    rootRef.value?.clientWidth ?? 0
  );

  measurementHost.setAttribute("aria-hidden", "true");
  measurementHost.style.position = "absolute";
  measurementHost.style.left = "0";
  measurementHost.style.top = "0";
  measurementHost.style.width = width > 0 ? `${width}px` : "100%";
  measurementHost.style.height = "0";
  measurementHost.style.overflow = "hidden";
  measurementHost.style.visibility = "hidden";
  measurementHost.style.pointerEvents = "none";
  measurementHost.style.zIndex = "-1";

  measurementTable.querySelectorAll("colgroup").forEach((element) => {
    element.remove();
  });
  // ……把 sizing 表头恢复为正常 thead 参与 auto 测宽，重建 colgroup 后量 th 宽

// packages/components/table/src/store/index.ts:1174-1219
function setColumnWidth(uid: string, width: number) {
  widthOverrides.value = {
    ...widthOverrides.value,
    [uid]: Math.max(40, Math.round(width))
  };
}

function hasColumnWidthOverride(uid: string) {
  return Object.prototype.hasOwnProperty.call(widthOverrides.value, uid);
}

function syncAutoColumnWidths(widths: Record<string, number>) {
  const nextWidths: Record<string, number> = {};

  Object.entries(widths).forEach(([uid, width]) => {
    if (!Number.isFinite(width)) {
      return;
    }

    const normalizedWidth = Math.max(40, Math.round(width));

    if (normalizedWidth > 0) {
      nextWidths[uid] = normalizedWidth;
    }
  });

  const previousEntries = Object.entries(autoWidthOverrides.value);
  const nextEntries = Object.entries(nextWidths);

  if (
    previousEntries.length === nextEntries.length &&
    nextEntries.every(([uid, width]) => autoWidthOverrides.value[uid] === width)
  ) {
    return;
  }

  autoWidthOverrides.value = nextWidths;
}

function clearAutoColumnWidths() {
  if (Object.keys(autoWidthOverrides.value).length === 0) {
    return;
  }

  autoWidthOverrides.value = {};
}

// packages/components/table/src/table.vue:620-625
const appendWrapperStyle = computed(() => ({
  width: mainTableWidth.value > 0 ? toCssSize(mainTableWidth.value) : undefined,
  minWidth: "100%",
  paddingLeft: leftFixedWidth.value > 0 ? toCssSize(leftFixedWidth.value) : undefined,
  paddingRight: rightFixedWidth.value > 0 ? toCssSize(rightFixedWidth.value) : undefined
}));