fix: virtual table scrollTo align support

- Add VirtualScrollConfig type with Exclude<ScrollLogicalPosition, 'center'>
- Implement align mapping for virtual table (start->top, end->bottom, nearest->auto)
- Add default align 'auto' when neither align nor offset provided
- Add backward compatibility: default to 'top' when offset provided but align not
- Update tests to cover align parameter scenarios
- Fix offset JSDoc comment

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 刘欢

src/VirtualTable/BodyGrid.tsx

@@ -3,7 +3,12 @@ import VirtualList, { type ListProps, type ListRef } from '@rc-component/virtual
 import * as React from 'react';
 import TableContext, { responseImmutable } from '../context/TableContext';
 import useFlattenRecords, { type FlattenData } from '../hooks/useFlattenRecords';
-import type { ColumnType, OnCustomizeScroll, ScrollConfig } from '../interface';
+import type {
+  ColumnType,
+  OnCustomizeScroll,
+  ScrollConfig,
+  VirtualScrollConfig,
+} from '../interface';
 import BodyLine from './BodyLine';
 import { GridContext, StaticContext } from './context';
 
@@ -79,15 +84,22 @@ const Grid = React.forwardRef<GridRef, GridProps>((props, ref) => {
   // =========================== Ref ============================
   React.useImperativeHandle(ref, () => {
     const obj = {
-      scrollTo: (config: ScrollConfig) => {
-        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);
-        }
+      scrollTo: (config: VirtualScrollConfig) => {
+        const { align, offset, ...restConfig } = config;
+
+        const alignMap: Record<string, 'top' | 'bottom' | 'auto'> = {
+          start: 'top',
+          end: 'bottom',
+          nearest: 'auto',
+        };
+
+        const virtualAlign = align ? alignMap[align] : offset ? 'top' : 'auto';
+
+        listRef.current?.scrollTo({
+          ...restConfig,
+          offset,
+          align: virtualAlign,
+        });
       },
       nativeElement: listRef.current?.nativeElement,
     } as unknown as GridRef;

src/interface.ts

@@ -40,13 +40,17 @@ export type ScrollConfig = {
    * 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 be aligned according to the `align` parameter.
+   * In `key` / `index` mode, `offset` is added to the position resolved by `align`.
    */
   offset?: number;
 
   align?: ScrollLogicalPosition;
 };
 
+export type VirtualScrollConfig = ScrollConfig & {
+  align?: Exclude<ScrollLogicalPosition, 'center'>;
+};
+
 export type Reference = {
   nativeElement: HTMLDivElement;
   scrollTo: (config: ScrollConfig) => void;

tests/Virtual.spec.tsx

@@ -373,6 +373,7 @@ describe('Table.Virtual', () => {
 
     expect(global.scrollToConfig).toEqual({
       index: 99,
+      align: 'auto',
     });
   });
 
@@ -423,6 +424,31 @@ describe('Table.Virtual', () => {
     });
   });
 
+  it('scrollTo with align should pass', async () => {
+    const tblRef = React.createRef<Reference>();
+    getTable({ ref: tblRef });
+
+    // align start -> top
+    tblRef.current.scrollTo({ index: 50, align: 'start' });
+    await waitFakeTimer();
+    expect(global.scrollToConfig).toEqual({ index: 50, align: 'top' });
+
+    // align end -> bottom
+    tblRef.current.scrollTo({ index: 50, align: 'end' });
+    await waitFakeTimer();
+    expect(global.scrollToConfig).toEqual({ index: 50, align: 'bottom' });
+
+    // align nearest -> auto
+    tblRef.current.scrollTo({ index: 50, align: 'nearest' });
+    await waitFakeTimer();
+    expect(global.scrollToConfig).toEqual({ index: 50, align: 'auto' });
+
+    // offset + align
+    tblRef.current.scrollTo({ index: 50, offset: 20, align: 'end' });
+    await waitFakeTimer();
+    expect(global.scrollToConfig).toEqual({ index: 50, offset: 20, align: 'bottom' });
+  });
+
   describe('auto width', () => {
     async function prepareTable(columns: any[]) {
       const { container } = getTable({