fix(animation): carousel fails to scroll to bottom with fractional row heights

common/changes/@visactor/vtable-plugins/fix-carousel-boundary_2026-10-09-02-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix(vtable-plugins): restart carousel scrolling at the row and column boundaries with fractional dimensions",
+      "type": "patch",
+      "packageName": "@visactor/vtable-plugins"
+    }
+  ],
+  "packageName": "@visactor/vtable-plugins",
+  "email": "mikewushuwen@outlook.com"
+}

common/changes/@visactor/vtable/fix-carousel-scroll-correction_2026-10-09-02-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix(vtable): preserve fractional animated scroll targets and cancel column correction when the table is released",
+      "type": "patch",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "mikewushuwen@outlook.com"
+}

packages/vtable-plugins/src/table-carousel-animation.ts

@@ -101,6 +101,9 @@ export class TableCarouselAnimationPlugin implements pluginsDefinition.IVTablePl
     if (customRow) {
       this.row = customRow.distRow;
       animation = customRow.animation ?? true;
+    } else if (this.row >= this.table.rowCount - 1) {
+      this.row = this.table.frozenRowCount;
+      animation = false;
     } else if (isInteger(this.row) && screenTopRow !== this.row) {
       this.row = this.table.frozenRowCount;
       animation = false;
@@ -120,7 +123,6 @@ export class TableCarouselAnimationPlugin implements pluginsDefinition.IVTablePl
         this.willUpdateRow = false;
         this.updateRow();
       },
-      // animation ? this.animationDuration + this.animationDelay : 0
       this.animationDuration + this.animationDelay
     );
   }
@@ -135,6 +137,9 @@ export class TableCarouselAnimationPlugin implements pluginsDefinition.IVTablePl
     if (customCol) {
       this.col = customCol.distCol;
       animation = customCol.animation ?? true;
+    } else if (this.col >= this.table.colCount - 1) {
+      this.col = this.table.frozenColCount;
+      animation = false;
     } else if (isInteger(this.col) && this.table.scenegraph.proxy.screenLeftCol !== this.col) {
       this.col = this.table.frozenColCount;
       animation = false;
@@ -156,7 +161,6 @@ export class TableCarouselAnimationPlugin implements pluginsDefinition.IVTablePl
         this.willUpdateCol = false;
         this.updateCol();
       },
-      // animation ? this.animationDuration + this.animationDelay : 0
       this.animationDuration + this.animationDelay
     );
   }

packages/vtable/__tests__/api/listTable-scrollToRow.test.ts

@@ -10,27 +10,88 @@ describe('listTable scrollToRow api', () => {
     document.body.innerHTML = '';
   });
 
-  test('keeps fractional row target when scrolling with animation', () => {
+  test.each(['row', 'col'])('keeps fractional %s target when scrolling with animation', axis => {
     const container = createDiv();
     container.style.position = 'relative';
     container.style.width = '400px';
     container.style.height = '240px';
 
     const table = new ListTable({
       container,
-      columns: [{ field: 'name', title: 'Name', width: 120 }],
+      columns: Array.from({ length: 8 }, (_, index) => ({ field: `name${index}`, title: 'Name', width: 120 })),
       records: Array.from({ length: 20 }, (_, index) => ({ name: `row-${index}` })),
       defaultRowHeight: 40
     });
 
     const scrollTo = jest.spyOn(table.animationManager, 'scrollTo').mockImplementation(() => undefined);
     const setTimeoutSpy = jest.spyOn(globalThis, 'setTimeout').mockImplementation(() => 0 as any);
 
-    table.scrollToRow(1.5, { duration: 100, easing: 'linear' });
+    if (axis === 'row') {
+      table.scrollToRow(1.5, { duration: 100, easing: 'linear' });
+    } else {
+      table.scrollToCol(1.5, { duration: 100, easing: 'linear' });
+    }
 
-    expect(scrollTo).toHaveBeenCalledWith({ row: 1.5 }, { duration: 100, easing: 'linear' });
+    expect(scrollTo).toHaveBeenCalledWith({ [axis]: 1.5 }, { duration: 100, easing: 'linear' });
     expect(setTimeoutSpy).not.toHaveBeenCalled();
 
     table.release();
   });
+
+  test('renders once after animated column correction', () => {
+    const table = Object.create(Object.getPrototypeOf(ListTable.prototype));
+    table._scrollToColCorrectTimer = null;
+    table.isReleased = false;
+    table.clearColCorrectTimer = jest.fn();
+    table.animationManager = { scrollTo: jest.fn() };
+    const callbacks = [];
+    jest.spyOn(globalThis, 'setTimeout').mockImplementation(callback => {
+      callbacks.push(callback);
+      return callbacks.length as any;
+    });
+    const render = jest.fn();
+    const scrollToCell = jest.fn(() => render());
+    table.render = render;
+    table.scrollToCell = scrollToCell;
+
+    table.scrollToCol(2, { duration: 100 });
+    callbacks[0]();
+
+    expect(scrollToCell).toHaveBeenCalledWith({ col: 2 });
+    expect(render).toHaveBeenCalledTimes(1);
+  });
+
+  test('cancels column correction on replacement and release, and ignores a late callback', () => {
+    const container = createDiv();
+    container.style.width = '400px';
+    container.style.height = '240px';
+    const table = new ListTable({
+      container,
+      columns: Array.from({ length: 8 }, (_, index) => ({ field: `name${index}`, title: 'Name', width: 120 })),
+      records: [{ name0: 'first' }]
+    });
+    jest.spyOn(table.animationManager, 'scrollTo').mockImplementation(() => undefined);
+    const callbacks = [];
+    const setTimeoutSpy = jest.spyOn(globalThis, 'setTimeout').mockImplementation(callback => {
+      callbacks.push(callback);
+      return callbacks.length as any;
+    });
+    const clearTimeoutSpy = jest.spyOn(globalThis, 'clearTimeout');
+
+    table.scrollToCol(2, { duration: 100 });
+    expect(setTimeoutSpy).toHaveBeenCalledTimes(1);
+    const firstHandle = table._scrollToColCorrectTimer;
+    table.scrollToCol(3, { duration: 100 });
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(firstHandle);
+    const releaseHandle = table._scrollToColCorrectTimer;
+    table.release();
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(releaseHandle);
+    expect(table._scrollToColCorrectTimer).toBeNull();
+
+    const scrollToCell = jest.spyOn(table, 'scrollToCell');
+    const render = jest.spyOn(table, 'render');
+    callbacks[1]();
+    expect(scrollToCell).not.toHaveBeenCalled();
+    expect(render).not.toHaveBeenCalled();
+  });
 });

