Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(sheets-ui): scrolling supports setting animation duration (#6012)

wpxp1234569e09ccec6738
diff --git a/packages/sheets-ui/src/commands/commands/set-scroll.command.ts b/packages/sheets-ui/src/commands/commands/set-scroll.command.ts
index 049205f4c8..ed84dd9681 100644
--- a/packages/sheets-ui/src/commands/commands/set-scroll.command.ts
+++ b/packages/sheets-ui/src/commands/commands/set-scroll.command.ts
@@ -45,6 +45,11 @@ export interface IScrollCommandParams {
* e.g. if scrolled about 2 columns, now left is E, then sheetViewStartColumn is 2.
*/
sheetViewStartColumn?: number;
+
+ /**
+ * The duration of the scroll animation in milliseconds.
+ */
+ duration?: number;
}
/**
@@ -120,7 +125,7 @@ export const ScrollCommand: ICommand<IScrollCommandParams> = {
return false;
}
- const { sheetViewStartRow, sheetViewStartColumn, offsetX, offsetY } = params;
+ const { sheetViewStartRow, sheetViewStartColumn, offsetX, offsetY, duration } = params;
const {
sheetViewStartColumn: currentColumn,
sheetViewStartRow: currentRow,
@@ -140,6 +145,7 @@ export const ScrollCommand: ICommand<IScrollCommandParams> = {
sheetViewStartColumn: sheetViewStartColumn ?? (currentColumn ?? 0 + xSplit),
offsetX: offsetX ?? currentOffsetX,
offsetY: offsetY ?? currentOffsetY,
+ duration,
});
},
};
diff --git a/packages/sheets-ui/src/commands/operations/scroll.operation.ts b/packages/sheets-ui/src/commands/operations/scroll.operation.ts
index 039b14f49f..a345b4890a 100644
--- a/packages/sheets-ui/src/commands/operations/scroll.operation.ts
+++ b/packages/sheets-ui/src/commands/operations/scroll.operation.ts
@@ -31,7 +31,7 @@ export const SetScrollOperation: IOperation<IScrollStateWithSearchParam> = {
}
// freeze is handled by set-scroll.command.ts
- const { unitId, sheetId, offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = params;
+ const { unitId, sheetId, offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow, duration } = params;
const renderManagerService = accessor.get(IRenderManagerService);
const scrollManagerService = renderManagerService.getRenderById(unitId)!.with(SheetScrollManagerService);
// const currentService = accessor.get(IUniverInstanceService);
@@ -46,6 +46,7 @@ export const SetScrollOperation: IOperation<IScrollStateWithSearchParam> = {
offsetY,
sheetViewStartRow,
sheetViewStartColumn,
+ duration,
});
return true;
diff --git a/packages/sheets-ui/src/controllers/render-controllers/scroll.render-controller.ts b/packages/sheets-ui/src/controllers/render-controllers/scroll.render-controller.ts
index a0f3b03c59..a1e925389c 100644
--- a/packages/sheets-ui/src/controllers/render-controllers/scroll.render-controller.ts
+++ b/packages/sheets-ui/src/controllers/render-controllers/scroll.render-controller.ts
@@ -15,7 +15,7 @@
*/
import type { IFreeze, IRange, IWorksheetData, Nullable, Workbook } from '@univerjs/core';
-import type { IRenderContext, IRenderModule, IScrollObserverParam, IWheelEvent } from '@univerjs/engine-render';
+import type { IRenderContext, IRenderModule, IScrollObserverParam, IWheelEvent, Viewport } from '@univerjs/engine-render';
import type { IScrollToCellOperationParams, ISetSelectionsOperationParams, SheetsSelectionsService } from '@univerjs/sheets';
import type { IScrollCommandParams } from '../../commands/commands/set-scroll.command';
import type { IExpandSelectionCommandParams } from '../../commands/commands/set-selection.command';
@@ -141,7 +141,7 @@ export class SheetsScrollRenderController extends Disposable implements IRenderM
}
// prev scrolling state from rawScrollInfo$
- const { sheetViewStartRow, sheetViewStartColumn, offsetX, offsetY } = rawScrollInfo;
+ const { sheetViewStartRow, sheetViewStartColumn, offsetX, offsetY, duration } = rawScrollInfo;
const { startX, startY } = skeleton.getCellWithCoordByIndex(
sheetViewStartRow,
@@ -152,7 +152,11 @@ export class SheetsScrollRenderController extends Disposable implements IRenderM
const viewportScrollX = startX + offsetX;
const viewportScrollY = startY + offsetY;
- viewportMain.scrollToViewportPos({ viewportScrollX, viewportScrollY });
+ if (!duration) {
+ viewportMain.scrollToViewportPos({ viewportScrollX, viewportScrollY });
+ } else {
+ this._smoothScrollToViewportPos({ viewportMain, viewportScrollX, viewportScrollY, duration });
+ }
})
)
);
@@ -262,6 +266,35 @@ export class SheetsScrollRenderController extends Disposable implements IRenderM
));
}
+ _smoothScrollToViewportPos(params: { viewportMain: Viewport; viewportScrollX: number; viewportScrollY: number; duration: number }) {
+ const { viewportMain, viewportScrollX, viewportScrollY, duration } = params;
+ const startTime = performance.now();
+ const startX = viewportMain.viewportScrollX;
+ const startY = viewportMain.viewportScrollY;
+ const offsetX = viewportScrollX - startX;
+ const offsetY = viewportScrollY - startY;
+
+ function animate(now: number) {
+ const elapsed = now - startTime;
+ const progress = Math.min(elapsed / duration, 1); // 0 → 1
+ const ease = 1 - (1 - progress) ** 3; // cubic easing
+
+ const currentX = startX + offsetX * ease;
+ const currentY = startY + offsetY * ease;
+
+ viewportMain.scrollToViewportPos({
+ viewportScrollX: currentX,
+ viewportScrollY: currentY,
+ });
+
+ if (progress < 1) {
+ requestAnimationFrame(animate);
+ }
+ }
+
+ requestAnimationFrame(animate);
+ }
+
_updateViewportScroll(viewportScrollX: number = 0, viewportScrollY: number = 0) {
const sheetObject = this._getSheetObject();
if (!sheetObject) return;
@@ -318,7 +351,7 @@ export class SheetsScrollRenderController extends Disposable implements IRenderM
* @param {number} column - Cell column
* @returns {boolean} - true if scroll is successful
*/
- scrollToCell(row: number, column: number) {
+ scrollToCell(row: number, column: number, duration?: number): boolean {
const worksheet = this._context.unit.getActiveSheet();
const {
ySplit: freezeYSplit,
@@ -329,6 +362,7 @@ export class SheetsScrollRenderController extends Disposable implements IRenderM
sheetViewStartColumn: column - freezeXSplit,
offsetX: 0,
offsetY: 0,
+ duration,
});
}
diff --git a/packages/sheets-ui/src/facade/f-worksheet.ts b/packages/sheets-ui/src/facade/f-worksheet.ts
index 499b859c56..dffc033e76 100644
--- a/packages/sheets-ui/src/facade/f-worksheet.ts
+++ b/packages/sheets-ui/src/facade/f-worksheet.ts
@@ -89,6 +89,7 @@ export interface IFWorksheetSkeletonMixin {
* Based on the limitations of viewport and the number of rows and columns, you can only scroll to the maximum scrollable range.
* @param {number} row - Cell row index
* @param {number} column - Cell column index
+ * @param {number} [duration] - The duration of the scroll animation in milliseconds.
* @returns {FWorksheet} - The FWorksheet instance for chaining.
* @example
* ```ts
@@ -102,7 +103,7 @@ export interface IFWorksheetSkeletonMixin {
* fWorksheet.scrollToCell(row, column);
* ```
*/
- scrollToCell(row: number, column: number): FWorksheet;
+ scrollToCell(row: number, column: number, duration?: number): FWorksheet;
/**
* Get scroll state of current sheet.
@@ -352,13 +353,13 @@ export class FWorksheetSkeletonMixin extends FWorksheet implements IFWorksheetSk
return range;
}
- override scrollToCell(row: number, column: number): FWorksheet {
+ override scrollToCell(row: number, column: number, duration?: number): FWorksheet {
const unitId = this._workbook.getUnitId();
const renderManagerService = this._injector.get(IRenderManagerService);
const render = renderManagerService.getRenderById(unitId);
if (render) {
const scrollRenderController = render?.with(SheetsScrollRenderController);
- scrollRenderController.scrollToCell(row, column);
+ scrollRenderController.scrollToCell(row, column, duration);
}
return this;
}
diff --git a/packages/sheets-ui/src/services/scroll-manager.service.ts b/packages/sheets-ui/src/services/scroll-manager.service.ts
index cb453093e3..fee542e5c5 100644
--- a/packages/sheets-ui/src/services/scroll-manager.service.ts
+++ b/packages/sheets-ui/src/services/scroll-manager.service.ts
@@ -45,6 +45,11 @@ export interface IScrollState {
* e.g. If column A ~ C is frozen, the first column of viewMain is D, but sheetViewStartColumn still 0.
*/
sheetViewStartColumn: number;
+
+ /**
+ * The duration of the scroll animation in milliseconds.
+ */
+ duration?: number;
}
export interface IViewportScrollState extends IScrollState {