feat: Table scrollTo support offset (#1301)

* feat: support offset

* test: add test case

* chore: align with virtual

Author: zombieJ

docs/examples/scrollY.tsx

@@ -3,7 +3,7 @@ import React from 'react';
 import '../../assets/index.less';
 
 const data = [];
-for (let i = 0; i < 10; i += 1) {
+for (let i = 0; i < 20; i += 1) {
   data.push({
     key: i,
     a: `a${i}`,
@@ -68,6 +68,26 @@ const Test = () => {
       >
         Scroll To top
       </button>
+      <button
+        onClick={() => {
+          tblRef.current?.scrollTo({
+            index: 5,
+            offset: -10,
+          });
+        }}
+      >
+        Scroll To Index 5 + Offset -10
+      </button>
+      <button
+        onClick={() => {
+          tblRef.current?.scrollTo({
+            key: 6,
+            offset: -10,
+          });
+        }}
+      >
+        Scroll To Key 6 + Offset -10
+      </button>
       <Table
         ref={tblRef}
         columns={columns}

docs/examples/virtual.tsx

@@ -199,6 +199,12 @@ const Demo: React.FC = () => {
       <button onClick={() => tableRef.current?.scrollTo({ index: data.length - 1 })}>
         Scroll To Key
       </button>
+      <button onClick={() => tableRef.current?.scrollTo({ index: 10, offset: -10 })}>
+        Scroll To Index 10 + Offset -10
+      </button>
+      <button onClick={() => tableRef.current?.scrollTo({ key: '50', offset: -10 })}>
+        Scroll To Key 50 + Offset -10
+      </button>
       <VirtualTable
         style={{ marginTop: 16 }}
         ref={tableRef}

src/Table.tsx

@@ -342,12 +342,26 @@ function Table<RecordType extends DefaultRecordType>(
       scrollTo: config => {
         if (scrollBodyRef.current instanceof HTMLElement) {
           // Native scroll
-          const { index, top, key } = config;
+          const { index, top, key, offset } = config;
+
           if (validNumberValue(top)) {
+            // In top mode, offset is ignored
             scrollBodyRef.current?.scrollTo({ top });
           } else {
             const mergedKey = key ?? getRowKey(mergedData[index]);
-            scrollBodyRef.current.querySelector(`[data-row-key="${mergedKey}"]`)?.scrollIntoView();
+            const targetElement = scrollBodyRef.current.querySelector(
+              `[data-row-key="${mergedKey}"]`,
+            );
+            if (targetElement) {
+              if (!offset) {
+                // No offset, use scrollIntoView for default behavior
+                targetElement.scrollIntoView();
+              } else {
+                // With offset, use element's offsetTop + offset
+                const elementTop = (targetElement as HTMLElement).offsetTop;
+                scrollBodyRef.current.scrollTo({ top: elementTop + offset });
+              }
+            }
           }
         } else if ((scrollBodyRef.current as any)?.scrollTo) {
           // Pass to proxy

src/VirtualTable/BodyGrid.tsx

@@ -78,7 +78,18 @@ const Grid = React.forwardRef<GridRef, GridProps>((props, ref) => {
   React.useImperativeHandle(ref, () => {
     const obj = {
       scrollTo: (config: ScrollConfig) => {
-        listRef.current?.scrollTo(config);
+        const { offset, ...restConfig } = config;
+
+        // If offset is provided, force align to 'top' for consistent behavior
+        if (offset) {
+          listRef.current?.scrollTo({
+            ...restConfig,
+            offset,
+            align: 'top',
+          });
+        } else {
+          listRef.current?.scrollTo(config);
+        }
       },
       nativeElement: listRef.current?.nativeElement,
     } as unknown as GridRef;

src/interface.ts

@@ -30,9 +30,19 @@ export type DefaultRecordType = Record<string, any>;
 export type TableLayout = 'auto' | 'fixed';
 
 export type ScrollConfig = {
+  /** The index of the row to scroll to */
   index?: number;
+  /** The key of the row to scroll to */
   key?: Key;
+  /** The absolute scroll position from top */
   top?: number;
+  /**
+   * Additional offset in pixels to apply to the scroll position.
+   * Only effective when using `key` or `index` mode.
+   * Ignored when using `top` mode.
+   * When offset is set, the target element will always be aligned to the top of the container.
+   */
+  offset?: number;
 };
 
 export type Reference = {

tests/Virtual.spec.tsx

@@ -368,6 +368,53 @@ describe('Table.Virtual', () => {
     });
   });
 
+  it('scrollTo with offset should pass', async () => {
+    const tblRef = React.createRef<Reference>();
+    getTable({ ref: tblRef });
+
+    // Test index with offset
+    tblRef.current.scrollTo({
+      index: 50,
+      offset: 20,
+    });
+
+    await waitFakeTimer();
+
+    expect(global.scrollToConfig).toEqual({
+      index: 50,
+      offset: 20,
+      align: 'top',
+    });
+
+    // Test key with offset
+    tblRef.current.scrollTo({
+      key: '25',
+      offset: -10,
+    });
+
+    await waitFakeTimer();
+
+    expect(global.scrollToConfig).toEqual({
+      key: '25',
+      offset: -10,
+      align: 'top',
+    });
+
+    // Test top with offset (offset should be passed to virtual list)
+    tblRef.current.scrollTo({
+      top: 100,
+      offset: 30,
+    });
+
+    await waitFakeTimer();
+
+    expect(global.scrollToConfig).toEqual({
+      top: 100,
+      offset: 30,
+      align: 'top',
+    });
+  });
+
   describe('auto width', () => {
     async function prepareTable(columns: any[]) {
       const { container } = getTable({

tests/refs.spec.tsx

@@ -62,4 +62,51 @@ describe('Table.Ref', () => {
     });
     expect(scrollIntoViewElement.textContent).toEqual('bamboo');
   });
+
+  it('support scrollTo with offset', () => {
+    const ref = React.createRef<Reference>();
+
+    render(
+      <Table
+        data={[{ key: 'light' }, { key: 'bamboo' }]}
+        columns={[
+          {
+            dataIndex: 'key',
+          },
+        ]}
+        ref={ref}
+        scroll={{
+          y: 10,
+        }}
+      />,
+    );
+
+    // Scroll To top with offset should ignore offset
+    ref.current.scrollTo({
+      top: 100,
+      offset: 50,
+    });
+    expect(scrollParam.top).toEqual(100); // offset ignored
+
+    // Scroll index with offset
+    ref.current.scrollTo({
+      index: 0,
+      offset: 30,
+    });
+    expect(scrollParam.top).toEqual(30); // offsetTop (0) + offset (30)
+
+    // Scroll key with offset
+    ref.current.scrollTo({
+      key: 'bamboo',
+      offset: 20,
+    });
+    expect(scrollParam.top).toEqual(20); // offsetTop (0) + offset (20)
+
+    // Scroll index without offset should use scrollIntoView
+    scrollIntoViewElement = null;
+    ref.current.scrollTo({
+      index: 0,
+    });
+    expect(scrollIntoViewElement.textContent).toEqual('light');
+  });
 });