packages/vtable/src/core/BaseTable.ts

@@ -176,6 +176,7 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
   internalProps: IBaseTableProtected;
   showFrozenIcon = true;
   _scrollToRowCorrectTimer: ReturnType<typeof setTimeout> | null = null;
+  _scrollToColCorrectTimer: ReturnType<typeof setTimeout> | null = null;
   padding: { top: number; left: number; right: number; bottom: number };
   globalDropDownMenu?: MenuListItem[] | ((args: { row: number; col: number; table: BaseTableAPI }) => MenuListItem[]);
   //画布绘制单元格的区域 不包括整体边框frame，所以比canvas的width和height要小一点（canvas的width包括了frame）
@@ -2671,6 +2672,13 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
     }
   }
 
+  private clearColCorrectTimer() {
+    if (this._scrollToColCorrectTimer !== null) {
+      clearTimeout(this._scrollToColCorrectTimer);
+      this._scrollToColCorrectTimer = null;
+    }
+  }
+
   /**
    * Dispose the table instance.
    * @returns {void}
@@ -2726,6 +2734,7 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
       delete element.__vtable_id__;
     }
     this.clearCorrectTimer();
+    this.clearColCorrectTimer();
     internalProps.tooltipHandler?.release?.();
     internalProps.menuHandler?.release?.();
 
@@ -5285,6 +5294,9 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
   private _scheduleScrollToRowCorrect(row: number, delay: number = 0) {
     this._scrollToRowCorrectTimer = setTimeout(() => {
       this.clearCorrectTimer();
+      if (this.isReleased) {
+        return;
+      }
       const targetScrollTop = this.getTargetScrollTop(row);
       if (targetScrollTop !== this.scrollTop) {
         this.scrollTop = targetScrollTop;
@@ -5311,16 +5323,29 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
     this.animationManager.scrollTo({ row: targetRow }, animationOption);
     if (targetRowInt === targetRow) {
       this._scrollToRowCorrectTimer = setTimeout(() => {
-        this.scrollToRow(targetRowInt, false);
+        this._scrollToRowCorrectTimer = null;
+        if (!this.isReleased) {
+          this.scrollToRow(targetRowInt, false);
+        }
       }, duration);
     }
   }
   scrollToCol(col: number, animationOption?: ITableAnimationOption | boolean) {
+    this.clearColCorrectTimer();
     if (!animationOption) {
       this.scrollToCell({ col });
       return;
     }
+    const duration = !isBoolean(animationOption) ? animationOption?.duration ?? 3000 : 3000;
     this.animationManager.scrollTo({ col }, animationOption);
+    if (Math.floor(col) === col) {
+      this._scrollToColCorrectTimer = setTimeout(() => {
+        this._scrollToColCorrectTimer = null;
+        if (!this.isReleased) {
+          this.scrollToCell({ col });
+        }
+      }, duration);
+    }
   }
   /**
    * 滚动到具体某个单元格位置

packages/vtable/src/core/animation.ts

@@ -10,11 +10,11 @@ function isInteger(value: number) {
 class Animateaaa extends ACustomAnimate<any> {
   onUpdate(end: boolean, ratio: number, out: Record<string, any>): void {
     if (this.from.x !== this.to.x) {
-      const x = end ? this.to.x : this.from.x + Math.floor((this.to.x - this.from.x) * ratio);
+      const x = end ? this.to.x : this.from.x + Math.round((this.to.x - this.from.x) * ratio);
       this.params.table.scrollLeft = x;
     }
     if (this.from.y !== this.to.y) {
-      const y = end ? this.to.y : this.from.y + Math.floor((this.to.y - this.from.y) * ratio);
+      const y = end ? this.to.y : this.from.y + Math.round((this.to.y - this.from.y) * ratio);
       this.params.table.scrollTop = y;
     }
   }