fix(Table): improve horizontal scroll handling for fixedRows and headerAffixedTop

RylanBot · RylanBot · commit 90c00aebbf4c · 2025-10-20T11:36:32.000+08:00
diff --git a/packages/components/table/BaseTable.tsx b/packages/components/table/BaseTable.tsx
@@ -1,8 +1,8 @@
-import React, { forwardRef, RefAttributes, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
-import classNames from 'classnames';
-import { pick } from 'lodash-es';
 import log from '@tdesign/common-js/log/index';
 import { getIEVersion } from '@tdesign/common-js/utils/helper';
+import classNames from 'classnames';
+import { pick } from 'lodash-es';
+import React, { forwardRef, RefAttributes, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import Affix, { type AffixRef } from '../affix';
 import useDefaultProps from '../hooks/useDefaultProps';
 import useElementLazyRender from '../hooks/useElementLazyRender';
@@ -80,7 +80,7 @@ const BaseTable = forwardRef<BaseTableRef, BaseTableProps>((originalProps, ref)
     showAffixHeader,
     showAffixFooter,
     showAffixPagination,
-    onHorizontalScroll,
+    onTableHorizontalScroll,
     setTableContentRef,
     updateAffixHeaderOrFooter,
   } = useAffix(props, { showElement });
@@ -184,7 +184,7 @@ const BaseTable = forwardRef<BaseTableRef, BaseTableProps>((originalProps, ref)
 
   const onFixedChange = () => {
     const timer = setTimeout(() => {
-      onHorizontalScroll();
+      onTableHorizontalScroll();
       updateAffixHeaderOrFooter();
       clearTimeout(timer);
     }, 0);
@@ -244,7 +244,7 @@ const BaseTable = forwardRef<BaseTableRef, BaseTableProps>((originalProps, ref)
       updateColumnFixedShadow(target);
     }
     lastScrollY = top;
-    onHorizontalScroll(target);
+    onTableHorizontalScroll(target);
     emitScrollEvent(e);
   };
 
diff --git a/packages/components/table/_example/fixed-column.tsx b/packages/components/table/_example/fixed-column.tsx
@@ -1,6 +1,6 @@
 import React, { useRef, useState } from 'react';
-import { Table, Radio, Checkbox, Space, Tag, Link } from 'tdesign-react';
-import { ErrorCircleFilledIcon, CheckCircleFilledIcon, CloseCircleFilledIcon } from 'tdesign-icons-react';
+import { Button, Checkbox, Link, Radio, Space, Table, Tag } from 'tdesign-react';
+import { CheckCircleFilledIcon, CloseCircleFilledIcon, ErrorCircleFilledIcon } from 'tdesign-icons-react';
 
 import type { TableProps } from 'tdesign-react';
 
@@ -27,13 +27,13 @@ const statusNameListMap = {
 };
 
 export default function TableFixedColumn() {
+  const tableRef = useRef(null);
+
   const [tableLayout, setTableLayout] = useState<TableProps['tableLayout']>('fixed');
   const [emptyData, setEmptyData] = useState(false);
   const [leftFixedColumn, setLeftFixedColumn] = useState(2);
   const [rightFixedColumn, setReftFixedColumn] = useState(1);
 
-  const tableRef = useRef(null);
-  // eslint-disable-next-line
   const scrollToCreateTime = () => {
     // 横向滚动到指定列，一般用于列数量较多的场景
     tableRef.current.scrollColumnIntoView('createTime');
@@ -42,6 +42,7 @@ export default function TableFixedColumn() {
   const table = (
     <Table
       ref={tableRef}
+      style={{ maxWidth: '800px' }}
       bordered
       rowKey="index"
       data={emptyData ? [] : data}
@@ -101,7 +102,7 @@ export default function TableFixedColumn() {
         <Radio.Button value={2}>右侧固定两列</Radio.Button>
       </Radio.Group>
 
-      <div>
+      <Space align="center">
         <Radio.Group
           value={tableLayout}
           variant="default-filled"
@@ -110,10 +111,13 @@ export default function TableFixedColumn() {
           <Radio.Button value="fixed">table-layout: fixed</Radio.Button>
           <Radio.Button value="auto">table-layout: auto</Radio.Button>
         </Radio.Group>
-        <Checkbox value={emptyData} onChange={setEmptyData} style={{ marginLeft: '16px', verticalAlign: 'middle' }}>
+        <Button onClick={scrollToCreateTime} variant="dashed">
+          滚动到指定列
+        </Button>
+        <Checkbox value={emptyData} onChange={setEmptyData}>
           空数据
         </Checkbox>
-      </div>
+      </Space>
 
       {table}
     </Space>
diff --git a/packages/components/table/_example/fixed-header-col.tsx b/packages/components/table/_example/fixed-header-col.tsx
@@ -19,7 +19,6 @@ for (let i = 0; i < 20; i++) {
     index: i,
     applicant: ['贾明', '张三', '王芳'][i % 3],
     status: i % 3,
-    channel: ['电子签署', '纸质签署', '纸质签署'][i % 3],
     detail: {
       email: ['w.cezkdudy@lhll.au', 'r.nmgw@peurezgn.sl', 'p.cumx@rampblpa.ru'][i % 3],
     },
@@ -65,7 +64,6 @@ export default function TableFixedColumn() {
             );
           },
         },
-        { colKey: 'channel', title: '签署方式' },
         { colKey: 'matters', title: '申请事项', width: '150', foot: '-' },
         { colKey: 'detail.email', title: '邮箱地址' },
         { colKey: 'createTime', title: '申请日期', width: '120', foot: '-' },
diff --git a/packages/components/table/hooks/useAffix.ts b/packages/components/table/hooks/useAffix.ts
@@ -1,7 +1,7 @@
-import { useState, useRef, useMemo, useEffect } from 'react';
-import { TdBaseTableProps } from '../type';
-import { AffixProps } from '../../affix';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { off, on } from '../../_util/listener';
+import type { AffixProps } from '../../affix';
+import type { TdBaseTableProps } from '../type';
 
 /**
  * 1. 表头吸顶（普通表头吸顶 和 虚拟滚动表头吸顶）
@@ -11,6 +11,9 @@ import { off, on } from '../../_util/listener';
  */
 export default function useAffix(props: TdBaseTableProps, { showElement }: { showElement: boolean }) {
   const tableContentRef = useRef<HTMLDivElement>(null);
+  const lastTableScrollLeftRef = useRef<number>(0);
+  const lastPageScrollLeftRef = useRef<number>(0);
+
   // 吸顶表头
   const affixHeaderRef = useRef<HTMLDivElement>(null);
   // 吸底表尾
@@ -19,6 +22,7 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
   const horizontalScrollbarRef = useRef<HTMLDivElement>(null);
   // 吸底分页器
   const paginationRef = useRef<HTMLDivElement>(null);
+
   // 当表格完全滚动消失在视野时，需要隐藏吸顶表头
   const [showAffixHeader, setShowAffixHeader] = useState(true);
   // 当表格完全滚动消失在视野时，需要隐藏吸底尾部
@@ -32,23 +36,23 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
   );
 
   const isAffixed = useMemo(
-    () => !!(props.headerAffixedTop || props.footerAffixedBottom || props.horizontalScrollAffixedBottom),
-    [props.footerAffixedBottom, props.headerAffixedTop, props.horizontalScrollAffixedBottom],
+    () =>
+      !!(isVirtualScroll || props.headerAffixedTop || props.footerAffixedBottom || props.horizontalScrollAffixedBottom),
+    [isVirtualScroll, props.footerAffixedBottom, props.headerAffixedTop, props.horizontalScrollAffixedBottom],
   );
 
-  let lastScrollLeft = 0;
-  const onHorizontalScroll = (scrollElement?: HTMLElement) => {
-    if (!isAffixed && !isVirtualScroll) return;
+  const onTableHorizontalScroll = (scrollElement?: HTMLElement) => {
+    if (!isAffixed) return;
     let target = scrollElement;
     if (!target && tableContentRef.current) {
-      lastScrollLeft = 0;
+      lastTableScrollLeftRef.current = 0;
       target = tableContentRef.current;
     }
     if (!target) return;
     const left = target.scrollLeft;
     // 如果 lastScrollLeft 等于 left，说明不是横向滚动，不需要更新横向滚动距离
-    if (lastScrollLeft === left) return;
-    lastScrollLeft = left;
+    if (lastTableScrollLeftRef.current === left) return;
+    lastTableScrollLeftRef.current = left;
     // 表格内容、吸顶表头、吸底表尾、吸底横向滚动更新
     const toUpdateScrollElement = [
       tableContentRef.current,
@@ -63,6 +67,28 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
     }
   };
 
+  const onPageHorizontalScroll = () => {
+    if (!isAffixed || !props.fixedRows?.length) return;
+
+    const pageScrollLeft = window.pageXOffset || document.documentElement.scrollLeft || document.body.scrollLeft || 0;
+    if (lastPageScrollLeftRef.current === pageScrollLeft) return;
+    lastPageScrollLeftRef.current = pageScrollLeft;
+
+    const toUpdateScrollElement = [affixHeaderRef.current, affixFooterRef.current, horizontalScrollbarRef.current];
+    toUpdateScrollElement.forEach((element) => {
+      if (element) {
+        // 固定行会使用绝对定位，吸顶表头的位置计算需要考虑页面级别的滚动偏移
+        if (props.fixedRows.length) {
+          // eslint-disable-next-line no-param-reassign
+          element.style.marginLeft = `-${pageScrollLeft}px`;
+        } else if (element.style.marginLeft) {
+          // eslint-disable-next-line no-param-reassign
+          element.style.marginLeft = '';
+        }
+      }
+    });
+  };
+
   // 吸底的元素（footer、横向滚动条、分页器）是否显示
   const isAffixedBottomElementShow = (elementRect: DOMRect, tableRect: DOMRect, headerHeight: number) =>
     tableRect.top + headerHeight < elementRect.top && elementRect.top > elementRect.height;
@@ -73,7 +99,7 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
   };
 
   const updateAffixHeaderOrFooter = () => {
-    if (!isAffixed && !isVirtualScroll) return;
+    if (!isAffixed) return;
     const pos = tableContentRef.current?.getBoundingClientRect();
     if (!pos) return;
     const headerRect = tableContentRef.current?.querySelector('thead')?.getBoundingClientRect();
@@ -105,24 +131,25 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
     }
   };
 
-  const onDocumentScroll = () => {
+  const onPageScroll = () => {
     updateAffixHeaderOrFooter();
+    onPageHorizontalScroll();
   };
 
   const onFootScroll = () => {
-    onHorizontalScroll(affixFooterRef.current);
+    onTableHorizontalScroll(affixFooterRef.current);
   };
 
   const onHeaderScroll = () => {
-    onHorizontalScroll(affixHeaderRef.current);
+    onTableHorizontalScroll(affixHeaderRef.current);
   };
 
   const horizontalScrollbarScroll = () => {
-    onHorizontalScroll(horizontalScrollbarRef.current);
+    onTableHorizontalScroll(horizontalScrollbarRef.current);
   };
 
   const onTableContentScroll = () => {
-    onHorizontalScroll(tableContentRef.current);
+    onTableHorizontalScroll(tableContentRef.current);
   };
 
   const onFootMouseEnter = () => {
@@ -173,7 +200,7 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
       on(horizontalScrollbarRef.current, 'mouseleave', onScrollbarMouseLeave);
     }
 
-    if ((isAffixed || isVirtualScroll) && tableContentRef.current) {
+    if (isAffixed && tableContentRef.current) {
       on(tableContentRef.current, 'mouseenter', onTableContentMouseEnter);
       on(tableContentRef.current, 'mouseleave', onTableContentMouseLeave);
     }
@@ -198,14 +225,14 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
     }
   };
 
-  const addVerticalScrollListener = () => {
+  const addPageScrollListener = () => {
     if (typeof document === 'undefined') return;
     if (!isAffixed && !props.paginationAffixedBottom) return;
     const timer = setTimeout(() => {
       if (isAffixed || props.paginationAffixedBottom) {
-        on(document, 'scroll', onDocumentScroll);
+        on(document, 'scroll', onPageScroll);
       } else {
-        off(document, 'scroll', onDocumentScroll);
+        off(document, 'scroll', onPageScroll);
       }
       clearTimeout(timer);
     });
@@ -214,26 +241,28 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
   useEffect(() => {
     const timer = setTimeout(() => {
       addHorizontalScrollListeners();
-      onHorizontalScroll();
+      onTableHorizontalScroll();
       updateAffixHeaderOrFooter();
       clearTimeout(timer);
     });
-
-    return removeHorizontalScrollListeners;
+    return () => {
+      removeHorizontalScrollListeners();
+    };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [affixHeaderRef, affixFooterRef, horizontalScrollbarRef, tableContentRef, showElement]);
+  }, [affixHeaderRef, affixFooterRef, horizontalScrollbarRef, tableContentRef, showElement, props.fixedRows]);
 
   useEffect(() => {
-    addVerticalScrollListener();
+    addPageScrollListener();
     return () => {
-      off(document, 'scroll', onDocumentScroll);
+      if (typeof document === 'undefined') return;
+      off(document, 'scroll', onPageScroll);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isAffixed]);
+  }, [isAffixed, props.fixedRows]);
 
   useEffect(() => {
     addHorizontalScrollListeners();
-    onHorizontalScroll();
+    onTableHorizontalScroll();
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     props.data,
@@ -242,11 +271,12 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
     props.footerAffixedBottom,
     props.horizontalScrollAffixedBottom,
     props.lazyLoad,
+    props.fixedRows,
   ]);
 
   const setTableContentRef = (tableContent: HTMLDivElement) => {
     tableContentRef.current = tableContent;
-    addVerticalScrollListener();
+    addPageScrollListener();
   };
 
   return {
@@ -257,7 +287,7 @@ export default function useAffix(props: TdBaseTableProps, { showElement }: { sho
     affixFooterRef,
     horizontalScrollbarRef,
     paginationRef,
-    onHorizontalScroll,
+    onTableHorizontalScroll,
     setTableContentRef,
     updateAffixHeaderOrFooter,
   };
diff --git a/test/snap/__snapshots__/csr.test.jsx.snap b/test/snap/__snapshots__/csr.test.jsx.snap
diff --git a/test/snap/__snapshots__/ssr.test.jsx.snap b/test/snap/__snapshots__/ssr.test.jsx.snap
